TL;DR e veredito
O artigo da Anthropic sobre dobrar subagents no loop principal diz para usar menos deles, e os vídeos feitos a partir dele dizem "apague seus subagents". O artigo ainda mantém três casos e dá um teste para todo o resto s1. Este pacote traz os três arquivos que passam nesse teste (um scout de pesquisa, um reviewer somente leitura, um builder isolado), o quarto arquivo que passamos pelo teste (um test writer) e o script que o rodou.
- O scout, o reviewer e o builder respondem cada um a um caso de manter, e cada um tem seu motivo escrito na sua
description. - O quarto agent, um test writer, passou pelo fold test: seis tarefas, duas execuções cada, uma vez como subagent e uma vez dobrado numa skill. Dobrado numa skill, passou em 12/12. Como subagent, passou em 11/12, a 0,410 dólar por execução em média contra 0,262, e 72 segundos contra 36.
- Então o test writer perdeu seu arquivo. A versão dobrada nunca teve nota pior.
Veredito: mantenha os três arquivos e passe todo outro agent pelo fold test antes de ele ganhar um arquivo. Pule o scout em consultas rápidas, nunca mande o builder para código que sua sessão principal está editando e leia a lista de "não verificado" do reviewer com o mesmo cuidado que o veredito dele. Os limites são reais: doze execuções por lado em um único repositório, e o único erro do subagent foi um comando de teste que as configurações do nosso projeto não permitiam. Rode no seu repositório.
Síntese com fontes
O artigo mantém subagents em três casos. Use-os quando um único loop de agent sofre degradação mensurável de desempenho por inchaço de contexto, quando várias tarefas rodam em paralelo com janelas de contexto novas que podem ser descartadas, ou quando um único agent tem dificuldade para escolher a ferramenta certa ou enfrenta instruções conflitantes no prompt de sistema s1.
O teste de dobrar de volta. Monte um eval pequeno de ponta a ponta, dobre um subagent e só o mantenha como subagent se a versão dobrada tiver nota pior, depois repita s1. O artigo é escrito para agents da Claude Platform e não fala de arquivos do Claude Code, então aplicamos o teste dele por analogia s1.
Como dividir se você mantiver um. Divida por contexto: dê a cada subagent uma peça de trabalho que precise de pouco do resto do sistema e faça-o devolver um resultado compacto s1. É por isso que o scout leva um contrato de retorno e o reviewer um formato de resposta.
Um arquivo de subagent é um arquivo Markdown com frontmatter YAML. Só name e description são obrigatórios, e tools herda todas as ferramentas disponíveis para subagents se for omitido s2. Então um agent somente leitura precisa listar suas ferramentas explicitamente. Para impedir que um reviewer inicie ajudantes, omita Agent da lista de ferramentas dele ou adicione-o a disallowedTools s2.
Você escreve os arquivos à mão. O Claude Code 2.1.198 removeu o assistente /agents: peça ao Claude para criar ou gerenciar subagents, ou edite .claude/agents/ diretamente. Ele também passou a rodar subagents em segundo plano por padrão s24 s3.
maxTurns e isolation: worktree fazem o que o builder precisa. Quando o subagent atinge o limite de maxTurns, o Claude Code devolve a saída dele marcada como parcial s2. O isolamento por worktree dá ao subagent uma cópia isolada do repositório, criada por padrão a partir da sua branch padrão e não do HEAD da sessão pai, e o worktree é limpo se o subagent não fizer mudanças s2. A versão 2.1.295 corrigiu subagents em seu próprio worktree vinculado que mostravam a branch git da sessão pai s3. Rodamos na 2.1.294.
Leituras abrem em paralelo, escritas ficam em um só. Abra em paralelo para leituras, fique em um só para escritas s8. É por isso que o pacote tem um builder e nunca uma equipe.
Abrir em paralelo custa tokens e, em buscas comuns, não acha nada a mais. Setups com vários agents costumam usar de 3 a 10 vezes mais tokens do que abordagens com um único agent para tarefas equivalentes s4. Num benchmark de 288 execuções, o recall ficou entre 97% e 100% em todas as condições, e o custo por execução subiu de 74% a 116% no Haiku 5.5 e de 143% a 221% no Opus 5.5 s5. O scout compensa quando a leitura é grande e sua sessão tem mais trabalho depois.
Um reviewer precisa de evidência, ou inventa achados. Numa issue, um reviewer apontou código correto por falta de informação de versão, e o agent principal repassou o achado sem verificar s12. Por isso o arquivo do nosso reviewer recusa qualquer achado sem uma linha citada. Um reviewer que acaba aprovando tudo também parou de funcionar s11, então confira de vez em quando se o seu ainda encontra alguma coisa.
Pastas de agents apodrecem. Um desenvolvedor relatou que 16 agents importados nunca foram acionados em duas semanas s10. Um subagent em segundo plano também pode travar num pedido de permissão, como mostra a issue aberta sobre subagents com worktree isolado s13.
O sistema de pesquisa da própria Anthropic é um fan-out. Ele mostra onde as leituras em paralelo compensam s14. A maioria das tarefas de programação tem menos partes realmente paralelizáveis do que a pesquisa.
Código
Nota de instalação: coloque os arquivos de agent em .claude/agents/ do seu projeto. Eles são detectados poucos segundos depois de salvos, a não ser que o diretório agents não existisse quando a sessão começou, e nesse caso reinicie s2. A linha de convenções do reviewer (dinheiro em centavos inteiros, funções de domínio que nunca mutam, erros lançados como ValidationError, NotFoundError ou ConflictError) descreve a nossa API de faturas de exemplo: troque pelas suas próprias convenções.
O scout responde ao caso de contexto inchado. Ele tem só Read, Grep e Glob, roda no modelo barato haiku e devolve no máximo 12 linhas: a resposta, a prova como path:line e o que ele não encontrou. Coloque-o como .claude/agents/scout.md e peça um scout por pergunta independente, em paralelo.
scout.md
---
name: scout
description: Read-only researcher for one question about this codebase that needs many files read but only a short answer back. Use proactively, one scout per independent question, in parallel.
tools: Read, Grep, Glob
model: haiku
---
You answer one question about this codebase. Read what you need. Never edit anything.
Return at most 12 lines:
1. The answer, in plain words, first.
2. The proof: the files and lines that show it, as path:line.
3. What you did not find or are not sure of.
No code block longer than 5 lines.
O reviewer responde ao caso de verificação com olhar novo. Só Read, Grep e Glob, sem Agent, então ele não pode editar nem iniciar ajudantes. Entregue a ele a especificação e o diff (git diff main...<branch>) e verifique cada achado você mesmo antes de agir. Coloque-o como .claude/agents/reviewer.md.
reviewer.md
---
name: reviewer
description: Read-only code reviewer. Use after a change is built, with the spec and the diff in the prompt. Returns a verdict with file:line evidence. Never edits.
tools: Read, Grep, Glob
model: sonnet
---
You review one change against its spec. The spec and the diff are in your prompt; read the surrounding code you need to judge them.
Look for what breaks: wrong behaviour against the spec, an edge case the code or its tests miss, a broken convention of this repo (money in integer cents, domain functions never mutate, errors thrown as ValidationError, NotFoundError or ConflictError).
Answer in this shape, nothing else:
VERDICT: PASS or FAIL
FINDINGS (most serious first, at most 5):
- [high|medium|low] path:line - what breaks, and the line that proves it, quoted
UNVERIFIED:
- anything you suspect but could not prove from the code
No style remarks. No finding without a quoted line.
O builder responde ao caso do componente separado. isolation: worktree dá a ele a própria cópia do repositório e a própria branch, e maxTurns: 40 impede que um builder ande em círculos. Dê a ele uma peça independente enquanto você continua trabalhando e faça o merge depois que o reviewer aprovar. Coloque-o como .claude/agents/builder.md e troque os comandos de instalação e de teste pelos seus.
builder.md
---
name: builder
description: Builds one self-contained component with a clean interface, tests included, in its own git worktree. Use when a separate piece can be built while the main session keeps working. Never for changes to code the main session is editing.
isolation: worktree
maxTurns: 40
model: inherit
---
You build exactly the component in your prompt, in this worktree, and nothing else.
1. Run `git branch --show-current` and `git rev-parse --show-toplevel` and report both.
2. If node_modules is missing, run `pnpm install --frozen-lockfile`.
3. Write the code and its tests. Follow the conventions in README.md.
4. Run `pnpm test` and `pnpm typecheck` until both are green.
5. Commit on your branch with a one-line message.
Report in at most 10 lines: branch, files changed, test count before and after, anything you did not do.
O test writer é o quarto arquivo, o que o fold test removeu. Ele está aqui para você rodar o mesmo teste nele, ou usá-lo como modelo do agent que está prestes a adicionar. Se você o mantiver, ele vai em .claude/agents/test-writer.md.
test-writer.md
---
name: test-writer
description: Writes vitest tests for one module of this repo. Use proactively when the user asks to add or improve tests for a file or module.
tools: Read, Grep, Glob, Edit, Write, Bash
model: inherit
---
You write tests for exactly one module.
1. Read the module and the code that calls it. Read the existing test file for it, if any.
2. Add the missing cases to the test file under test/ (create it if none exists): boundaries, empty and invalid input, every branch, and anything the code promises in a comment.
3. Never edit files under src/. If a test reveals a bug, keep the test, mark it `it.fails`, and say so.
4. Run `pnpm test` until the suite is green.
Report in at most 6 lines: the test file, the cases added, the test count before and after.
As configurações de projeto usadas nas execuções. O builder e o test writer só rodam o que as configurações permitem, então uma lista de permitidos que esquece um comando pode custar uma execução: foi assim que aconteceu o nosso único erro de subagent. Incorpore as linhas de que precisar em .claude/settings.json.
ledgerly-settings.json
{
"permissions": {
"allow": [
"Bash(pnpm test)", "Bash(pnpm test:*)", "Bash(pnpm typecheck)", "Bash(pnpm install:*)",
"Bash(npx vitest:*)", "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)",
"Bash(git add:*)", "Bash(git commit:*)", "Bash(git branch:*)", "Bash(git rev-parse:*)", "Bash(git worktree list)",
"Edit", "Write"
]
}
}
ledgerly-settings.json on GitHub
O harness do fold test, em quatro arquivos. run-one.sh roda uma tarefa como subagent ou dobrada numa skill, com o mesmo prompt de usuário. score.py aplica a regra de aprovação decidida de antemão: suíte verde, nenhum arquivo de código-fonte alterado e o bug plantado pego. mutations.py guarda um bug plantado por módulo. jobs.txt lista as seis tarefas, duas execuções cada, alternando as variantes. Os caminhos apontam para a nossa pasta de rascunho e para os nossos módulos de exemplo, então troque o caminho raiz e as mutações para combinar com o seu repositório antes de rodar.
run-one.sh
#!/bin/bash
# One fold-test run: run-one.sh <variant agent|skill> <task> <n>
# Copies ledgerly, sets up the variant, sends the same user prompt, scores the result.
set -u
V=$1; T=$2; N=$3
ROOT=/private/tmp/subagents-bench
W=$ROOT/eval/runs/$V-$T-$N
rm -rf "$W"; mkdir -p "$W"; cp -R "$ROOT/ledgerly/." "$W/"
cd "$W"
if [ "$V" = skill ]; then
# Fold: the subagent's prompt becomes a skill in the main loop; the agent file moves aside
mkdir -p .claude/skills/test-writer
BODY=$(awk 'f>=2{print} /^---$/{f++}' .claude/agents/test-writer.md)
{ printf -- '---\nname: test-writer\ndescription: Write vitest tests for one module of this repo. Use when the user asks to add or improve tests for a file or module.\n---\n'; printf '%s\n' "$BODY"; } > .claude/skills/test-writer/SKILL.md
git mv .claude/agents/test-writer.md .claude/test-writer.agent.md.aside
git add -A .claude && git commit -qm "eval: fold test-writer into a skill"
fi
FILE=$(python3 -c "import sys;sys.path.insert(0,'$ROOT/eval');from mutations import MUTATIONS;print(MUTATIONS['$T'][0])")
START=$(date +%s)
claude -p "Add tests for $FILE." --model opus --setting-sources project,local \
--output-format stream-json --verbose --permission-mode acceptEdits > run.jsonl 2> run.err
END=$(date +%s)
# Score
SRC_CHANGED=$(git status --porcelain -- src | wc -l | tr -d ' ')
npx vitest run > after.txt 2>&1 && GREEN=1 || GREEN=0
TESTS=$(grep -Eo 'Tests +[0-9]+ passed' after.txt | grep -Eo '[0-9]+' | head -1)
python3 - "$W" "$T" <<'PY'
import sys; sys.path.insert(0, "/private/tmp/subagents-bench/eval")
from mutations import MUTATIONS
w, t = sys.argv[1], sys.argv[2]; f, old, new = MUTATIONS[t]
p = f"{w}/{f}"; s = open(p).read(); open(p, "w").write(s.replace(old, new))
PY
npx vitest run > mutant.txt 2>&1 && KILLED=0 || KILLED=1
git checkout -q -- "$FILE"
python3 "$ROOT/eval/score.py" "$W" "$V" "$T" "$N" "$SRC_CHANGED" "$GREEN" "${TESTS:-0}" "$KILLED" "$((END-START))" >> "$ROOT/eval/results.jsonl"
tail -1 "$ROOT/eval/results.jsonl"
score.py
# Parse one run's stream-json and write a result row
import json, sys
w, v, t, n, src_changed, green, tests, killed, wall = sys.argv[1:]
delegated = skill = False
result = {}
for line in open(f"{w}/run.jsonl"):
try: e = json.loads(line)
except Exception: continue
if e.get("type") == "assistant":
for b in e["message"].get("content", []):
if b.get("type") == "tool_use":
i = b.get("input", {})
if b["name"] in ("Agent", "Task") and i.get("subagent_type") == "test-writer": delegated = True
if b["name"] == "Skill" and "test-writer" in json.dumps(i): skill = True
if e.get("type") == "result": result = e
passed = int(src_changed) == 0 and green == "1" and killed == "1"
print(json.dumps({
"variant": v, "task": t, "run": int(n),
"invoked": delegated if v == "agent" else skill,
"pass": passed, "green": green == "1", "srcChanged": int(src_changed), "killed": killed == "1",
"tests": int(tests), "wallSec": int(wall),
"costUsd": result.get("total_cost_usd"), "durationMs": result.get("duration_ms"), "turns": result.get("num_turns"),
"usage": result.get("usage"), "modelUsage": result.get("modelUsage"), "isError": result.get("is_error"),
}))
mutations.py
# One planted mutation per golden task: (task id, file, old, new)
MUTATIONS = {
"money": ("src/domain/money.ts", "if (value < min) {", "if (value <= min) {"),
"customer": ("src/domain/customer.ts", "name.trim() === \"\"", "name === \"\""),
"invoice": ("src/domain/invoice.ts", 'invoice.dueDate < now.toISOString()', 'invoice.dueDate <= now.toISOString()'),
"validation": ("src/domain/validation.ts", "quantity < 1", "quantity < 0"),
"migrations": ("src/store/migrations.ts", "{ customer: 0, invoice: 0, invoiceNumber: 0 }", "{ customer: 0, invoice: 0, invoiceNumber: 1 }"),
"router": ("src/http/router.ts", "decodeURIComponent(m[i + 1])", "m[i + 1]"),
}
jobs.txt
skill money 1
agent customer 1
skill customer 1
agent invoice 1
skill invoice 1
agent validation 1
skill validation 1
agent migrations 1
skill migrations 1
agent router 1
skill router 1
agent money 2
skill money 2
agent customer 2
skill customer 2
agent invoice 2
skill invoice 2
agent validation 2
skill validation 2
agent migrations 2
skill migrations 2
agent router 2
skill router 2
O baseline-kill.sh confere as mutações primeiro: cada uma precisa fazer a suíte existente falhar, ou sobreviver quando deveria, antes de você confiar no eval.
baseline-kill.sh
#!/bin/bash
# For each mutation: apply on a scratch copy of ledgerly, run the suite, report killed/survived
set -u
SRC=/private/tmp/subagents-bench/ledgerly
for t in money customer invoice validation migrations router; do
W=$(mktemp -d /private/tmp/subagents-bench/eval/mut-XXXX); cp -R "$SRC/." "$W/"
python3 - "$W" "$t" <<'PY'
import sys; sys.path.insert(0, "/private/tmp/subagents-bench/eval")
from mutations import MUTATIONS
w, t = sys.argv[1], sys.argv[2]
f, old, new = MUTATIONS[t]
p = f"{w}/{f}"; s = open(p).read()
assert s.count(old) == 1, (t, s.count(old)); open(p, "w").write(s.replace(old, new))
PY
(cd "$W" && npx vitest run >/dev/null 2>&1) && echo "$t survived" || echo "$t killed"
rm -rf "$W"
done
Faça isto na segunda-feira
- Rode
claude --versione note que/agentsé só um aviso desde a 2.1.198: você cria arquivos de agent editando.claude/agents/ou pedindo ao Claude s24. - Liste os arquivos de agent que você tem hoje e escreva o motivo de manter cada um em uma frase. Se não consegue, ele é candidato a ser dobrado numa skill.
- Copie
scout.mdereviewer.mdpara.claude/agents/e adapte a linha de convenções do reviewer ao seu repositório. - Copie
builder.md, confira se sua lista de permitidos cobre os comandos de teste e de checagem de tipos dele e dê a ele uma peça de trabalho independente numa branch. - Monte um conjunto de referência de 6 prompts para o agent de que você duvida, cada um com uma regra de aprovação fixada antes de rodar: suíte verde, nenhum arquivo de código-fonte alterado, um bug plantado pego.
- Rode o
baseline-kill.sh(adaptado) para provar que cada bug plantado faz a suíte atual falhar. - Rode cada tarefa duas vezes como subagent, mova o arquivo do agent para o lado, coloque as mesmas instruções numa skill, rode cada tarefa duas vezes de novo e leia quais tarefas mudaram de resultado, não só a nota.
- Mantenha o arquivo do agent só se a skill tiver nota pior. Senão, apague-o.
Medições
As execuções foram no Claude Code 2.1.294 com Opus 5.5 em 2026-11-08. São pequenas: doze execuções por lado em um único repositório para o fold test, duas execuções por lado para o scout.
Fold test: test writer, 6 tarefas x 2 execuções x 2 variantes
| Variante | Invocado | Aprovado | Custo médio $ | Tempo médio s |
|---|---|---|---|---|
| agent | 12/12 | 11/12 | 0.410 | 72 |
| skill | 12/12 | 12/12 | 0.262 | 36 |
A única falha: agent/router/2 deixou um teste vermelho em test/router.test.ts ("matches the root path": expected null not to be null). Toda execução matou a mutação plantada do seu módulo, e nenhuma editou src/.
Scout, medido na sessão principal (mainCtx é o tamanho do contexto da sessão principal, spawns o número de scouts iniciados, durS a duração em segundos)
| Execução | mainCtx | spawns | custo $ | durS | turnos |
|---|---|---|---|---|---|
| audit-inline-1 | 45868 | 0 | 0.457 | 55 | 15 |
| audit-inline-2 | 47476 | 0 | 0.433 | 47 | 12 |
| audit-scout-1 | 30505 | 3 | 0.267 | 17 | 1 |
| audit-scout-2 | 33937 | 3 | 0.344 | 25 | 3 |
| inline-1 | 32294 | 0 | 0.273 | 29 | 7 |
| inline-2 | 33345 | 0 | 0.272 | 36 | 10 |
| scout-1 | 28966 | 3 | 0.223 | 18 | 1 |
| scout-2 | 30390 | 3 | 0.257 | 20 | 2 |
As linhas "audit" são a leitura grande (como cada middleware embutido de um grande framework de código aberto rejeita uma requisição). As outras linhas são três perguntas pequenas. Nas perguntas pequenas, o scout quase não economizou nada. Os scouts rodaram no haiku.
Para ir além
Agent Teams são outro mecanismo. Teams são sessões que trocam mensagens entre si, atrás de uma flag experimental, e nada neste pacote precisa deles s3.
Abrir em paralelo custa mais do que um chat. O sistema de pesquisa da própria Anthropic mede o custo multi-agent contra um chat, não contra um único agent, então não leia esse número como subagents contra um loop só s14. Nossa comparação contra um único agent é a tabela do scout acima.
Subagent contra skill, em uma linha. Um subagent começa com um contexto novo e isolado; uma skill roda na sua conversa principal, onde a sessão já conhece o repositório. É por isso que o test writer dobrado foi mais rápido.
Forks e retomada. Um fork herda a conversa inteira em vez de começar do zero, e um subagent parado pode ser retomado com todo o seu histórico. Não testamos nenhum dos dois; leia a documentação de subagents antes de depender deles s2.
Vários builders. Builders paralelos escrevendo ao mesmo tempo ficaram fora do escopo. A regra para começar é "leituras abrem em paralelo, escritas ficam em um só" s8.
Agents de persona. Arquiteto, gerente de produto e outros agents de organograma são o que o teste remove. O artigo da Anthropic alerta que a arquitetura de agents vira uma cópia do organograma s1.
FAQ
O scout sempre economiza contexto? Não. Nas nossas três perguntas pequenas ele quase não economizou nada, e abrir em paralelo em buscas comuns não achou nada a mais por um custo maior s5. Ele compensou na leitura grande, onde a sessão principal ficou menor.
Por que o reviewer não tem Edit nem Write?
Para que ele não corrija o que encontra, e omitir Agent o impede de iniciar ajudantes s2. Deixar tools de fora daria a ele todas as ferramentas, porque tools omitido herda todas s2.
O worktree do meu builder não continha meu trabalho não commitado. Isso é um bug? Não. O worktree é criado por padrão a partir da sua branch padrão, não de onde você está s2. Faça commit ou merge do que o builder precisa primeiro.
O test writer perdeu no repositório de vocês. Vai perder no meu? Talvez não. Rodamos doze execuções por lado em um único repositório pequeno, e o único erro do subagent foi um comando de teste que nossas configurações não permitiam. Rode o harness no seu e leia qualquer execução que mude de resultado, como o artigo recomenda s1.
Posso fazer o reviewer esperar em vez de rodar em segundo plano? Subagents rodam em segundo plano por padrão desde a 2.1.198 s24. A documentação descreve como pedir ao Claude que espere o relatório e uma configuração que o faz esperar; confira a documentação de subagents para a sua versão s2.
AIDive