"Multi-Agent Parallel Development" Is Just Terminal Windows Times Git Worktrees
"Multi-agent parallel development" sounds like there's a scheduler somewhere, coordinating several AI instances that talk to each other and divide up the work. There isn't.
Each terminal window running Claude Code is an independent agent instance, and instances do not communicate directly with each other. What "parallel agents" actually means is: multiple terminal windows, each pointed at a different git worktree — a full working directory checked out against its own branch, so multiple branches can be checked out and edited side by side without touching each other's files. Three terminals, each cd'd into a different worktree, each running its own claude process. That's the whole mechanism.
Each Claude instance only knows three things: its own terminal's conversation history, the code files inside its own worktree directory, and the project's root CLAUDE.md (loaded automatically). Anything that needs to cross terminals has to be carried across by hand.
What has to be true first
Three conditions, none of them optional:
- Every track needs its own design doc. A DD is the agent's work order — without one, there's no boundary to enforce.
- Shared base components are already merged into main. The parallel agents all depend on these components; nobody should be rebuilding them from scratch mid-track.
- Each track's file directories are fully separated. If two tracks ever need to touch the same file, the isolation breaks immediately — that's the actual precondition for "parallel" to mean anything.
The full workflow
Step one: create the worktrees. From the main repo directory (not inside any worktree), run git worktree add .worktrees/{track} feat/{track}, one per track. Worth adding .worktrees/ to .gitignore so it doesn't clutter the repo.
Step two: open a new terminal, initialize the agent. cd into the worktree, start claude. The first message matters a lot — Claude Code starts with an empty context, and that message is what determines its sense of role: who it is, what it's doing, where the design intent lives, and what's out of bounds. Leave it vague and the agent won't infer the rest on its own.
Step three: the agent works independently. Read the DD for design intent, read CLAUDE.md for architectural conventions, read the current code to understand the state of things, then implement against the DD's plan step by step, run self-tests (typecheck/build), and report "done, ready for review."
Step four: review. The trigger is plain — a single line like "review the feat/{track} branch." The agent runs git diff main...feat/{track}, produces a report in a fixed format, and writes it to the review-docs directory. Review and dev can be the same Claude instance switching roles in one window, or a separate terminal dedicated to review.
Step five: fix by tier. Category A (critical/major bugs, architecture violations) gets fixed immediately. Category B (refactor suggestions, low-priority items) goes into an enh-todo.md and doesn't block this round. Once fixed, the agent writes back to the REV report — checks it off, appends the fix record.
Step six: squash merge — collapsing every WIP commit from the branch into a single clean one on main, instead of importing the whole messy history. Back on the main terminal: git checkout main && git merge --squash feat/{track}, then a single commit. Keeps main's history readable.
Step seven: clean up. git worktree remove .worktrees/{track}, and optionally delete the local branch.
Questions that come up
Will two agents ever touch the same file? No, as long as the worktrees stay fully isolated and each track's directories don't overlap. If a shared file genuinely needs a change (say, types/api.ts), make that change on main first, then have each worktree pull it down.
Can one track merge before another finishes? Yes. Track branches are independent and don't affect each other — whichever finishes first merges first, and the remaining tracks sync the base with git rebase main.
Main keeps moving — how do worktrees keep up? git fetch origin && git rebase origin/main. Same as using worktrees under any other circumstance.
Where I land on this
What actually makes this workflow work isn't the word "parallel" — it's the combination of worktree isolation plus a DD as the boundary. Physical directory separation rules out two agents ever stepping on the same file by accident. The design doc does the job that would otherwise require agents to talk to each other: it gives instances with zero communication a shared, explicit sense of what they should and shouldn't touch.
Long-term, "multi-agent collaboration" as a phrase will probably keep getting broken down into two plainer questions: how task boundaries get drawn, and how state gets isolated. A chatty scheduler isn't a requirement. Physical isolation plus a work order written down clearly is usually enough.