Claude Code Multi-Agent Review Workflow: Roles, Worktrees, and Manual Sign-off
A structured multi-agent workflow for Claude Code: separating author and reviewer roles, isolating workspaces with Git worktrees, and enforcing manual engineer sign-off.
Building fully autonomous "AI agent teams" with automated code merging often introduces subtle architectural defects, circular refactoring loops, and codebase degradation. Two agents running in parallel do not constitute independent ground truth: if the author agent makes a logical error, a reviewer agent operating on similar prompt foundations may easily overlook it.
A reliable multi-agent workflow is built not on the illusion of full autonomy, but on strict role separation: a dedicated implementer (Author), an independent verifier (Reviewer), and a human developer who makes the final merge decision (Decision Maker).
1. Role Boundaries: Author, Reviewer, and Human Engineer
In an effective AI development workflow, each participant has a closed, well-defined scope of responsibility:
2. Context and Workspace Isolation
Never run the author and reviewer agents within the same working directory or shared conversation thread. Isolate them across three operational levels:
- Session Context: Independent conversation threads prevent mutual hallucination and circular confirmation.
- Filesystem Isolation: Separate Git worktrees ensure the reviewer inspects only committed diffs without dirty working tree state.
- Environment Security: API keys and runtime credentials remain in environment variables and are never passed in prompt text.
Worktree Preparation Commands:
[!IMPORTANT]
API Configuration: Each Claude Code session operates using its own dedicated API credentials configured through OS environment variables. Follow the official setup guide in BetterToken Claude Code Docs.
3. The Structured Handoff Contract
When the author agent completes implementation, it produces a concise handoff card. Raw chat transcripts, secrets, and unverified assumptions are strictly excluded:
Handoff Card
- Task: Add HTTP 429 retry support in payment client with exponential backoff.
- Branch:
feat/payment-retry - Changed Files:
src/client/http.ts,tests/http-retry.test.ts - Verification Command:
npm test -- tests/http-retry.test.ts(Passed) - Risks & Blockers: Exponential backoff capped at 3 attempts; socket timeout left unchanged.
- Next Step: Reviewer agent validates Retry-After header handling.
4. Human-in-the-Loop Sign-off Protocol
The reviewer agent performs an isolated evaluation:
- Navigates to the clean worktree:
../agent-reviewer. - Executes the recorded verification command.
- Conducts an independent diff inspection for side effects and edge cases.
- Generates a structured summary for the lead engineer.
The engineer performs the final sign-off:
- Reviews findings from the reviewer agent;
- Confirms zero regressions against
main; - Executes the merge manually:
git merge feat/payment-retry.
This multi-agent pipeline prevents mutual hallucination loops while keeping code quality and architectural ownership firmly under developer control.