A Multi-Agent Claude Code Development Workflow

Everything runs headless on one always-on Linux machine. There is no cluster, no cloud build farm, no Kubernetes — just an ordinary unprivileged user, a working tree, and a pool of specialized Claude Code agents that share it. Claude Code is Anthropic’s command-line coding tool; an agent, here, is a scoped persona it can hand a job to.

The shape is simple to state. Three intake paths feed one pool of agents. A structured pipeline turns any change that touches production into reviewed, tested, deployed code. The parts that must be predictable are plain Python; the parts that need judgment are the model’s. Everything the agents know that isn’t in their training lives in a notes vault they read at runtime.

The agent pool

Each agent is a Markdown file with a small block of structured metadata at the top: a name, a one-line description, a model tier, and the tools it may touch. Claude Code reads the description and routes work to the matching agent on its own — there is no hand-maintained dispatch table. Add an agent file, describe what it does, and it becomes eligible for work.

The agents are deliberately narrow. There is a Python implementer that writes code and never reviews it, a Python reviewer that lints and critiques and never writes, a test engineer that owns the entire test stack, a security reviewer, an architecture reviewer, a documentation writer, and an operations agent that owns commits and deploys. Parallel families cover the other stacks the same way — web, game engine, home-automation config, shell and container work — each with its own implementer, reviewer, and test engineer. Off to the side sit the non-coding specialists: a research agent, a bug-diagnosis agent that investigates but never fixes, a plan validator, a fact checker, and the editorial agents that produced this page.

Two rules make the narrowness pay off:

• Strict ownership. Exactly one agent owns each responsibility. Tests belong to the test engineer. Linting belongs to the reviewer. Commits belong to the operations agent. No agent re-runs another’s work, so findings do not get relitigated and nothing gets checked twice.
• Shared knowledge by reference. Style guides, domain references, and review checklists live in the vault. Agents read them by path rather than carrying inlined copies, so updating one guide updates every agent that reads it at once.

Each agent also keeps its own memory — a running file of what it learned across past sessions. The bug-diagnosis agent reads prior write-ups before opening a new investigation. The retrospective agent compares the current session against every one before it and catches patterns no single session would reveal. The architecture reviewer remembers the design calls it has already made so the same tradeoff is not re-argued from scratch. This is the part that compounds: the memory turns a hundred isolated runs into one long, improving one.

Three ways in

Work reaches the pool through three doors, and all three draw from the same agents.

Interactive dispatch. A single command takes one or more tasks — “fix the login bug, update the API docs, commit” — splits them into discrete units, groups them into dependency waves, matches each to an agent, shows the plan, and executes wave by wave. Independent tasks run in parallel; a task that depends on others waits for its wave. A bug report gets special handling: it becomes a diagnosis step followed by a fix step, so the fix works from evidence instead of guessing. The orchestrator that runs this never does task work itself. Every unit goes to a specialist, which keeps the coordinator’s attention on sequencing rather than on implementation detail.

The structured pipeline. For features, production bugs, and anything other systems depend on, a full software-development lifecycle runs end to end. It has a heavyweight form for real changes and a fast form for small, single-surface ones. More on it below.

The autonomous loop. A scheduled job pulls tasks from a task manager on a fixed cadence and routes each to an agent with no one watching. This is how research happens overnight and how unattended fixes land while I sleep.

The SDLC pipeline

The pipeline is the system’s definition of done for a change. Its defining trait is that the sequence of steps is fixed while the work inside each step uses judgment. I can trust the process even when the specific decisions vary run to run.

It comes in two sizes. The full pipeline runs the whole ceremony. A fast path collapses it to a handful of steps for work that is single-repo, single-surface, small, and free of anything sensitive — no prompt-engineering, no paid external API, no security-adjacent surface. The full run can step down to the fast path when the architect judges a change trivial; the fast path steps up to the full run the moment it trips one of its guard conditions. Small changes should not pay for ceremony they do not need, and the calibration of which change gets which treatment is the product of long tuning.

Think before building

Non-trivial work starts before any code exists. The orchestrator gathers technical facts, talks through two or three approaches with me, and writes a design document. A validator agent then stress-tests that document — are the assumptions sound, where are the edge cases, will this still hold in six months? Only after the plan survives does the architecture reviewer check it for fit against the existing system. Obvious one-line changes skip all of this.

The test-driven core

The heart of the pipeline is a test-driven loop, each step owned by a specialist:

1. Architecture review. The reviewer checks that the change fits existing patterns and that at least one real alternative was weighed. Its verdict can send the plan back.
2. Tests first. The test engineer writes tests before the implementation exists. They define the intended behavior and are expected to fail — that failure is the point.
3. Implementation. The engineer matched to the change writes code until the failing tests pass. Which engineer is automatic, chosen from the files being touched.
4. Parallel verification. Several reviewers run at once, each triggered by what actually changed — architecture quality, test coverage, code quality and linting, security, and the stack-specific reviewers. Each reports independently, and each finding surfaces as it lands rather than being saved for the end.
5. Fix everything. Every finding gets fixed. There are no severity tiers, no “pre-existing,” no “later.” The only thing that may stay open is a genuine tradeoff that needs a human call. After fixes, verification runs again, and the loop repeats until every reviewer is clean.
6. Mutation testing. The test engineer makes small deliberate breaks in the source — flip a condition, swap an operator, drop a call — runs the suite, and reverts. A break that no test catches is a hole in the tests. This step runs alone, since it edits source in place.
7. Documentation. A documentation pass checks that what shipped matches what the docs say, and promotes any durable new knowledge into its permanent home in the vault.
8. Operations review. The operations agent reads the diff and every reviewer’s verdict, proposes a set of clean atomic commits, and writes the deployment notes. It proposes; it does not yet act.
9. Readiness gate. Every agent states, in the affirmative, what it verified — not “no objections” but “I checked this and it passes.” Then I review the whole thing myself. Nothing ships until I say so.
10. Commit and deploy. With approval, the operations agent lands the commits, deploys, and runs post-deploy checks.
11. Retrospective and closure. A retrospective agent compares the session against past ones, interviews me about what to change, and — only with my answers in hand — updates the agents and their memory. A final pass closes out the originating plan and task so nothing drifts out of sync with the shipped code.

Each run happens in an isolated copy of the repository — its own working tree, on its own branch — so the pipeline can build, break, and rebuild without ever touching the live tree until the end. At deploy time the branch is fast-forwarded onto the main line only if it applies cleanly; a conflict halts the run for me to resolve rather than being forced through. When it is done, the isolated copy is torn down.

The whole thing rests on a few non-negotiables: specialists with strict ownership, tests before code, fix every finding, and a human gate before anything reaches production. The agents propose. I dispose.

The autonomous loop

The scheduled job is where the system works without me. A plain scheduler wakes on a fixed cadence, reads the task manager, and dispatches eligible work to agents. The task manager is the universal inbox for both machine work and human-in-the-loop work, because a two-inbox system fails the moment the dividing line drifts — a “fix this automation” task begins as a human question, becomes a diagnosis, becomes a fix, becomes a review. Keeping the whole life of a task in one place, with its comment thread as the durable record, means the task carries its own full history and nothing is lost at a handoff.

The unit of dispatch is the whole task tree, not the individual line. A parent task and its subtasks are handled together: the agent receives the entire tree, does its work, and writes the results back in one atomic update. Two clean predicates govern it — one decides whether a tree runs this cycle at all, the other decides which subtasks the agent acts on once it does. A task that leaves work unfinished yields rather than closing, carrying itself into the next cycle with a visible marker, and a built-in ceiling stops a task from driving itself in an endless loop.

The division of labor is the same one that makes the pipeline trustworthy. The scheduling wrapper is plain Python and handles everything that must be deterministic — timing, single-instance locking, backoff when the model API is rate-limited, spend and request budgets, retries, dead-lettering after repeated failure, and an audit that confirms an agent actually posted its result before the task is called done. The agent handles everything that needs judgment. Each dispatched task runs as its own process under an ordinary subscription rather than a metered per-token bill. Task text that came from a human is wrapped in fences the agent is told to treat as untrusted, so a task cannot smuggle in instructions. And because no one is watching at three in the morning, the pipeline runs in a headless mode that skips the human approval gates — while still running every test, lint, and security check.

The vault as connective tissue

Everything that is not code lives in one notes vault: design documents and plans, deep-research notes, bug post-mortems, audit reports, the reference material the agents read, and blog drafts like the source this page was tended from. The vault is the connective tissue. Research informs plans, plans drive implementation, implementation produces post-mortems and retrospectives, and retrospectives feed back into the agents as improved memory. A feature can begin as an overnight research task and end, several loops later, as a published post — and every stage leaves its trace in the same place.

One box, kept in sync

The machine is the whole of it. A file-sync tool keeps the vault mirrored to the laptop I edit notes on and to the server that runs my home automation, so I can write in a comfortable editor while the agents read the same files on the box. Git lives only on the box — all commits happen there and push to a self-hosted remote — while the sync tool moves file contents and git moves history, each doing the job it is good at.

The box reaches the outside world through a small, deliberate surface. It talks to external systems — the home-automation platform, the task manager, centralized logs and metrics, dashboards — through a standard protocol for giving a model tools, so an agent can query the house or read logs the same way it reads a file. Beyond the model API and the task manager, there are no cloud dependencies. Simple infrastructure, sophisticated orchestration.

What holds it together

A handful of principles do the real load-bearing work:

• Specialization beats generalization. A do-everything agent is mediocre across the board. Narrow agents with strict ownership produce better work and are far easier to debug.
• Deterministic wrappers make the model reliable. Scheduling, locking, and retry logic are Python, not judgment calls. The model does the judgment inside each task. That separation is what makes the system trustworthy enough to run unattended.
• “Fix everything” deletes a whole category of argument. No meetings about severity, no debates about whether something is really a bug. If an agent found it, it gets fixed. The only escape hatch is a real tradeoff that needs a human.
• The human stays in the loop. No code ships without my review, and no architectural call is final without my approval. Headless mode exists for overnight work where I pre-approved the scope, but even then the quality gates still run.
• Memory compounds. Comparing this session against every prior one catches what a single session cannot. The system gets better at being a system.
• Match the ceremony to the risk. Quick tasks take the quick path; anything touching production takes the full one. That table of which change gets which treatment is the most useful thing here, and it was earned one calibration at a time.

The agents handle execution. I handle direction. Every decision is logged, every finding is reported, and every commit is gated on approval.