Most teams treat Claude Code as a single agent. That is half the value.

The real unlock is sub-agents — specialized personas with their own system prompts, allowed tools, and rules. You don't talk to "Claude." You talk to code-reviewer, then to test-writer, then to migration-runner. Each one stays in its lane and does one thing well.

Here are the 11 sub-agents I run on every serious codebase, what they own, and the .claude/agents/<name>.md definitions that make them work.

Why sub-agents at all?

A monolithic agent is a generalist. Generalists are great when the problem is small. On a real codebase you want:

• A reviewer that only reviews and never writes code.
• A test-writer that never modifies application code.
• A migration runner that only runs migrations and stops.

The constraint is the feature. Each sub-agent is bound by a system prompt and a tool allowlist. That bounding is what makes them reliable.

The 11 I keep on every project

1. code-reviewer

Owns: post-implementation review. Reads diffs, never writes them.

# system
You review diffs. You do not modify files. You output:
1. Bugs (with file:line)
2. Risk areas (security, perf, breaking changes)
3. Style/convention violations against CLAUDE.md
4. A 1-line verdict: SHIP, FIX-FIRST, or REWRITE.

# tools
allow: ["git diff *", "rg *", "cat *"]
deny:  ["edit", "shell-write"]

2. test-writer

Writes new tests. Never edits production code. If the test fails, it reports the failure — it does not "fix" it.

3. test-fixer

The mirror image. Reads failing tests, modifies production code to make them pass, never edits the test itself unless the test is provably wrong.

4. migration-runner

Runs DB migrations. Allowed: pnpm db:migrate, psql -c "...". Denied: every other shell command.

5. dependency-auditor

pnpm outdated, pnpm audit, npm-check-updates. Outputs a markdown table of upgrades + risk. Does not run upgrades unsupervised.

6. release-bot

Generates changelogs, version bumps, tags. Never pushes — push is human-only.

7. docs-writer

Touches README.md, docs/, JSDoc comments. Forbidden from src/ and app/.

8. refactor-surgeon

Pure refactors. Constraint: zero behaviour change, all tests must pass before and after. If a test fails, the refactor was not pure — back out.

9. incident-responder

The one you only summon during an outage. Reads logs, writes a postmortem skeleton, suggests rollback commands. Never runs production commands.

10. architect

Read-only. Looks at the codebase, produces an ADR (architecture decision record) draft when you ask "should we add X?"

11. ci-fixer

Reads .github/workflows/, the failing CI logs, and proposes minimal changes. Allowed to push branches, never to push to main.

What goes in .claude/agents/<name>.md

Each agent is one file. Here's the canonical shape:

---
name: code-reviewer
model: claude-sonnet-4
---

# system
<persona + scope + output format>

# tools
allow: [...]
deny: [...]

# CLAUDE.md respect
Read project CLAUDE.md before acting.

That is it. Commit this folder; everyone on the team gets the same crew.

How they collaborate (without being called "multi-agent")

This is not yet multi-agent pipelines (that is Article 7). It is the simpler choreography:

You → /agents → pick test-writer → "write tests for lib/cache.ts"
  → /agents → pick test-fixer    → "make them pass"
  → /agents → pick code-reviewer → "review the diff"
  → /release-notes

Each step is bounded. Each step is reviewable. You never have a single agent that "wrote the tests, fixed the code, reviewed itself, and pushed to main." That kind of self-review is exactly the failure mode you want to design out.

The naming rule

Sub-agents are named after roles, not tools. code-reviewer, not claude-with-rg. migration-runner, not psql-runner. Roles compose; tools don't.

When a new teammate joins, they read .claude/agents/ once and immediately understand the operating model. That is documentation by configuration.

A live example: shipping a feature with the crew

You: /agents test-writer
> Write vitest cases for lib/cache.ts covering TTL expiry and LRU eviction.
test-writer: <writes 2 tests, both fail, reports>

You: /agents test-fixer
> Make those tests pass without changing lib/cache.test.ts.
test-fixer: <implements TTL + LRU in lib/cache.ts, tests green>

You: /agents code-reviewer
> Review the diff.
code-reviewer: SHIP.

You: /release-notes
release-bot: <writes changelog>

You: git checkout -b feat/cache-lru && git commit && gh pr create

You wrote ~20 lines of natural language. Three different specialists wrote / verified / signed off the actual code. That is the workflow.

Building your own

Start with two: code-reviewer and test-writer. Use them on every PR for a week. You will discover where the friction is and add the third one organically — usually ci-fixer or migration-runner.

By month two, every team I've onboarded has 6-8 sub-agents committed in .claude/agents/, and they're treated like infrastructure.

---

Next article: Production Codebase Safety — permissions, guardrails, and the things you should never let any sub-agent touch unsupervised.