Claude Code Multi-Agent Review Workflow: Roles, Worktrees, and Manual 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). In an effective AI development workflow, each participant has a closed, well-defined scope of responsibility: Role Core Responsibility Input Artifacts Output Artifacts Author Agent Code implementation, local unit tests Task description, completion criteria Git branch, diff, focused test suite Reviewer Agent Edge case discovery, regression checking Git diff, handoff card, verification commands Structured review checklist (Pass/Block) Human Decision Maker Architectural validation, final merge Reviewer summary, CI/CD status Manual merge to main branch 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. git worktree add ../agent-author -b feat/payment-retry git worktree add ../agent-reviewer feat/payment-retry [!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. 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. 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. Originally published on the BetterToken blog. BetterToken provides pay-as-you-go access to AI model APIs through docs to get started.