A maioria dos times trata Claude Code como um único agente. Isso é metade do valor.

O destrancamento real são os sub-agentes — personas especializadas com seus próprios system prompts, ferramentas permitidas e regras. Você não fala com "Claude". Fala com code-reviewer, depois com test-writer, depois com migration-runner. Cada um fica na pista dele e faz uma coisa bem-feita.

Aqui estão os 11 sub-agentes que rodo em todo codebase sério, o que cobrem e as definições .claude/agents/<nome>.md que os fazem funcionar.

Por que sub-agentes?

Um agente monolítico é generalista. Generalista é ótimo em problema pequeno. Em codebase real você quer:

• Um reviewer que só revisa e nunca escreve código.
• Um test-writer que nunca mexe no código de aplicação.
• Um migration-runner que só roda migrações e para.

A restrição é a feature. Cada sub-agente é amarrado por um system prompt e uma allowlist de tools. Esse limite é o que os torna confiáveis.

Os 11 que mantenho em todo projeto

1. code-reviewer

Cobre: revisão pós-implementação. Lê diffs, nunca escreve.

# system
Você revisa diffs. Não modifica arquivos. Devolve:
1. Bugs (com arquivo:linha)
2. Áreas de risco (segurança, performance, mudanças que quebram)
3. Violações de estilo/convenção contra o CLAUDE.md
4. Veredito de 1 linha: SHIP, FIX-FIRST ou REWRITE.

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

2. test-writer

Escreve testes novos. Nunca edita código de produção. Se o teste falha, ele reporta — não "conserta".

3. test-fixer

A imagem espelhada. Lê testes que falharam, modifica código de produção para passarem, nunca edita o teste a não ser que ele esteja comprovadamente errado.

4. migration-runner

Roda migrações de DB. Permitido: pnpm db:migrate, psql -c "...". Negado: todo o resto.

5. dependency-auditor

pnpm outdated, pnpm audit, npm-check-updates. Devolve uma tabela markdown de upgrades + risco. Não roda upgrades sem supervisão.

6. release-bot

Gera changelogs, bumps de versão, tags. Nunca dá push — push é humano.

7. docs-writer

Mexe em README.md, docs/, comentários JSDoc. Proibido em src/ e app/.

8. refactor-surgeon

Refactors puros. Restrição: zero mudança de comportamento, todos os testes têm que passar antes e depois. Se um teste quebra, o refactor não foi puro — reverte.

9. incident-responder

O que você só chama em outage. Lê logs, escreve esqueleto de postmortem, sugere comandos de rollback. Nunca roda comandos de produção.

10. architect

Read-only. Olha o codebase, produz um rascunho de ADR (architecture decision record) quando você pergunta "devemos adicionar X?"

11. ci-fixer

Lê .github/workflows/, os logs de CI falhados, e propõe mudanças mínimas. Pode dar push em branches, nunca em main.

O que vai em .claude/agents/<nome>.md

Cada agente é um arquivo. Esse é o formato canônico:

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

# system
<persona + escopo + formato de saída>

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

# Respeito ao CLAUDE.md
Leia o CLAUDE.md do projeto antes de agir.

Só isso. Comite essa pasta; todo o time recebe a mesma equipe.

Como eles colaboram (sem se chamar "multi-agente")

Isso ainda não é pipeline multi-agente (artigo 7). É a coreografia mais simples:

Você → /agents → escolhe test-writer → "escreva testes para lib/cache.ts"
  → /agents → escolhe test-fixer    → "faça eles passarem"
  → /agents → escolhe code-reviewer → "revise o diff"
  → /release-notes

Cada passo é limitado. Cada passo é revisável. Você nunca tem um único agente que "escreveu os testes, consertou o código, se autorrevisou e deu push em main". Esse tipo de autorrevisão é exatamente o modo de falha que você quer projetar para fora.

Regra de nomes

Sub-agentes se chamam pelos papéis, não pelas tools. code-reviewer, não claude-com-rg. migration-runner, não psql-runner. Papéis compõem; tools não.

Quando alguém novo entra, lê .claude/agents/ uma vez e entende imediatamente o modelo operacional. Isso é documentação por configuração.

Exemplo ao vivo: entregando uma feature com o time

Você: /agents test-writer
> Escreva casos vitest para lib/cache.ts cobrindo expiração TTL e despejo LRU.
test-writer: <escreve 2 testes, os dois falham, reporta>

Você: /agents test-fixer
> Faça esses testes passarem sem alterar lib/cache.test.ts.
test-fixer: <implementa TTL + LRU em lib/cache.ts, testes verdes>

Você: /agents code-reviewer
> Revise o diff.
code-reviewer: SHIP.

Você: /release-notes
release-bot: <escreve changelog>

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

Você escreveu ~20 linhas em linguagem natural. Três especialistas diferentes escreveram / verificaram / aprovaram o código real. Esse é o workflow.

Construa os seus

Comece com dois: code-reviewer e test-writer. Use os dois em cada PR por uma semana. Você descobre onde está o atrito e adiciona o terceiro organicamente — normalmente ci-fixer ou migration-runner.

No segundo mês, todo time que onboardei tem 6-8 sub-agentes commitados em .claude/agents/, tratados como infraestrutura.

---

Próximo artigo: Segurança em codebase de produção — permissões, guard-rails e o que nenhum sub-agente deveria encostar sem supervisão.