Multi-agent setups work when each agent has a narrow job, a written contract with the next one, and a short list of things it must never do. The number of agents matters much less.
I learned this on a side project: a local Python app that does the bookkeeping for a small self-employed business. Scanned receipts land in a synced folder. A model extracts their data. Each document is stored as a JSON file and projected into SQLite. A small web UI on localhost lets you review and correct, and an export produces the Excel file the accountant wants.
It is not a toy. Version 1 shipped in eight milestones. Two weeks of work produced about 30 dated design notes, more than 100 numbered decisions and a test suite of several thousand tests. Most of the code was written by Claude Code, through a pipeline of six agents.
This post walks through that pipeline: who does what, how they hand work to each other, and where it stops to ask me.
The problem with one agent doing everything
A single agent that designs, codes, tests and reviews its own work is grading its own exam. In practice, three things go wrong.
- It validates itself. The same context that wrote the code decides the code is fine. Blind spots survive the review because the reviewer shares them.
- It bends the tests. When a test fails late in a long session, the shortest path to green is to change the test. Nothing in a single-agent setup forbids it.
- It forgets. Why did we store money as integer cents? Why is SQLite rebuildable from JSON? Those decisions live in a conversation that ends. The next session reopens them.
None of this is a model problem. A human developer working alone hits the same walls. Teams fix it with roles, reviews and written decisions. So I gave the agents the same structure.
The /feature chain
Every change, from a new screen to a one-file fix, goes through one skill: /feature. It runs six agents in a fixed order, and each one is defined by what it is allowed to touch.
The main line runs left to right; dashed steps only happen for UI changes, and the human box is reached only through the two stop points.
| Agent | Job | Tools | Never |
|---|---|---|---|
| architect | Writes a dated design note before any code | Read, Grep, Glob, Write, Edit | Writes application code or tests |
| web-designer | Adds the UI section to the note; later checks the result in a browser | Read, Grep, Glob, Write, Edit, Bash | Writes Python, tests or app logic |
| developer | Implements the design note, commits on the work branch | Read, Grep, Glob, Edit, Write, Bash | Edits an existing test to make it pass; runs git push |
| tester | Writes unit and integration tests, hunts edge cases | Read, Grep, Glob, Edit, Write, Bash | Writes outside tests/; fixes application code (it reports bugs) |
| reviewer | Checks the diff against the project rules and decisions | Read, Grep, Glob, Bash | Modifies any file |
| documentation | Updates docs, changelog and the Claude Code files | Read, Grep, Glob, Edit, Write | Writes outside docs/, README.md, CHANGELOG.md, CLAUDE.md files and .claude/ |
The last column is the one that matters. Each “never” closes a shortcut that a single agent would happily take. The developer cannot make a red test green by editing it. The tester cannot quietly patch the bug it found, so the bug shows up in its report. The reviewer has no write tool at all, so its only output is an opinion.
An agent is a Markdown file in .claude/agents/. Here is the top of the reviewer:
---
name: reviewer
description: Reviews a change against project invariants, documented
decisions and the one-responsibility-one-implementation rule.
Use after implementation and tests, before documentation.
tools: Read, Grep, Glob, Bash
---
You review. You never modify files.
The tools line enforces the role. The first sentence of the body states it. I found both necessary: the tool list stops the action, and the sentence stops the agent from trying.
One model per agent
The frontmatter takes one more field: model. Leave it out and the agent inherits the model of the main session. That is what this project does today: every agent runs on the same model.
The roles do not need the same strength, though. A sensible split looks like this:
| Agent | Model | Why |
|---|---|---|
| architect | opus | Weighs options against a hundred documented decisions; a bad design costs every later step |
| reviewer | opus | Has to spot what the others missed, including duplication across the codebase |
| developer | sonnet | Follows a precise design note; speed matters more than deep reasoning |
| tester | sonnet | Writes many tests from a clear plan |
| web-designer | sonnet | Works from written UI rules and a narrow screen spec |
| documentation | haiku | Updates files from a diff and a short report |
The rule of thumb: spend on the agents that decide (design, review) and save on the agents that execute a plan someone else wrote. Setting it is one line:
---
name: architect
tools: Read, Grep, Glob, Write, Edit
model: opus
---
The web-designer only joins when a change touches the web UI. It runs twice: once before the developer to design the screen, once next to the reviewer to check the result at 360 and 1280 px.
Contracts between agents
Agents do not talk to each other. They read and write files, and the files are the contract.
The design note. The architect’s only output is a Markdown file in docs/architecture/, named <date>-<slug>.md. It restates the request in one sentence, lists the options it rejected and why, names the affected modules and ends with a test plan. The developer starts from that file, not from my original sentence. When a decision changes how the system behaves, the architect also appends it to docs/decisions.md with a number. That log is how a fresh session knows why money is stored in integer cents.
The review format. The reviewer returns at most ten lines, each tagged:
BLOCKING storage/files.py:42 writes JSON without atomic_write
TO FIX web/api.py:118 error leaves a half-written batch
SUGGESTION domain/search.py:30 name says list, returns a generator
Only BLOCKING sends the work back. The tag makes the loop mechanical: no debate about whether a remark is serious.
Ten lines, maximum. Every agent ends with a summary of ten lines at most. Details go into docs/, never into the conversation. This rule looks cosmetic. It is the reason the pipeline survives a long session: the orchestrator’s context holds six short summaries per feature instead of six logs.
Docs as state. Progress lives in files too. A milestone table in docs/progress.md says what is done, at which commit, and what is open. The conversation can be compacted or lost; the next run reads the file and resumes.
Loops and guardrails
The pipeline is allowed to loop, but only twice, and it knows when to stop and ask me.
Two review loops, then stop. If the reviewer (or the web-designer in review mode) reports a BLOCKING item, both reports go back to the developer, then the tester runs again. After two rounds that still end in BLOCKING, the pipeline stops and reports to me. A third attempt by the same agents on the same problem rarely ends better than the second.
Approval only where it counts. The architect flags NEEDS USER APPROVAL only when a design would supersede a documented decision. Everything else goes ahead. I am asked about the few things that change the rules, not about every design note.
Autonomous mode. A second skill, /build-v1, chains /feature over every milestone of the roadmap without waiting for me. It stops on a short, explicit list of conditions:
- tests still failing after three fix attempts on the same problem;
- BLOCKING items left after two developer loops;
- a design that would change a released data format or a documented decision;
- something only I can provide: a secret, a real document, a check on my machine;
- a permission it does not have.
When it stops, it writes BLOCKED in docs/progress.md with what it tried and the exact question for me. The next run reads that line first.
Hard limits outside the prompts. Some rules are too important to leave to an instruction. An agent can misread a prompt; it cannot get past a hook.
A Claude Code hook is a command you register in .claude/settings.json against an event. PreToolUse runs before every matching tool call, PostToolUse right after it. Claude Code sends the tool call as JSON on the hook’s stdin: the tool name and its arguments. If the hook exits with code 2, the call is blocked and the hook’s stderr goes back to the agent as the reason.
This project registers two:
{
"hooks": {
"PreToolUse": [{
"matcher": "Read|Edit|Write|MultiEdit|Glob|Grep|Bash",
"hooks": [{ "type": "command", "command": "uv run python .claude/hooks/guard_paths.py" }]
}],
"PostToolUse": [{
"matcher": "Edit|Write|MultiEdit",
"hooks": [{ "type": "command", "command": "uv run python .claude/hooks/format.py" }]
}]
}
}
The first one, guard_paths.py, is plain Python. Simplified, its core reads:
def block(reason: str) -> None:
print(f"Blocked by guard_paths: {reason}.", file=sys.stderr)
sys.exit(2)
def main() -> None:
call = json.load(sys.stdin)
tool = call.get("tool_name", "")
args = call.get("tool_input", {}) or {}
if tool == "Bash":
command = args.get("command", "")
if SECRET_IN_COMMAND.search(command):
block("command references .env, config.toml or credentials")
if GIT_COMMIT.search(command) and current_branch() == "main":
block("commits on main are not allowed; switch to the dev branch")
return
path = resolve(args.get("file_path") or args.get("path"))
if path in SECRET_FILES or is_inside(path, CREDENTIALS):
block(f"{path.name} contains secrets")
It refuses any read of .env, the config file, the OAuth tokens or the real data folder, whichever tool tries, and any git commit while main is checked out. The agent gets the reason back and adjusts, usually by working on the dev data instead.
The second one never blocks. After every edit of a Python file it runs ruff format and ruff check --fix, so no agent wastes a turn on formatting.
Git hooks add a last layer outside Claude Code: a commit-msg hook rejects anything that is not a Conventional Commit, and pre-commit runs ruff, duplicate detection and a secret scanner. The prompt explains the rule; the hook makes it hold.
What this does not solve
The pipeline is not free, and it does not replace me.
- It is heavy for small changes. Six agents for a one-line fix is overkill. I still use
/featurefor those, because skipping it once is how the docs start to drift. But the cost is real. - The test suite grows fast. A tester whose whole job is to hunt edge cases will find many. The suite reached several thousand tests and CI got slow, especially on Windows. I had to run a dedicated audit to parallelise it and cut the duplicates.
- Some checks stay human. A screen reader, dark mode on a real machine, a real scanned receipt, a clean install: the agents list them as open points, and I do them.
- It costs tokens. Each agent rereads the project rules and the design note. The ten-line rule keeps the orchestrator lean, but the agents themselves still read a lot.
What I get in return: changes I can review from a design note and a short report, a decision log I trust, and a codebase where the same rule is not implemented three different ways.
Try it yourself
You do not need six agents to start. Three are enough to get most of the benefit: one that designs, one that builds, one that reviews without write access.
.claude/
├── agents/
│ ├── architect.md # writes docs/design/<date>-<slug>.md, no code
│ ├── developer.md # implements the note, never edits tests to pass
│ └── reviewer.md # tools: Read, Grep, Glob, Bash; returns BLOCKING / TO FIX / SUGGESTION
└── skills/
└── feature/
└── SKILL.md # architect → developer → reviewer, two loops max
Three rules make it work:
- Write down what each agent must never do, and back it with the
toolslist. - Pass work through files, not through the conversation: a design note in, a tagged report out.
- Cap every return at ten lines and send the details to
docs/.
Add a tester when the reviewer keeps finding untested paths. Add a documentation agent when your docs start to lie. Add hooks when a rule matters too much to trust to a prompt.
The agents are not the clever part. The contracts between them are.