Path to AI Architect · Chapter 12 of 25
Multi-Agent Coordination and AI Development Workflows
When multiple agents help, how to split work between them, and how to coordinate interfaces, shared state, and merges.
27 min read Slides for this chapter
Opening scenario: four agents, one afternoon#
Chapter 11 had made Maya careful with one agent. The practice quiz feature tempted her to try four. Students would pick a set of notes, the Learning Coach would generate five questions, and they would answer and see a score. The feature had an obvious shape: a backend, a screen, tests, and documentation. So she opened four sessions, one for each, gave each the feature description, and started them at 1 p.m.
By 3 p.m. all four had pull requests, and each one passed its own checks. Maya felt the speed she'd hoped for. Then she merged them into one branch, and the afternoon was over.
- The backend and the screen disagreed. The backend agent returned each question with a
promptfield and answeroptions. The screen agent, working from the same description, had guessedquestionandchoices. Neither was wrong; nobody had decided. - The score was computed twice. Both agents needed a score, so both wrote one. The backend rounded down and the screen rounded to the nearest whole number. A student with 2 of 3 right saw 67% on one screen and 66% on the next.
- The tests had been “fixed.” The test agent wrote tests from the feature description. When they failed against the backend, the backend agent changed two of them to match its own field names.
- The documentation described a plan nobody followed. The documentation agent finished first, from the description, and documented an endpoint that no longer existed.
Merging took the rest of that day and most of the next. Sam, the developer friend who now helped Maya two days a week, tested the merged branch and found a quiz score of NaN% when a student answered no questions. Maya worked out that building the feature with one agent, one step at a time, would have taken about a day. Four agents had made it take two, and the bill for model usage was several times what a single session would have cost.
Each agent had done its own job reasonably. The failure was in how the work was split.
Why it matters#
Chapters 10 and 11 taught you to direct one agent through one task. Running several agents at once is tempting because it looks like hiring a team for free. But a team isn't just more people; it's people plus the coordination between them, and coordination is where multi-agent work usually fails.
In 1968, Melvin Conway observed that organizations which design systems produce designs that copy their own communication structures, and concluded that design work should be organized around the need for communication (Conway, 1968). Agents make this sharper, not weaker. Two agents in separate sessions don't communicate at all unless you build the channel. Whatever they must agree on has to be decided before they start, or it will be decided twice, differently.
Research on multi-agent systems points the same way. A Berkeley-led team studied more than 1,600 execution traces from seven popular multi-agent frameworks and found failure rates between 41% and 86.7%. They grouped the failures into 14 modes, and concluded that many come from how the agents are organized and coordinated rather than from the limits of any one model (Cemri et al., 2025). Anthropic, describing its own multi-agent research system, reported that it used about 15 times as many tokens as a chat, and noted that most coding tasks have fewer truly parallel parts than research does (Hadfield et al., 2025).
None of this means “never use several agents.” It means the architect decides when parallel work pays, splits it along lines that need little communication, writes down what must be shared, and keeps one person responsible for putting it back together.
Learning objectives#
After this chapter you will be able to:
- Decide when multiple agents help and when one agent is the simpler, faster choice.
- Define agent roles with clear inputs, outputs, permissions, and reviewers.
- Coordinate parallel work with frozen contracts, a task board, isolated workspaces, and structured handoffs.
- Recognize multi-agent failures: conflicting edits, stale interfaces, circular delegation, and runaway costs.
- Choose a workflow pattern: sequential pipeline, parallel work behind contracts, propose, critique, and revise, or a human decision at a risk boundary.
- Run two features in parallel and integrate them with a responsibility matrix, a dependency graph, and an integration report.
12.1 When to use multiple agents#
Independent parallel tasks versus tightly coupled tasks#
Two tasks are independent when each can be finished and checked without reading or changing the other's output. They are tightly coupled when one depends on choices the other makes: a field name, a database table, a helper function, a rule.
A quick test before splitting work. For each pair of tasks, ask:
- Shared files? Will both change the same file?
- Shared data? Will both create or change the same tables, or depend on the same migration?
- Shared decisions? Does either need an answer the other will invent: a field name, a format, a rounding rule?
Three “no” answers mean the tasks can run in parallel. Any “yes” means either decide the shared thing first, in writing, or run the tasks one after the other.
The quiz feature failed all three. The backend and screen shared undecided field names; both needed the score rule; the tests and the backend shared files. Split by layer, before anything was decided, its parts were tightly coupled.
Coordination overhead and diminishing returns#
Each agent you add brings its own costs. It needs its own instructions and context. Its output needs its own review, and review is your bottleneck (chapter 11). And every pair of agents that must agree is a possible conflict: two agents have one pair, four have six, six have fifteen.
Token costs grow too. Anthropic found that token usage alone explained 80% of the difference in performance on one browsing benchmark, which is why spreading work across agents with separate context windows helped its research tasks. The same post is clear about the price: about four times the tokens of a chat for one agent, and about fifteen times for its multi-agent system, worth it only when the task's value justifies the cost (Hadfield et al., 2025).
For a small product team, a practical limit is the number of agent pull requests you can review well in a day. Beyond that, extra agents produce a queue, not progress.
The human architect as task owner#
Whatever the setup, one person owns the outcome: the task graph, the contracts, the merge order, and the decision to ship. Agents can plan, implement, and review, but they don't own anything. When two agents disagree, the disagreement goes to the owner. When the merged result is wrong, the owner finds out why.
In the quiz afternoon, nobody owned the merge until Maya started merging, and by then all the decisions had been made, four times.
When one agent is the simpler choice#
Use one agent when the task is tightly coupled, small enough to finish in one session, or not yet clearly specified. Anthropic's general advice for agent systems is to find the simplest solution that works and add complexity only when it clearly improves results (Anthropic, 2024). Cognition, which builds a coding agent, argues more strongly that in 2025 a single agent with continuous context is usually more reliable than several, because every action carries implicit decisions, and agents that can't see each other's decisions make conflicting ones (Yan, 2025).
A single agent can still use helpers. A common, safe use is a helper session that answers a question (“where is the week boundary computed?”) and returns only the answer, so the main session's context stays clean. Helpers that read and report are low-risk; helpers that write code in parallel are where coordination starts to matter.
12.2 Agent roles#
A role is a job description for an agent session: what it reads, what it produces, what it may change, and who reviews its output. Roles keep sessions focused, and they let you give each one only the permissions it needs.
| Role | Reads | Produces | May change | Reviewed by |
|---|---|---|---|---|
| Planner / requirements analyst | PRD, specs, user notes | Questions, draft spec, task graph | docs/specs/, docs/tasks/ |
Maya |
| Architect / contract reviewer | Spec, ADRs, existing contracts | Contracts, review findings | Contract files only, on request | Maya |
| Backend implementer | Task card, contract, backend code | Code, tests, evidence | Its module's folder | Maya + reviewer session |
| Frontend implementer | Task card, contract, generated types | Screens, tests, evidence | Its feature's screens | Maya + reviewer session |
| Tester | Spec, acceptance examples, contract | Tests from the spec | Test folders only | Maya |
| Security reviewer | Diff, risky zones, ADRs | Findings, ranked | Nothing (read-only) | Maya decides |
| Documentation agent | Merged code, spec | Docs updates | docs/ only |
Maya |
Planner and requirements analyst#
The planner turns a feature idea into the documents of chapter 10: questions for the human, a draft specification with acceptance examples, and a task graph. It writes no product code. Its main value is surfacing decisions early, while they're cheap.
Architect and contract reviewer#
This role drafts the contracts that parallel work depends on, or reviews contracts you drafted, against the spec and the existing ADRs. It looks for gaps: a missing error case, a field with no format, a rule two tasks both need. Its output is a contract Maya reviews and freezes.
Frontend and backend implementers#
Implementers do the work of chapter 11: one task card, one branch, owned files, evidence at the end. In parallel work, the most important line on their task card is the contract they build against, and the instruction that changing it is a question, not an edit.
Tester, security reviewer, and documentation agent#
These roles check or describe others' work, and they work best with no stake in it. Anthropic suggests a writer and reviewer pattern with separate sessions, because a fresh context isn't biased toward code it just wrote, and a related pattern where one session writes tests and another writes code to pass them (Anthropic, Best practices for Claude Code). Give reviewers read-only permissions. A security reviewer that can edit will “fix” things instead of reporting them, and you lose the record of what was wrong.
Roles only help if agents stay in them. Among the failure modes in the Berkeley study is agents disobeying their role specification, for example one agent ending a conversation without the agreement of the agent that was supposed to decide. In one case study, simply making sure the right agent had the final say raised task success by 9.4% (Cemri et al., 2025). Permissions enforce roles better than instructions do: a tester that can only write test files can't change the code to match.
12.3 Coordination mechanisms#
Shared contracts and a common task board#
A contract is the written agreement at a boundary: the API's paths, fields, types, errors, and the rules both sides rely on (chapter 8). For parallel work, contracts are written first, reviewed, and frozen: no one changes them without the owner's approval and a version note. Chapter 10's task graph already put contracts at the start for this reason.
Write the shared rules into the contract too, not just the shapes. “score_percent is an integer, computed by the backend as round(100 * correct / answered), and is null when answered is 0” would have prevented both the 66/67 disagreement and the NaN%.
Back every contract with contract tests: automated tests that check the backend's actual responses against the contract, and generated frontend types that fail to compile if the screen uses a field that doesn't exist. Then drifting from the contract is a failing check, not a merge surprise.
A task board is the single place that shows every task's status, owner, workspace, and dependencies. For a small team, a Markdown file in the repository works:
| Task | Owner (role) | Workspace | Depends on | Status |
| --- | --- | --- | --- | --- |
| C1 Contracts: quizzes + summary | Maya + architect | main | none | frozen v1.0 |
| Q1 Quiz backend | backend agent A | ../coach-quiz | C1 | in review |
| Q2 Quiz screen | frontend agent B | ../coach-quiz-ui | C1 | in progress |
| S1 Weekly summary | agent C | ../coach-summary | C1 | done, merged |
Agents read it at the start of every session; only the owner changes the status column.
Branches, worktrees, or isolated workspaces#
Agents working in parallel need separate working copies of the code, or they overwrite each other's files mid-task. Three options, from lightest to heaviest:
- Branches alone aren't enough when sessions share one folder: switching branches changes the files under every session.
- Worktrees. Git can attach several working folders to one repository, each with its own branch checked out (Git, git-worktree documentation). Each agent gets its own folder, all sharing the same history.
- Isolated machines. Cloud agents (chapter 11) each run in their own environment and return a pull request.
Creating a worktree for a task takes one command:
git worktree add -b feat/quiz-backend ../coach-quiz main
git worktree list # see every workspace and its branch
git worktree remove ../coach-quiz # after the branch is merged
Anthropic's guidance for its agent recommends worktrees for running parallel sessions, so edits don't collide (as of the October 2026 review of its documentation) (Anthropic, Best practices for Claude Code). Remember that separate folders don't mean separate everything: if two worktrees point at the same local database, their migrations and test data collide. Give each workspace its own test database.
Structured handoffs and evidence summaries#
When one agent's output becomes another's input, pass it through a handoff note, not a chat summary. Anthropic found that when its lead agent gave short, vague instructions, subagents misread the task or duplicated each other's work; each one needed an objective, an output format, guidance on tools and sources, and clear boundaries (Hadfield et al., 2025). The Berkeley study lists the reverse problem too: an agent holding information another agent needed and never passing it on (Cemri et al., 2025).
A handoff note has a fixed shape:
## Handoff: Q1 quiz backend -> Q2 quiz screen
Contract: docs/contracts/quizzes.yaml v1.0 (unchanged)
Done: POST /quizzes, GET /quizzes/{id}, POST /quizzes/{id}/answers
Evidence: contract tests 14/14; full suite 431 passed, 0 skipped
Decisions made inside the contract: questions generated in one model call,
stored before returning; quiz expires after 7 days (spec AC-10.4)
Known gaps: no rate limit yet (task Q4)
Questions for the owner: none
The evidence summary from chapter 11 is the same idea pointed at the reviewer; the handoff note points it at the next worker.
Integration owner and merge gates#
One person, the integration owner, merges parallel work into the main branch. In a small team that's the architect. An agent can prepare the integration, but the owner decides.
The owner merges in the order of the dependency graph, one branch at a time, and runs the merge gates after each: contract tests, the full test suite on the integrated code, the end-to-end journeys, and the migration check (one chain of migrations, applying cleanly to a fresh database). A branch that fails a gate goes back to its owner with a note. It doesn't get fixed during the merge, because fixes made during a merge are the least reviewed code in any project.
12.4 Failure modes#
Conflicting edits and duplicated work#
Two agents change the same file, or both write the same helper. Conflicting edits show up at merge; duplicates often don't, and live on as two versions of one rule that slowly disagree, like the two score functions.
Prevent both with file ownership on every task card, a rule that shared helpers belong to one task (or are written first), and a reviewer step that searches for new code resembling existing code (chapter 11).
Stale interfaces and inconsistent assumptions#
An agent builds against a contract that changed after it started, or against an assumption another agent never shared. Cognition's article makes the point with a game-building example: two subagents given halves of a task each made reasonable choices, and the pieces didn't fit, because each action carried decisions the other couldn't see (Yan, 2025). The Berkeley study found agents proceeding on wrong assumptions instead of asking for clarification in 6.8% of the failures it categorized (Cemri et al., 2025).
Prevent it with frozen, versioned contracts; task cards that name the contract version; and a rule that any contract change pauses every task that depends on it until the owner has updated their cards.
Circular delegation and unreviewed autonomy#
When agents can hand work to each other, they can hand it back. A planner asks an implementer, the implementer asks the planner to clarify, the planner restates the task, and so on. Among the Berkeley study's most common failure modes were step repetition (15.7%) and agents not recognizing when the task was finished (12.4%) (Cemri et al., 2025).
The related danger is agents approving each other's work with no person in the loop. The same study found that verifier agents often performed only shallow checks, such as whether code compiled, even when asked to verify thoroughly; one generated chess program passed review and still broke the rules of chess (Cemri et al., 2025). An agent reviewer adds a second look. It doesn't add a decision.
Prevent both with round limits, a clear “done when” for every loop, and a rule that open questions go to the human owner, never back around the loop.
Escalating token or compute costs#
Every agent reads its own context, often the same files, and every loop repeats that reading. Costs grow faster than the number of agents. Set a budget per task and per day, watch it the way you watch any other running cost (chapter 16 covers cost per user and per request), and stop any session that passes its budget for a human look. A task that needs three times its budget is usually a task that needed a better specification.
12.5 Workflow design patterns#
Anthropic's description of agent workflows names several patterns, including prompt chaining (steps in sequence, with checks between them), parallelization (independent parts run at once), and evaluator-optimizer (one model generates, another evaluates, in a loop) (Anthropic, 2024). Chapter 9 used them inside the product. The same shapes organize the agents that build it.
Sequential specialist pipeline#
One task at a time, each role in turn: planner, contract review, implementer, tester, reviewer, with a check between steps. Slower in wall-clock time, but nothing conflicts, and each step starts from reviewed work. This is the default for tightly coupled work, including most single features.
Parallel work behind frozen contracts#
Decide and freeze the shared parts first, then run independent tasks at once, each in its own workspace, and integrate through merge gates. This is where parallelism pays: separate features, or the two sides of a well-specified contract. It's the pattern for the worked example.
Propose, critique, revise#
One session proposes (a plan, a contract, a design), another critiques against stated criteria, and the first revises. Anthropic notes that this works when there are clear evaluation criteria and when feedback demonstrably improves the result (Anthropic, 2024). Without clear criteria, the critic's taste replaces the spec, and the loop doesn't end. Give it the criteria from the spec, a round limit (two or three is plenty), and a rule that unresolved disagreements go to a person.
Human decision at risk boundaries#
Some decisions always go to a person, whatever pattern is running: contract changes, migrations on shared data, access rules, anything touching student privacy, and the final merge. Mark these as gates in the workflow, so that agents stop at them by design, not by remembering to.
flowchart TD
S["Spec + task graph<br/>(owner: Maya)"] --> C["C1 Contracts frozen v1.0<br/>quizzes + summary<br/>(human gate)"]
C --> Q1["Q1 Quiz backend<br/>worktree coach-quiz"]
C --> Q2["Q2 Quiz screen<br/>worktree coach-quiz-ui"]
C --> S1["S1 Weekly summary<br/>worktree coach-summary"]
Q1 --> R1["Reviewer session<br/>(read-only)"]
Q2 --> R2["Reviewer session<br/>(read-only)"]
S1 --> R3["Reviewer session<br/>(read-only)"]
R1 --> I["Integration owner merges in order:<br/>S1, then Q1, then Q2<br/>gates after each merge"]
R2 --> I
R3 --> I
I --> G{"Contract tests, full suite,<br/>migrations, end-to-end pass?"}
G -->|no| B["Back to task owner<br/>with a note"]
G -->|yes| M["Main branch +<br/>integration report"]
Architect's decision: how do we run parallel agent work?#
| Context | After the quiz afternoon, Maya needs a standard way to decide when agents work in parallel and how their work is combined. Two features are next: practice quizzes (US-10) and a weekly progress summary (US-11). |
| Constraints | One reviewer (Maya) with limited daily review time. Agents can't see each other's sessions. Model costs are watched. Contracts, migrations, and privacy decisions need a person. |
| Option A | One agent, one task at a time (sequential pipeline). Simple and conflict-free; slow for independent work. |
| Option B | Parallel by layer: a backend agent and a frontend agent build the same feature at once. Fast if the contract is complete; fails badly if it isn't. |
| Option C | Parallel by feature behind frozen contracts: independent features run at once in separate worktrees, each a vertical slice, with one integration owner and merge gates. |
| Option D | An autonomous agent team: a lead agent splits work, starts helpers, and merges their results. Least effort to start; least control, highest cost, and hard to review. |
| Decision | Option A by default. Option C when tasks pass the independence test. Option B only with a frozen contract, contract tests, and generated types. No more than three implementer sessions at once (an assumption based on Maya's review capacity). Option D not used for product code. Recorded as ADR-009. |
| Tradeoffs | Contracts take time to write before any code. Some features must wait for others. Three sessions is a cap on speed in exchange for review quality. |
| Validation | Over the next four parallel features: no merge needs code fixes during integration, no contract changes go unversioned, review time per pull request stays under 30 minutes, and model cost per feature stays within the budget set on the task board. |
| Revisit trigger | Merges keep failing gates, review becomes the bottleneck at three sessions, or agent tools gain shared context good enough to make Option D reviewable. |
AI collaboration recipe#
Use agents to analyze dependencies, draft contracts, and prepare integration, and keep the decisions (what runs in parallel, what's frozen, what merges) with the owner.
1. Independence analysis.
Here are the specs for US-10 and US-11 and the repository map. For every pair of tasks in the two task graphs, list shared files, shared tables or migrations, and shared decisions (names, formats, rules). Mark each pair independent or coupled, and for each coupled pair say what would have to be decided first to make it independent. Don't propose code.
2. Contract draft and critique. One session drafts:
Draft the API contracts both features need, in OpenAPI. Include every field's type and format, every error, and every rule two sides depend on, such as how a score is computed and what happens with zero answers.
A second, fresh session critiques:
Review this contract against the spec. List missing errors, fields with no format, rules only one side could know, and anything two implementers could interpret differently. Don't rewrite it.
3. Role prompt for an implementer.
You are the backend implementer for task Q1 on
docs/tasks/board.md. Work only in this worktree and only inbackend/coach/quizzes/. Build againstdocs/contracts/quizzes.yamlv1.0. If the contract seems wrong or incomplete, stop and write the question in your handoff note; don't change the contract. Finish with the handoff note in the shape fromdocs/templates/handoff.md.
4. Integration report.
Here are the merged branches, in order, and the gate results after each merge. Write an integration report: what merged, which gates passed or failed, conflicts and how they were resolved, contract versions used, anything duplicated between branches, and follow-up tasks. Don't change any code.
Boundaries to state every time:
- “Work only in your worktree and your owned files.”
- “A contract change is a question for the owner, never an edit.”
- “Never merge, and never change another task's status on the board.”
- “If you need another agent's output, read its handoff note; don't guess.”
Worked example: two features in parallel#
Maya applied ADR-009 to the next two features.
US-10, practice quizzes: a student picks notes; the Coach generates five questions; the student answers and sees a score and the correct answers.
US-11, weekly summary: every Monday, a student sees last week's completed tasks, hours studied, and topics covered.
1. The independence test. The analysis prompt found three coupled points:
- Navigation. Both features add a menu item to the same navigation file.
- Migrations. Both add tables, and both migrations would start from the same parent, creating two competing “latest” migrations that the migration tool refuses to apply.
- Quiz scores in the summary. The first draft of US-11 included “quizzes taken this week,” which made the summary depend on the quiz feature's data.
Maya made each one independent before work split. The navigation file went to the integration owner, herself, as a five-minute change after both merged. The migrations would merge in a fixed order, with the second rebased onto the first before its merge. And quiz scores in the summary became a follow-up task, US-11b, after both features shipped. Cutting scope to remove a dependency is often the best decision in parallel work.
2. Contracts first. Task C1 produced docs/contracts/quizzes.yaml and docs/contracts/summary.yaml. The critique session found four gaps; the important one was that the draft never said what score_percent was when a student answered nothing. The frozen version said: an integer from 0 to 100, computed by the backend, null when no questions were answered, and the screen shows “Not answered” for null. Generated TypeScript types and contract tests went in the same pull request. Maya reviewed it line by line and marked it frozen v1.0 on the board.
3. The responsibility matrix.
| Task | Role / session | Owns | May read | Must not touch | Reviewed by |
|---|---|---|---|---|---|
| Q1 | Backend implementer A | backend/coach/quizzes/, its migration |
notes service, contracts | contracts, other modules | Reviewer session + Maya |
| Q2 | Frontend implementer B | web/src/pages/quizzes/ |
generated types | contracts, backend, navigation | Reviewer session + Maya |
| S1 | Full-slice implementer C | backend/coach/summary/, web/src/pages/summary/, its migration |
plans service, contracts | contracts, quizzes, navigation | Reviewer session + Maya |
| Q3 | Tester D | tests/quizzes/ |
spec, contract | application code | Maya |
| Nav, merge | Maya | navigation, main branch | everything |
US-11 was small and self-contained, so one session built its whole slice. US-10 was bigger and its contract was complete, so its backend and screen ran in parallel, per ADR-009's Option B rule.
4. Workspaces. Each implementer got its own worktree, branch, and test database:
git worktree add -b feat/quiz-backend ../coach-quiz main
git worktree add -b feat/quiz-ui ../coach-quiz-ui main
git worktree add -b feat/summary ../coach-summary main
5. What happened during the work.
- Implementer A wanted to add an
explanationfield to each question, so students could learn from wrong answers. It stopped and asked in its handoff note instead of editing the contract. Maya agreed, versioned the contract to v1.1, updated the task cards for Q1, Q2, and Q3, and regenerated the types. The screen session picked up the new field from the types; nothing broke. - Implementer C wrote a helper to find the start of the student's week. The reviewer session found that the plans module already had one, with the student's time-zone handling that the new one lacked. C switched to the existing helper.
- Tester D's tests, written from the spec and contract, caught that the backend returned the correct answers before the student submitted. It was a real bug, fixed by A, and the tests stayed unchanged.
6. Integration. Maya merged S1 first (no dependencies on the others), then Q1, then Q2, running the gates after each. The migration check failed after Q1, as predicted: Q1's migration still pointed at the old parent. A rebased its migration onto S1's, the check passed, and the merge continued. The integration report recorded it:
## Integration report: US-10 + US-11
Merged: S1 (summary) -> Q1 (quiz backend) -> Q2 (quiz screen) -> nav
Contracts: quizzes v1.1 (explanation added, approved), summary v1.0
Gates: contract tests pass; full suite 468 passed, 0 skipped;
end-to-end: take quiz, view summary; pass
Conflicts: Q1 migration parent stale after S1; rebased by Q1, re-reviewed
Duplicates found: week-start helper (removed in S1 before merge)
Follow-ups: US-11b quizzes in summary; Q4 rate limit on quiz generation
Cost: within task budgets (largest: Q1 at 70% of budget)
Two features shipped in two days, with no code fixed during the merge.
Verification: is parallel work under control?#
| Check | How |
|---|---|
| Independence | Each parallel pair passed the shared files, data, and decisions test, or the shared part was decided first. |
| Contracts | Every shared interface is written, frozen, versioned, and covered by contract tests and generated types. |
| Roles | Each session has a role with owned files and permissions; reviewers are read-only. |
| Workspaces | One worktree or isolated machine and one test database per implementer. |
| Task board | Every task shows owner, workspace, dependencies, and status; only the owner changes status. |
| Handoffs | Every handoff note names the contract version, evidence, decisions, gaps, and questions. |
| Merge gates | Merges follow the dependency order; contract tests, full suite, migrations, and end-to-end run after each. |
| No merge fixes | Branches failing a gate go back to their owner. |
| Loops bounded | Every agent loop has a round limit, a done condition, and escalation to the owner. |
| Costs | Each task has a budget; sessions over budget stop for review. |
Failure clinic: the loop that never converged#
Symptom. Before the weekly summary was built properly, Maya had tried an experiment: an implementer session and a critic session in a loop, running overnight, with the instruction “repeat until the critic approves.” In the morning the loop had run 37 rounds and used roughly 30 times the tokens of a normal task (an estimate from the usage page). The critic had finally approved. Sam's first test showed a student in Tokyo whose Monday summary was missing all of Sunday's work.
Reproduce. Maya read the transcript. Around round 4, the critic asked for week boundaries in UTC, the standard time used by servers, “for consistency.” Around round 9, it asked for the student's local time zone, “because students think in local weeks.” The implementer complied each time. The two positions alternated for 28 rounds, with other small requests mixed in. The version approved in round 37 used UTC.
Diagnose.
- The spec didn't decide. US-11 said “last week” without saying whose week. Both of the critic's positions were defensible; the question needed a person.
- Nothing could escalate. The loop's only exit was approval. Neither session was told that a disagreement it couldn't settle from the spec should go to Maya. The Berkeley study describes both behaviors: agents failing to ask for clarification, and agents not recognizing when to stop (Cemri et al., 2025).
- The critic had no criteria. It reviewed against its own judgment, which drifted between rounds, instead of against the acceptance examples.
- Approval stood in for verification. “Critic approves” was treated as done. No test for a student outside UTC existed, so nothing contradicted the approval.
Fix.
- Decide and write it down. Maya chose the student's local week, Monday to Sunday, and added AC-11.3 with examples for a student in Tokyo and one in Los Angeles.
- Bound every loop. Propose, critique, revise now runs at most three rounds. After that, or at any disagreement the spec can't settle, the loop stops and writes a question for the owner.
- Give critics criteria. The critic prompt lists the acceptance examples and asks for findings tied to them; findings without a spec reference are labeled as suggestions, not blockers.
- Set a budget. Every unattended loop has a token budget on the task board and stops when it's reached.
Lesson. Agents in a loop can't make a decision nobody gave them; they can only circle it, at your expense. Make the decision in the spec, give loops an exit to a human, and keep approval and verification separate.
Architect's checklist#
Before running agents in parallel:
- ☐ The tasks pass the independence test, or the shared parts are decided first.
- ☐ One agent was considered first, and parallel work has a clear payoff.
- ☐ One human owns the task graph, contracts, merge order, and ship decision.
- ☐ Each session has a role, owned files, matching permissions, and a reviewer.
- ☐ Shared interfaces are written, frozen, versioned, and covered by contract tests.
- ☐ The task board shows every task's owner, workspace, dependencies, and status.
- ☐ Each implementer has its own worktree or isolated machine and its own test database.
- ☐ Handoffs use a fixed note: contract version, evidence, decisions, gaps, questions.
- ☐ Merges follow the dependency graph, with gates after each and no fixes during merge.
- ☐ Every loop has a round limit, criteria from the spec, and escalation to a person.
- ☐ Every task has a cost budget.
- ☐ An integration report closes the work.
Exercises#
Beginner. For the Meal Planner, apply the independence test to these pairs of tasks and say which could run in parallel: (a) a shopping list export and a dark-mode theme; (b) an allergy filter in the recipe search and allergy warnings on the weekly plan; (c) a new database table for pantry items and a screen to edit pantry items. For each coupled pair, name what would have to be decided first.
Intermediate. For the Trip Planner, plan two features in parallel: “share a trip with a friend” and “weather alerts for trip days.” Write the independence analysis, the frozen contract for each, a responsibility matrix, and the dependency graph as a Mermaid diagram. Identify at least one dependency you remove by cutting scope.
Advanced. For the Shop Help Chat, build the same small feature, “let customers change a delivery address before shipping,” three ways: one agent sequentially; a backend and a frontend agent in parallel behind a frozen contract; and a propose, critique, revise loop with a round limit. For each, record wall-clock time, your review time, token cost, defects found after merge, and code fixed during integration. Write a one-page recommendation for when this team should use each approach.
Lab, artifact, and review#
Lab. Run two independent Learning Coach features in parallel behind frozen API contracts: practice quizzes (US-10) and the weekly summary (US-11), or two features of your own that pass the independence test. Use separate worktrees and one integration owner.
Deliverable. Add to your portfolio:
- the independence analysis and the decisions that made the features independent;
- the frozen contracts, with version history and contract tests;
- the agent responsibility matrix;
- the dependency graph, as a Mermaid diagram;
- the handoff notes;
- the integration report, including gate results, conflicts, duplicates, costs, and follow-ups;
- ADR-009 on parallel agent work.
Review. Give a colleague the integration report and the responsibility matrix, and ask them to explain what would have happened if two tasks had swapped workspaces, or if the contract had changed halfway through. If they can't answer from your documents, the coordination lives in your head, and the next parallel run depends on you remembering.
Reflection#
- In your last multi-step feature, which decisions would two parallel agents have made differently?
- How many agent pull requests can you review well in a day? Does your setup respect that number?
- Where does a disagreement between two agents go in your workflow, and how long would it take to reach you?
- Which loop or automation in your work has no exit except success?
You can now specify work, direct one agent safely, and coordinate several. What remains is proving the result works. Chapter 13 turns to testing, debugging, and verification: the evidence that has to stand behind every merge gate in this chapter.
References#
- Anthropic. (2024). Building effective agents. Anthropic Engineering.
- Anthropic. Best practices for Claude Code. Claude Code documentation.
- Cemri, M., Pan, M. Z., Yang, S., Agrawal, L. A., Chopra, B., Tiwari, R., Keutzer, K., Parameswaran, A., Klein, D., Ramchandran, K., Zaharia, M., Gonzalez, J. E., & Stoica, I. (2025). Why do multi-agent LLM systems fail? arXiv:2503.13657.
- Conway, M. E. (1968). How do committees invent? Datamation, April 1968.
- Git. git-worktree documentation. Git reference manual.
- Hadfield, J., Zhang, B., Lien, K., Scholz, F., Fox, J., & Ford, D. (2025, June 13). How we built our multi-agent research system. Anthropic Engineering.
- Yan, W. (2025, June 12). Don't build multi-agents. Cognition.
Links checked October 2026.
Check your understanding
3 questions
1.You want two agents to build two features at the same time. Which question best predicts whether running them in parallel will save time?
2.A backend agent and a frontend agent are building the same feature in parallel. What must exist before either starts?
3.An implementer agent and a critic agent loop until the critic approves. After 30 rounds they are still going. What is the most likely cause?
Was this chapter helpful?
Cite this chapter
Shi, T. (2026). Multi-Agent Coordination and AI Development Workflows. In Path to AI Architect: From vibe coding to designing, building, and leading AI-driven software systems (Online edition, Chapter 12). Exciton Research. Retrieved November 2, 2026, from https://excitonresearch.com/education/become-an-ai-architect/multi-agent-coordination
Brief quotations are welcome with attribution and a link.
© 2026 Tian Shi. All rights reserved.