o problema
Um chatbot responde e espera. Um agente de código lê arquivos, roda comandos, edita e continua trabalhando enquanto você observa, redireciona ou sai da frente. A inversão é a promessa: em vez de escrever o código e pedir revisão, você descreve o resultado e o agente decide como chegar lá. Só que a autonomia não vem de graça, e a maior parte do que dá errado não é o modelo escrever código ruim.
Duas coisas quebram. A primeira: a janela de contexto guarda a conversa inteira — cada mensagem, cada arquivo lido, cada saída de comando. Uma sessão de debug ou uma exploração de codebase consome dezenas de milhares de tokens, e o desempenho degrada conforme o espaço enche; o modelo começa a esquecer instruções anteriores e a errar mais. A segunda: o agente para quando o trabalho parece pronto. Sem um sinal que ele mesmo possa ler, “parece pronto” é o único critério, e cada erro fica esperando você notar.
a ideia
O guia não é uma lista de dicas soltas. Quase tudo nele deriva dessas duas restrições, e dá para ler cada prática perguntando qual das duas ela ataca. Gastar menos contexto: /clear entre tarefas não relacionadas, subagents que pesquisam em outra janela e devolvem só o resumo, CLI tools como gh em vez de bater na API crua, skills carregadas sob demanda em vez de despejar tudo no CLAUDE.md. Fechar o loop: dar ao agente um comando que devolve pass ou fail e mandar iterar até passar.
A analogia honesta aqui é gerência, não programação. Você não revisa cada linha de quem trabalha com você: define o critério de pronto, garante acesso às ferramentas que produzem evidência e pede a evidência junto com o resultado. O guia é explícito nisso — peça a saída do teste, o comando rodado e o que ele retornou, ou o screenshot, em vez da afirmação de que funcionou. Ler evidência é mais rápido que refazer a verificação, e funciona para sessões que você nem assistiu.
como funciona
A verificação aparece em quatro níveis, do mais barato ao mais duro. No próprio prompt, pedindo que o agente rode o check e itere na mesma mensagem. Como condição de /goal, com um avaliador separado rechecando depois de cada turno. Como Stop hook, um script que bloqueia o fim do turno até passar — o Claude Code sobrepõe o hook e encerra depois de 8 bloqueios consecutivos. E como segunda opinião: um subagent de verificação, em contexto limpo, tentando refutar o resultado, para que quem fez o trabalho não seja quem dá a nota.
O fluxo recomendado tem quatro fases: explorar em plan mode (Shift+Tab ou claude --permission-mode plan), pedir o plano (Ctrl+G abre no editor para você mexer), implementar, commitar. Se dá para descrever o diff numa frase, pule o plano.
As superfícies de configuração se ordenam por dureza. CLAUDE.md é conselho lido em toda sessão, gerado por /init e podado por /doctor. Skill é conhecimento ou workflow em .claude/skills/, carregado quando é relevante, com disable-model-invocation: true para o que tem efeito colateral. Subagent é .claude/agents/, com contexto próprio, lista própria de tools e model declarado. Hook é determinístico e não negocia.
Para escalar, /batch divide a mudança entre 5 e 30 subagents, cada um no seu worktree abrindo um PR. Para dirigir isso do seu script:
for file in $(cat files.txt); do
claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
--allowedTools "Edit,Bash(git commit *)"
doneO --allowedTools é o que limita o estrago quando ninguém está olhando.
o que isso custou
O guia admite os limites. Plan mode tem overhead e atrapalha em mudança pequena. Checkpoints só rastreiam o que passou pelas ferramentas de edição de arquivo: o que o agente fez via Bash ou processo externo não volta — não é substituto de git. O Stop hook, que existe para ser inegociável, é sobreposto depois de 8 bloqueios. E o reviewer adversarial tem viés embutido: pedido para achar lacunas, ele acha, e seguir todas produz camada de abstração e teste para caso impossível; a saída sugerida é instruir o reviewer a reportar só o que afeta correção ou requisito declarado.
O custo maior é de calibração. A seção final desmonta a própria receita: às vezes deixar o contexto acumular é certo, às vezes pular o plano é certo, às vezes o prompt vago é exatamente o que você quer. Os cinco padrões de falha listados — a sessão pau para toda obra, a correção em looping, o CLAUDE.md inchado, o gap entre confiar e verificar, a exploração infinita — são o reconhecimento de que a ferramenta quebra de jeitos previsíveis e que a parte não automatizável continua sendo julgamento de quem opera.
onde isso aparece hoje
O efeito prático é que a configuração do agente deixou de ser prompt e virou arquivo versionado no repositório: CLAUDE.md commitado para o time contribuir, skills, hooks e subagents em .claude/, plugins que empacotam tudo isso num instalável, MCP para os serviços externos. O guia manda tratar CLAUDE.md como código — revisar quando algo dá errado, podar com regularidade, testar mudanças observando se o comportamento realmente mudou.
Do outro lado, claude -p em CI e pre-commit hooks, com saída em JSON ou stream-json para o script consumir, e sessões paralelas em worktrees, no desktop, na web ou em agent view. A parte mais coordenada disso — agent teams, com tarefas compartilhadas e um líder — o próprio documento marca como experimental e desligada por padrão.