AI Three-Stage Pipeline: A Practical Workflow for Small-Team Web Admin System Development

1. Problem: The Three Structural Tensions in Small-Team Admin System Development

Internal web admin systems in small and medium-sized businesses often share a common pattern: few people, many modules, and frequent change.

Typically, only two or three developers must maintain a dozen or more modules, including user and permission management, organization and personnel management, approval workflows, reporting and statistics, and data import/export. Business requirements are often introduced through short verbal descriptions. One day, the team is told that an approval requires two levels; the next day, the rule changes so that amounts below a threshold require only one level.

Every requirement change can create a chain of downstream modifications across entity definitions, database fields, API contracts, form validation, list filters, permission configurations, and other locations.

Under these constraints, the team faces three unavoidable tensions:

• Headcount does not match the number of modules. Highly repetitive code such as create, read, update, and delete operations consumes a large amount of engineering time, squeezing out the time needed for the business logic that actually requires human judgment.
• Regression testing costs become unmanageable. Every change requires manual page-by-page verification. If one area is modified, many other areas must be checked, and testing time grows non-linearly with the number of modules.
• Boundary scenarios are systematically missed. Cases such as a zero amount, an empty list, concurrent submission of the same record, overly long fields, or unauthorized access to another user’s data are easily missed during requirements review and easily overlooked during testing.

The purpose of introducing AI-assisted development is mainly to address the repetitive labor segment. However, in practice, directly giving a vague requirement to a model and asking it to generate an entire module in one pass usually fails. The context expands rapidly, generated results contradict each other, the code may run but does not conform to team conventions, and the cost of review and rework can become higher than writing the code manually.

Therefore, the effective approach is not simply “using AI to write code.” It is to place AI inside a pipeline with clear inputs and outputs, quality gates, and human confirmation points.

2. Overall Pipeline Design

The pipeline uses a three-stage serial structure. Each stage produces the sole input contract for the next stage:

Stage 1  Requirements and Design  →  Stage 2  Coding Implementation  →  Stage 3  Testing and Validation
   Document-first                     Rule-constrained code generation    Quality gates + failure loops
        ↓                                      ↓                                  ↓
  Human review and confirmation        Human spot-check of critical logic   Human acceptance of business semantics

Three design principles apply throughout the pipeline:

1. Documents act as contracts. Information is transferred between stages only through documents, not through conversation context. This prevents context length from growing linearly with task size and allows any stage to be rerun independently.
2. Rules are externalized. Team coding style, layering conventions, and naming habits should not depend on reminding the model every time. They should be fixed as rule files in the repository and treated as versioned, reviewable engineering assets.
3. Failures must loop back. When testing fails, the task is not allowed to “end in place.” Instead, it enters a closed loop of root-cause analysis, repair, and regression testing. If test coverage is incomplete, the loop is not considered complete.

3. Stage One: Requirements and Design — Eliminate Uncertainty Before Writing Code

The only goal of this stage is: expose all ambiguities, boundary conditions, and rule conflicts in the requirements before writing a single line of code. AI does not write code at this stage. Its role is to act as a tireless design assistant that expands a verbal requirement into structured documentation, while humans make decisions and confirm trade-offs.

The required deliverables include five categories:

Deliverable	Core content	Why it is required
Requirements specification	Business background, roles, scope, non-goals	Defines what to do and what explicitly not to do
Use case specification	Preconditions, main flow, exception flows, postconditions	Forces branch analysis and avoids happy-path thinking
Data model design	Entities, fields, types, lengths, constraints, indexes, state machines	Locks down the schema early and avoids repeated migrations later
API contract	Paths, methods, request parameters, response parameters, error codes, pagination and sorting rules	Prerequisite for parallel frontend and backend development
Menu and permission design	Menu tree, role mapping, button-level permission points, data visibility scope	Permissions are a high-risk area in admin systems

The most important practice in this stage is business rule numbering. Each business constraint is assigned a unique identifier. For example:

Rule ID	Rule description	Trigger scenario	Result when the rule is triggered
BR-001	Single-level approval is used when the reimbursement amount is CNY 5,000 or less	Submit for approval	Generates a single approval task
BR-002	Two-level approval is required when the amount exceeds CNY 5,000	Submit for approval	Generates two approval tasks
BR-003	The same applicant cannot submit duplicate requests for the same reason within 24 hours	Submit for approval	Returns a business validation error code

The benefit of numbering is traceability. Every piece of generated code is required to include a comment identifying which rule it implements. Every test case identifies which rule it verifies. Review comments can directly reference rule IDs. When the business side proposes a change, the team can directly locate “BR-002 needs adjustment,” quickly assess the impact scope, and avoid rereading all the code.

The decisions that humans must make in this stage include scope trimming, state-machine values, field lengths and precision, permission granularity, and whether to use soft deletion or hard deletion. If these decisions are wrong, the error will be amplified in all later stages. Therefore, they must be confirmed by humans before the next stage begins.

4. Stage Two: Coding Implementation — Separate Greenfield Generation from Existing-Code Changes

The input to the coding stage is the design documentation. The output is backend source code, frontend page code, and database change scripts.

The most commonly overlooked but highest-impact design decision in this stage is: separate “greenfield generation” from “existing-code changes” into two different processing paths.

4.1 Greenfield Generation Mode

This mode applies to a module that did not previously exist. It proceeds in fixed steps, and each step produces a separately reviewable artifact:

Step 1  Read the design documents, extract the entity, API, and permission-point inventory, and output an implementation plan
Step 2  Generate the data access layer and domain logic: entities, mappers, services, DTOs
Step 3  Generate the API layer: controllers, parameter validation, unified responses, error-code mapping
Step 4  Generate frontend pages: list, form, detail, routes, and menu registration
Step 5  Generate database scripts: table creation, indexes, initialization dictionary data, repeatable execution
Step 6  Compile and run static checks; fix obvious errors before delivery

The key constraint is “plan first, then generate.” Ask the model to first output a list of affected files. After humans confirm the list, implementation can begin. This prevents the model from creating a large number of unplanned files on its own.

4.2 Existing-Code Change Mode

This is the more common and higher-risk scenario in daily work: modifying a field, adding an approval node, or adjusting a validation rule. If the model is asked to “regenerate the entire module,” it will almost certainly overwrite existing business customizations.

The correct approach for existing-code changes is to perform impact analysis first, then apply minimal incremental changes:

Input: change description + design documents + existing code index
Step 1  Retrieve affected files: entities, mapper XML, services, controllers, frontend API modules, page components, routes, permission points
Step 2  Output a change list: which methods and fields will be modified in each file, and what will be added
Step 3  After human confirmation, apply incremental modifications file by file; full-file rewrites are prohibited
Step 4  Generate matching DDL change scripts, including rollback scripts
Step 5  Compile and run checks

Combined with the hard constraint “full-file rewrites are prohibited; only method-level or block-level incremental modifications are allowed,” the controllability of existing-code changes improves significantly.

4.3 Checkpoint Resume and State Files

Generating a medium-sized module often takes a long time. The process may be interrupted due to timeouts, errors, or context limits. The solution is not to restart the conversation. Instead, maintain a machine-readable state file in the repository:

task: Reimbursement module
mode: create
stage: build
completed:
  - design/01-requirement.md
  - design/02-use-case.md
  - design/03-data-model.md
  - build/Step-01-plan.md
  - build/Step-02-backend.md
current: build/Step-03-frontend.md
files_done: [...]
files_pending: [...]
blockers: []

After any interruption, the process restarts by reading the state file, skipping completed items, and continuing from current. This provides two additional benefits:

• It avoids duplicate generation and file conflicts.
• The process itself becomes auditable and can answer the question: “What stage is this module at?”

4.4 Writing Team Standards as Rule Files

One of the most common problems with AI-generated code is that it is “usable but not consistent with the team’s existing style.” The solution is to consolidate standards into rule files that are versioned with the repository:

.workflow/
├── design/
│   ├── INDEX.md                 # Stage navigation and deliverable inventory
│   ├── rules/
│   │   ├── use-case-rules.md    # Use case specification conventions
│   │   ├── db-design-rules.md   # Naming, primary keys, audit fields, indexes, status field conventions
│   │   ├── api-contract-rules.md# Path style, pagination parameters, error-code hierarchy
│   │   └── permission-rules.md  # Role, permission point, and data-scope modeling
│   └── stages/
│       ├── 01-requirement.md    ├── 02-use-case.md     ├── 03-data-model.md
│       ├── 04-api-contract.md   ├── 05-menu-permission.md
│       └── incremental/         # Steps dedicated to existing-code changes
├── build/
│   ├── rules/
│   │   ├── backend-layer-rules.md    # Layer responsibilities, dependency direction, transaction boundaries
│   │   ├── controller-rules.md       # Parameter validation, unified responses, exception mapping
│   │   ├── persistence-rules.md      # Query construction, logical deletion, pagination, batch writes
│   │   └── frontend-component-rules.md# Component division, form validation, list interaction consistency
│   └── stages/
│       ├── 01-ingest-design.md  ├── 02-backend.md   ├── 03-frontend.md
│       ├── 04-migration-sql.md  └── 05-verify.md
└── verify/
    ├── gates.md                 # Quality gate definitions
    ├── checklist.md             # Human acceptance checklist
    ├── state.yaml               # Checkpoint state
    └── knowledge/               # Root-cause analysis knowledge base

Rule files should specify what to do and what is prohibited. For example:

• All list APIs must support pagination and return the total count.
• Logical deletion fields must use a unified naming convention, and physical deletion statements are prohibited.
• Controllers must not directly call the data access layer.

The more specific the rules are, the easier it is for the model to get it right the first time.

5. Stage Three: Testing and Validation — Quality Gates and Failure Loops

This stage is where the value of the pipeline is realized. It is also the stage most likely to become superficial. It includes two mechanisms: quality gates and self-loop testing.

5.1 Four-Layer Quality Gates

The checks are performed in order. If any layer fails, the process stops and enters the failure loop. Known errors are not allowed to enter the next layer:

G1  Backend compile                 Syntax and dependency consistency
G2  Unit tests / integration tests   Business logic and data access correctness
G3  Frontend type check              Alignment between API contracts and type definitions
G4  Frontend production build        Whether the final artifacts can be built successfully

The gates must be scripted and executable with one command, and written into the rule files. Otherwise, they will be manually bypassed because running commands by hand every time is inconvenient. This is one of the most common failure modes in practice.

5.2 Self-Loop Testing and 5-Why Root-Cause Analysis

How test failures are handled is critical. If the raw error message is simply sent back to the model and it is asked to “fix it,” the result is often “the test passes but the logic is still wrong.”

A more reliable approach is to require a root-cause inquiry:

Failure symptom → Why did it fail? → Direct cause
               → Why did the direct cause occur? → Intermediate cause
               → Why did the intermediate cause exist? → Root cause (usually a design defect or missing rule)
               → Fix the root cause instead of changing assertions or adding patchwork fallbacks
               → Rerun all quality gates

It is especially important to distinguish between implementation errors and design errors. If the issue is a design error, the process must return to Stage 1, update the documentation, and then rerun the affected implementation steps. Patching the code directly is not sufficient. This constraint prevents technical debt from being accelerated by automation.

5.3 Three Types of Test Coverage and No Premature Convergence

Test cases must cover three types of scenarios:

• Normal scenarios: The main flow works correctly, and state transitions are valid.
• Exception scenarios: Missing parameters, invalid formats, operations not allowed by the current state, unavailable dependency services, and database unique constraint conflicts.
• Boundary scenarios: Empty lists, single records, the last page of pagination, minimum and maximum amounts or quantities, maximum field length, concurrent duplicate submissions, and time-zone or cross-day time issues.

One hard engineering rule applies: when the test plan lacks boundary scenarios, the loop must not be marked as complete. Models naturally tend to stop once the happy path passes. The process must force them to continue adding boundary cases. This rule is one of the most effective defenses against “surface-level passing” in the entire pipeline.

5.4 Converting Root-Cause Analysis into a Knowledge Base

Every 5-Why root cause, fix method, and regression conclusion should be saved to a knowledge directory. For example:

## KB-017 Pagination parameters sent as strings by the frontend
- Symptom: Type conversion fails on the backend when pagination parameters are strings
- Direct cause: The input DTO lacks type declarations
- Root cause: The API contract document did not define pagination parameter types
- Fix: Add to the contract rules: "Pagination parameters must be integers; the frontend component library performs conversion uniformly"
- Impact: All list APIs; regression checklist updated

As entries accumulate, the knowledge base becomes a supplementary source for rule files. If the same type of problem appears repeatedly, it should be promoted into a new rule, shifting from case-by-case fixes to prevention.

6. Four Non-Negotiable Human Responsibilities in the Pipeline

Higher automation does not mean fewer human responsibilities. The following four responsibilities should not be delegated to AI:

1. Defining and making trade-offs on business rules. When rules conflict, the final priority must be decided by the business owner and the project lead.
2. Final confirmation of the data model. Incorrect table structures are extremely costly to fix and require migration effort. They must be reviewed by humans.
3. Human review of security and permissions. Unauthorized access, data-scope leakage, sensitive-field masking, SQL injection risks, and file-upload validation are high-risk areas that automated checks cannot fully cover. They must be reviewed manually item by item.
4. Approval of new dependencies and new directory structures. The model may add third-party libraries or create directories that do not conform to team conventions in order to complete a task. These changes require human approval and dependency vulnerability scanning.

7. Adoption Roadmap and Common Anti-Patterns

It is recommended to proceed in four stages, validating each step in a small scope first:

1. Choose a low-risk existing module for a pilot, such as dictionary management or log query. Have both humans and the pipeline implement it once, and compare the results.
2. Build rule files and gate scripts first, rather than rushing to generate more AI code. Rule quality determines output quality.
3. Expand to the incremental change mode. This is the scenario with the greatest daily value.
4. Establish metrics, such as the cycle from requirement change to release, defect density, regression testing time, and the first-pass success rate of AI-generated output. Without metrics, it is impossible to determine whether the process is truly effective.

Anti-patterns to watch for include:

• Generating the entire system in one pass. The context explodes, and the output cannot be reviewed effectively.
• Letting AI decide whether tests pass. This creates a misaligned objective function and encourages changing assertions instead of fixing defects.
• Automation without gates. The process runs fast, but it also amplifies errors quickly.
• Rule files that are not updated over time. If the project runs for months but the rules remain stuck at the initial conventions, the output will gradually drift away from expectations.

8. Conclusion

The core of this pipeline is not the capability boundary of any single tool. It is three engineering principles:

• Use documents to eliminate requirement uncertainty before coding.
• Use externalized rules to turn team standards into executable constraints.
• Use quality gates and failure loops to ensure automation does not accelerate defect production.

AI is responsible for repetitive labor such as retrieval, expansion, generation, and regression testing. Humans are responsible for defining rules, making trade-offs, and guarding quality and security boundaries. For small and medium-sized teams with limited resources, whether these three principles can be embedded into the workflow determines whether AI-assisted development becomes a long-term asset or a liability.