Agent Roles

A multi-agent setup is not "more agents, more throughput." It is a way to manufacture something a single session cannot produce: independent judgment. One agent that writes code and then reviews its own code is one agent grading its own homework — it will re-derive the same wrong assumption twice and call it verified. Two agents with separate contexts — one building, one reviewing the diff cold against the spec — disagree in exactly the places where the builder guessed. That disagreement is the product.

So the taxonomy below is not org-chart cosplay. Each role exists because it needs a different context than the others: different inputs, different mandate, and hard limits on what it may touch. Get the separation right and two mediocre agents outperform one brilliant one. Get it wrong — share a session, paste the builder's reasoning into the reviewer — and you have one agent wearing two hats, plus double the token bill.

The taxonomy

Role	Mandate	Inputs	Outputs	Must NOT do
Builder	Implement one scoped task to spec, on its own branch	Spec, CLAUDE.md, interface contracts, acceptance criteria	Branch/PR with code + tests, notes on assumptions made	Expand scope, change interfaces, edit the spec, review itself
Reviewer	Find where the diff violates the spec, conventions, or safety	The diff, the spec, CLAUDE.md — never the builder's session or reasoning	Findings list: severity, file:line, why it's wrong	Fix the code, praise the code, accept "the builder probably had a reason"
Architect / planner	Turn a goal into a plan: decomposition, interfaces, risks, sequencing	Codebase read access, requirements, constraints, decision records	Plan doc / spec for human approval; interface contracts	Write implementation code, make product decisions, approve its own plan
Tester	Write acceptance tests from the spec — before or independent of implementation	Spec only (deliberately not the implementation)	Failing-first test files, coverage of edge cases the spec names	Read the implementation to decide what to test; weaken tests to pass
Security	Audit a diff or subsystem for authz, injection, secrets, unsafe defaults	Diff, threat notes, security conventions doc	Findings with exploit sketch + severity; watchlist updates	"Fix" issues by broadening permissions; sign off on code it patched
Research	Answer a question with evidence: library choice, API behavior, codebase archaeology	The question, repo and/or web access	Findings doc with sources, options table, recommendation	Make the decision; start implementing "while it's here"
Documentation	Sync docs to code: README, API docs, runbooks, CLAUDE.md updates	The merged diff, existing docs	Doc updates in the same PR or immediately after	Invent behavior not in the code; document aspirations as facts
Refactor	Structure-only change: extract, rename, dedupe — behavior frozen	Target modules, conventions, characterization tests	Diff with zero behavior change, proven by untouched tests	Mix in features or fixes; touch test expectations
Release	Mechanical release chores: changelog, version bumps, migration notes	Merged PRs since last tag, release checklist	Changelog PR, release notes, checklist evidence	Decide whether to ship; touch application code

Two rules cut across every row:

1. A role's power comes from what it doesn't see. The tester writes better tests because it hasn't seen the implementation. The reviewer catches assumption bugs because it never heard the builder's justification.
2. A role's safety comes from what it can't do. The reviewer that fixes code becomes a second builder — and now nobody reviewed the fix. Keep mandates narrow and enforce them in the role prompt.

The independence rule

This is the whole point of the page, so stated bluntly:

A reviewer that shares the builder's context is not a reviewer. It has already read the builder's plan, absorbed the builder's interpretation of the spec, and watched the builder rationalize each shortcut. It will confirm, not check.

The failure is mechanical, not motivational. An LLM's output is conditioned on everything in its context window. If the builder decided "the spec's 'idempotent retries' probably just means catch duplicate-key errors," and that reasoning sits in context, the reviewer inherits the interpretation as an established fact and evaluates the code against it — the code passes. A fresh session gets only the spec's words, interprets "idempotent retries" independently, and flags the mismatch. Independent judgment is created by information hygiene: same spec, different context windows, zero shared conversation.

Practical consequences:

• Reviewer input is the diff + spec + repo docs. Never paste the builder transcript, the builder's summary, or "the agent said it handled X."
• Same model in two fresh sessions is fine; the independence comes from context separation, not model diversity. A different model adds a second layer (different blind spots) — useful for security-critical review, optional otherwise.
• If the reviewer asks "why did the builder do X?", the correct answer is "irrelevant — is X correct against the spec?"
• The human stays arbiter. When builder and reviewer disagree, that disagreement is a flag on an under-specified point — resolve it in the spec, not in chat. Full protocol in Patterns.

Claude Code specifics

Claude Code has two native mechanisms for role separation:

Subagents run in separate context windows by construction. When a main session spawns a subagent (via the Task tool or a custom agent), the subagent gets its own window, does its work, and returns only its final report — the parent never sees the subagent's intermediate reasoning, and the subagent never sees the parent's conversation. That's the independence property for free. Caveat: a subagent spawned by the builder's session still receives whatever the builder puts in the task prompt — keep that prompt to "review this diff against docs/specs/billing.md", not a summary of the builder's approach.

Custom agent definitions live in .claude/agents/*.md — one file per role, with frontmatter for name, description, allowed tools, and model, then the role prompt as the body. This makes roles versioned, reviewable repo artifacts instead of prompts someone retypes:

---
name: reviewer
description: Adversarial spec-compliance review of a diff. Use after any builder task completes.
tools: Read, Grep, Glob, Bash
---

You are an independent code reviewer. You did not write this code and you
do not know why the author made any choice — evaluate only what is on the page.

Review the given diff against the referenced spec and CLAUDE.md. Report findings
as: severity (blocker/major/minor) · file:line · what's wrong · which spec line
or convention it violates. Hunt specifically for: silently narrowed requirements,
weakened error handling, security-relevant changes, tests that assert less than
the spec demands. Zero findings is a suspicious result — state explicitly what
you checked and found clean.

Do NOT modify any file. Do NOT suggest the author "probably intended" anything.

Note the tool list: read-only plus Bash for running tests. Tool restriction is mandate enforcement — a reviewer without Edit cannot drift into fixing.

For fully separate concurrent roles (parallel builders, long-running review), use separate Claude Code processes in separate git worktrees rather than subagents — subagents share the parent's working directory.

Mapping roles to tools

If you run a multi-tool shop, map roles to tools by their interaction shape — but hold the mapping loosely:

Role	Reasonable tool fit	Why
Builder	Claude Code, Codex-style autonomous agents	Long-horizon, multi-file, test-run-fix loops; needs repo-wide tool access
Reviewer	Claude Code subagent or fresh session; optionally a different model	Needs the diff + docs and read-only tools; benefits from fresh context
Interactive editor	Cursor / Copilot-style in-IDE	Human-in-the-loop line-level work; wrong shape for autonomous roles
Architect	A chat model with the spec and pasted excerpts, or Claude Code plan mode	Planning is dialogue + reading, not editing; plan mode enforces read-only
Verification / second opinion	A different model than the builder	Different training → different blind spots on security and correctness

The caveat that matters: roles matter more than tools. Every failure this section prevents — self-confirming review, scope creep, interface drift — is caused by context contamination and missing mandates, not by tool choice. A disciplined builder/reviewer split inside one tool beats five tools sharing one conversation. Buy separation, not logos.

Related

• Coordination — how separated roles share state without sharing context: git, worktrees, and docs as the only channel.
• Patterns — the builder + reviewer protocol and four other role compositions, with prompts.
• CLAUDE.md and AGENTS.md — the shared ground truth every role prompt points at.
• Reviewing AI PRs — the human review layer that stays on top of any agent reviewer.
• Responsibility Split — which judgments never get delegated to any role.