画板 1

    Multi-Agent Collaborative AI Coding Workflow: How to Do It and Common Mistakes

    5 hr ago0 views

    This article explains how to use a multi-agent AI coding workflow that separates planning from execution, when the approach is worth its higher cost, how to write a structured spec, run cross-review, create constraint files, perform code audits and test planning, and avoid common failure modes that lead to rework, unclear requirements, or unsafe code.

    1. What Is Multi-Agent Collaboration: Separating Planning From Execution

    In a single-assistant workflow, the same model often handles both solution design and coding. The most common failure is not a syntax error, but weak design plus drifting implementation: the model keeps extending its own context and lacks an independent perspective capable of challenging the original plan.

    Multi-agent collaboration isolates context and introduces two roles:

    • Planning agents: handle requirement clarification, solution design, and document review. They are responsible for making the plan clear.
    • Execution agents: write or modify code according to the finalized plan. They are responsible for implementation quality.

    Because the two agents do not share the full reasoning chain, the review step can produce a genuine second opinion. In effect, context isolation simulates the separation between design and development in a team.

    Who Should Use This Workflow? When Is It Not Worth It?

    The cost must be stated clearly: multi-agent collaboration requires generating multiple rounds of text for the same requirement. Token usage, review rounds, and coordination overhead are noticeably higher than directly generating a solution with a single assistant. A practical boundary is:

    • Worth using: medium or large features, repositories with multiple contributors, modules involving money, permissions, or data, and scenarios where rework is expensive.
    • Not worth using: one-off scripts, small utility code of a few hundred lines, or exploratory prototypes. For these tasks, direct generation is usually faster, and adding review becomes a burden rather than a safeguard.

    2. The First Step: Turn Requirements Into a Spec Document

    Many AI coding failures start with unclear requirements, not with code quality. Therefore, the first step is not to write code, but to produce a structured specification document, sometimes also called a harness document. It is best stored inside the repository, for example at docs/spec.md, and tracked with Git. This way, every conversation can refer to the same source of truth, requirement changes leave diffs, and it becomes easier to trace which sentence caused the implementation to drift.

    A minimal usable template is shown below. Required and optional fields are marked:

    1. # Spec: <Feature Name>
    3. ## 1. Goals (Required)
    4. - The problem to solve and observable success criteria
    6. ## 2. In Scope (Required)
    7. - Feature list + priority (P0/P1/P2)
    8. - Pages, APIs, or modules affected
    10. ## 3. Out of Scope (Required)
    11. - Items explicitly excluded from this iteration (prevent scope creep)
    13. ## 4. Interface Contract (Required)
    14. - Request/response structure, callers, and protocol (HTTP/RPC/CLI)
    15. - Idempotency and timeout expectations
    17. ## 5. Data Model (Required when persistence is involved)
    18. - Table schema, field types, indexes, and migration approach
    20. ## 6. Error Codes and Error Handling (Required)
    21. - Unified error code convention (for example, XXX_001), response structure, and retry strategy
    23. ## 7. Acceptance Criteria (Required)
    24. - Executable criteria: input → expected output, including normal and failure cases
    26. ## 8. Non-Functional Requirements (Optional)
    27. - Performance targets, logging standards, monitoring metrics, and compatible versions

    The required fields are: Goals, In Scope, Out of Scope, Interface Contract, Error Handling, and Acceptance Criteria. If any of these are missing, they should be completed before coding begins. Data Model is required when persistence is involved, while Non-Functional Requirements can be added later.

    One frequently ignored field is Acceptance Criteria, because it determines whether test cases have a reliable basis. It should be written as decidable statements such as “input A returns B,” not as unverifiable descriptions such as “good user experience.”

    3. How to Converge the Design Review: Cross-Challenge and Stop Conditions

    Once the spec has a first draft, the workflow moves into cross-review. The execution agent raises concerns from the perspective of implementation difficulty, dependencies, and edge cases. The planning agent responds item by item, revises the design, and updates the spec. It is best to remain in plan mode during this stage, without changing code, so that the discussion stays focused on the solution itself.

    1. Example review rounds:
    3. R1 Execution: The consistency strategy for concurrent writes is undefined. 
    4.    Planning: Add a distributed lock and an idempotency key.
    6. R2 Planning: The error code system is missing. 
    7.    Planning: Add a unified error code convention and response structure.
    9. R3 Execution: No new blocking issues; remaining items are P2 optimizations. 
    10.    Result: Converged; the design is finalized.

    What Does a Failed Convergence Look Like?

    A common failure case starts from a requirement that only says “support bulk user import,” without defining file format limits, deduplication rules, or how partial failures are handled. In each round, the execution agent raises new problems. The planning agent updates the document, but each patch introduces new ambiguity. By the fifth round, the discussion is still going in circles. The issue is not the review process itself; it is that the acceptance criteria in the spec are empty.

    Stop conditions should be explicit and handled by human judgment:

    • If two consecutive rounds produce no new P0 or P1 issues, the review converges and implementation can begin.
    • If the same issue is still unresolved by the third round, stop the review and let a human make the requirement decision.
    • If the root cause is an undefined business rule rather than a technical choice, a human must intervene immediately. The model cannot decide business rules for you.
    • Hard limit: do not exceed five review rounds. If the limit is reached, return to the spec stage and complete the document.

    4. How to Write Constraint Files: Rules at the Project Root

    After the design is finalized, constraint files should be used during implementation to keep the model aligned. Without them, every new conversation may cause the model to guess your preferences again. In practice, this is a rule file at the repository root, such as AGENTS.md or RULES.md. Some tools also support files such as .cursorrules. An example is shown below:

    1. # Project Rules
    3. ## Coding Standards
    4. - Use TypeScript strict mode; functions should be no longer than 50 lines; use camelCase naming
    5. - Lint and typecheck must pass before commit
    7. ## Directory Structure
    8. - `src/api` contains only the interface layer; `src/service` contains business logic; services must not read request objects directly
    10. ## Forbidden Dependencies
    11. - Do not add `moment` (use `dayjs` instead); do not introduce unreviewed third-party packages
    13. ## Error Handling
    14. - Throw `AppError(code, message)` consistently; do not silently return after a bare `catch`
    16. ## Logging Standards
    17. - Use structured JSON logs and include a `traceId`; do not log phone numbers, tokens, or identity card numbers
    19. ## Security Red Lines
    20. - Do not put `.env` contents into code; SQL must be parameterized; external input must be validated and escaped
    22. ## Change Discipline
    23. - Commit one module at a time; when interfaces change, update `docs/spec.md` in the same change

    The value of a constraint file is that it turns one-off verbal preferences into versioned, diffable team assets.

    Modular Progression

    During development, modules should be implemented one at a time. Do not ask the model to generate an entire project at once:

    • Each module should be completed and verified independently, which reduces the scope of each generation and the surface area for errors.
    • Modules should be decoupled through the interface contracts defined in the spec, making them easier to replace and unit test.
    • After each module is completed, run a confirmation step to prevent errors from spreading across modules.

    5. How to Implement Cross-Code Audits and Test Planning

    Audit Trigger Conditions and Output Template

    Code audits should not be triggered by intuition. It is better to define two fixed triggers:

    1. After a module is completed and before merging.
    2. When the change involves permissions, payments, or data writes.

    The planning agent acts as an independent reviewer and audits the code. It outputs a structured list of issues. The execution agent then fixes the issues or responds to them item by item. This usually converges in one to two rounds.

    1. | ID | Issue | Severity | Evidence | Fix Suggestion |
    2. |---|---|---|---|---|
    3. | A1 | The pagination API does not validate the upper limit of `limit` | High | `api/user.ts:42` passes it through directly | Limit it to 1–100 and truncate values above the maximum |
    4. | A2 | An exception branch swallows errors | Medium | `service/order.ts:88` catches the error and only returns null | Throw `AppError` and preserve the stack trace |
    5. | A3 | Naming is inconsistent with the standard | Low | `utils/date.ts:10` | Rename to `formatDate` |

    Severity should use only three levels:

    • High: data issues, security issues, or potential financial loss. These must be cleared before merging.
    • Medium: functional defects or maintainability issues. These can be scheduled.
    • Low: style issues. These can be handled when convenient.

    Test Planning Template

    Let one agent draft a test plan, and let another agent review whether the coverage is sufficient. After the plan is finalized, generate test cases. This reduces blind spots such as tests only covering the paths the agent happened to think of.

    1. ## Test Plan: <Module Name>
    3. ### Unit Tests
    4. - Coverage: pure functions, validation logic, and state machine branches
    5. - Key cases: empty input, oversized input, concurrency, and amount boundaries (0 / negative / large values)
    7. ### Integration Tests
    8. - Coverage: API layer + database + mocked external dependencies
    9. - Key scenarios: normal flow, dependency timeout, and transaction rollback
    11. ### Coverage Targets
    12. - New code line coverage ≥ 70%; core amount and permission modules ≥ 85%
    14. ### Commands
    15. - Unit tests: npm run test
    16. - Coverage: npm run test:coverage
    17. - Full check: npm run lint && npm run typecheck && npm run test

    One important point is that AI-generated test cases may carry the same misunderstanding as the implementation. If the model assumes the feature works in a certain way, it may write tests that confirm that assumption. Therefore, acceptance criteria must come from the finalized spec produced during the review process, not from reverse-engineering the code.

    6. Security and Compliance: Non-Negotiable Reminders

    A multi-agent workflow repeatedly reads, pastes, and discusses code and documentation. This creates a larger exposure surface than a single question-and-answer interaction.

    • Do not input secrets or sensitive code. Do not paste API keys, database passwords, private keys, or real production data into the conversation. When troubleshooting, use redacted snippets or placeholders instead.
    • Generated code must be human-reviewed and actually tested. The model may introduce logic that looks correct but contains authorization bypasses, injection risks, or other hidden defects. Code that has not been reviewed and tested should not be merged.
    • Check dependency licenses and supply chain risk. Do not casually introduce unreviewed third-party packages. Check whether the license is compatible with commercial use, whether there have been recent malicious package incidents, lock versions, and verify the source.
    • Keep human approval points. Changes involving permissions, payments, or data deletion must be confirmed by a human before release.

    7. Human Fill-In: Focus on What Machines Are Bad At

    This workflow does not aim for fully autonomous, unattended development. Humans still need to handle two types of work:

    • UI and interaction: visual details, interaction feedback, loading states, empty states, and other edge cases. The model often struggles to get these right in one pass.
    • Complex cross-module defects: bugs involving tightly coupled logic across multiple modules require human judgment about the root cause and the right tradeoff.

    A reasonable division of labor is: AI handles high-frequency, pattern-based work such as requirement decomposition, design review, code generation, and test design. Humans handle judgment, tradeoffs, and final polish of the experience.

    8. Frequently Asked Questions

    What kind of projects is this suitable for?

    It is suitable for medium or large feature development, repositories that require long-term maintenance, high-risk modules such as permissions, payments, or data handling, and situations where developers have limited coding experience but still need stable output.

    What are the most common mistakes?

    1. Skipping the spec document and directly asking AI to write code, which leads to repeated rework.
    2. Allowing unlimited review rounds, causing costs to outweigh benefits.
    3. Producing audits with vague conclusions such as “poor code quality,” without severity levels or evidence, which cannot drive fixes.
    4. Writing test cases by reverse-engineering the code, so the tests verify the implementation instead of the requirement.
    5. Leaving constraint files unchanged for a long time, causing them to diverge from the current state of the code.

    How do you control context cost and prevent review-round inflation?

    Split sessions by module and load only the files that are necessary. Keep the spec and constraint files in the repository and reference them as needed, instead of pasting them repeatedly in every conversation. Set a five-round cap on design reviews. For low-risk style issues, merge them directly into the constraint file instead of discussing them one by one.

    Conclusion

    For practitioners without a deep coding background, the value of this workflow is that it uses process discipline to compensate for limited personal experience. The spec document turns vague requirements into decidable conditions. Constraint files turn one-off preferences into versioned assets. Cross-code audits and test planning turn “it looks runnable” into “it can be run with evidence.”

    At the same time, the workflow has costs: token usage, time, and review rounds all increase. The benefits of review and documentation are not fixed. They usually help reduce rework, but the actual effect depends on requirement complexity, review-round settings, and test quality. On simple tasks, the net benefit can even be negative. Choosing which stages to use based on task risk is more important than copying the entire process mechanically.

    09040904

    Top articles