Esta nota é uma aula sobre agents, subagents e orquestração. O objetivo é que, ao terminar, você consiga desenhar um agent do zero (o papel, as ferramentas, o prompt, os limites), decidir quando dividir um trabalho entre vários deles e conduzir uma feature inteira por um pipeline de agents sem perder o controle da qualidade.

Os exemplos usam o Claude Code porque ele tem subagents como recurso nativo, mas as ideias valem para qualquer sistema com modelos que chamam ferramentas. As figuras são animadas e foram geradas com o ArchFlow (veja MCP). Os detalhes do Claude Code vêm da documentação oficial de subagents e dos artigos de engenharia da Anthropic listados no fim, consultados em outubro de 2026. Esse recurso muda rápido, então confira a documentação antes de copiar um campo.

Mapa da aula

Pré-requisito: saber o que é um servidor MCP ajuda na parte 3, mas não é obrigatório. Se faltar contexto, leia MCP antes.

Parte 1: Fundamentos

1. O que é um agent

Um modelo de linguagem sozinho recebe texto e devolve texto. Um agent é um modelo que roda dentro de um loop e usa ferramentas para agir no mundo: lê arquivos, executa comandos, busca na web, edita código. A cada volta do loop ele decide o próximo passo olhando o resultado do passo anterior.

O ciclo tem cinco momentos:

1. Chega um objetivo, em linguagem natural.
2. O modelo decide o que fazer agora (chamar uma ferramenta ou responder).
3. A ferramenta executa no ambiente (um arquivo é lido, um teste roda).
4. O resultado volta para o modelo. Esse retorno é a verdade do mundo: um teste que falhou vale mais do que a opinião do modelo de que o código estava certo.
5. O ciclo repete até uma condição de parada: objetivo cumprido, limite de turnos ou uma dúvida que só o humano resolve.

A Anthropic usa uma distinção útil entre dois tipos de sistema agêntico:

Workflow dá previsibilidade. Agent dá flexibilidade quando você não sabe de antemão quantos passos o trabalho exige. A maioria dos sistemas bons mistura os dois: a estrutura geral é um workflow e cada etapa é um agent pequeno.

2. Anatomia de um agent

Todo agent, de qualquer tamanho, se descreve com cinco peças. Quando um agent se comporta mal, o defeito está quase sempre em uma delas.

Uma regra prática para pensar em cada peça: o agent é um colega novo e inteligente no primeiro dia. Ele sabe programar, mas não conhece o seu projeto, as suas convenções nem o que você já tentou. Tudo o que ele precisa saber tem de chegar por uma destas portas: o prompt de sistema, o brief da tarefa, os arquivos que ele lê ou a memória.

3. Quando usar (e quando não usar) um agent

Agents custam mais e erram de formas mais difíceis de prever. Os números da própria Anthropic ajudam a calibrar: no sistema de pesquisa multiagente deles, um agent usa cerca de 4 vezes os tokens de um chat comum, e um sistema com vários agents usa cerca de 15 vezes.

Siga esta escada e só suba um degrau quando o anterior não bastar:

1. Uma chamada ao modelo, com bons exemplos no prompt.
2. Uma chamada com busca ou ferramentas fixas (retrieval).
3. Um workflow com passos fixos.
4. Um agent único com ferramentas.
5. Vários agents (subagents e orquestração).

Sinais de que vale subir:

• Os passos não podem ser escritos antes (você só sabe o que fazer depois de ver o código).
• Existe um jeito objetivo de verificar o resultado (testes, tipos, linter). Código é um bom terreno justamente por isso.
• O trabalho gera muito ruído que você não quer na conversa principal (logs, buscas, leituras).

Sinais de que não vale:

• Uma única chamada já resolve.
• O trabalho exige que todas as partes compartilhem muito contexto o tempo todo. A Anthropic observa que a maior parte das tarefas de programação encaixa mal em multiagente por causa disso.
• Não existe critério para saber se o resultado está certo.

Parte 2: Subagents

4. O que é um subagent e por que existe

Um subagent é um agent que outro agent chama para fazer uma parte do trabalho. Ele roda com contexto próprio, prompt de sistema próprio, ferramentas próprias e, se você quiser, modelo próprio. Quando termina, devolve uma resposta curta, e o contexto dele é descartado.

Esse isolamento é a razão de existir do subagent, e resolve três problemas:

1. Poluição de contexto. Mapear um módulo exige ler dezenas de arquivos. Se isso acontecer na conversa principal, ela fica cheia de detalhes que você não vai mais usar, e o modelo rende menos. O subagent lê tudo e devolve só o mapa.
2. Custo e velocidade. Tarefas simples (buscar, listar, rodar teste) podem rodar num modelo menor e mais barato, enquanto a conversa principal fica com o modelo forte.
3. Paralelismo. Partes independentes do trabalho podem andar ao mesmo tempo.

O preço também existe. Cada subagent gasta os próprios tokens, conta no mesmo limite de uso da sua conta, e o resumo que volta pode perder um detalhe importante. Por isso o formato do relatório (seção 7) faz parte do projeto do agent.

5. O que o subagent sabe e o que ele não sabe

Este é o ponto que mais derruba orquestrações. Pela documentação do Claude Code, a conversa de um subagent começa com:

• o prompt de sistema dele (o corpo do arquivo do agent);
• a mensagem de delegação que a sessão principal escreveu (o brief);
• os arquivos CLAUDE.md do projeto (exceto nos agents Explore e Plan e nos que desligam isso);
• um retrato do estado do git (também exceto Explore e Plan);
• as skills que você listou no frontmatter.

Ele não recebe o histórico da sua conversa, os arquivos que a sessão principal já leu, nem o que você combinou nos turnos anteriores. A única ponte é o brief.

Consequência prática: tudo o que importa para a tarefa e foi decidido na conversa precisa estar escrito no brief, com palavras suficientes para alguém que chegou agora entender. A seção 11 mostra como escrever isso.

6. A estrutura de um agent no Claude Code

Um subagent é um arquivo Markdown com um bloco YAML no topo. O YAML configura, o corpo vira o prompt de sistema.

---
name: code-reviewer
description: Revisa mudanças de código procurando bugs e riscos. Use proactively depois de qualquer edição relevante.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Você é um revisor sênior. Rode `git diff` para ver o que mudou.
Para cada problema, informe arquivo e linha, explique o risco,
mostre o trecho e proponha a correção. Agrupe por gravidade.

A parte do frontmatter que fica carregada em toda sessão é só a description, porque é ela que o Claude lê para decidir se delega. O corpo só entra na conversa do subagent quando ele é chamado. Por isso a regra de ouro: a descrição diz quando usar, o corpo diz como trabalhar.

Onde o arquivo mora

Se dois agents têm o mesmo name, vence o de prioridade maior. Em geral: agents do time vão em .claude/agents/, agents pessoais em ~/.claude/agents/. Mudanças nessas pastas são detectadas em segundos, sem reiniciar (exceto ao criar a primeira pasta agents).

Os campos do frontmatter

Só name e description são obrigatórios. Campos desconhecidos são ignorados em silêncio, então um erro de digitação não dá aviso (rode claude --debug e procure does not recognize or apply).

Como o modelo é escolhido, em ordem: o parâmetro que o Claude passa na chamada, o campo model do arquivo, a variável CLAUDE_CODE_SUBAGENT_MODEL e, por último, o modelo da conversa principal.

Um arquivo com (quase) todos os campos, linha por linha

O exemplo da seção anterior é o mínimo útil. Este é o mesmo revisor com a configuração completa, no formato que as ferramentas costumam gerar (lista de ferramentas em YAML, uma por linha):

---
name: code-reviewer
description: >
  Reviews recently changed code for correctness, security, performance,
  maintainability, and missing tests. Use proactively after code changes.
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: inherit
permissionMode: plan
maxTurns: 20
skills:
  - api-conventions
  - testing-conventions
memory: project
background: true
isolation: worktree
---

You are a senior software engineer performing a focused code review.

O que cada linha faz e o que pensar antes de copiá-la:

Dois pontos para pensar sobre esse arquivo em particular. Primeiro, ele mistura configurações de naturezas diferentes: permissionMode: plan e isolation: worktree tratam do mesmo risco (alterar o código) por caminhos diferentes, e para um agent que só lê basta o primeiro. Segundo, tools com Bash permite rodar qualquer comando (inclusive um que escreva arquivos) mesmo que Edit e Write estejam de fora. Se o revisor só precisa do git diff, a trava mais forte é um hook (veja adiante), não a lista de ferramentas.

Um arquivo enxuto resolve a maioria dos casos. Acrescente um campo quando houver um motivo concreto para ele, e saiba dizer qual.

Cada campo em detalhe

A tabela anterior dá o resumo. Aqui cada campo do arquivo completo ganha uma explicação própria: o que é, como funciona por dentro, quais valores aceita e quando mexer.

name

É o identificador do agent. Serve para três coisas: o Claude citar o agent ao delegar, você chamar com @"code-reviewer (agent)" ou --agent code-reviewer, e o sistema decidir qual arquivo vence quando dois agents têm o mesmo nome (veja a tabela de locais).

Regras: no máximo 256 caracteres, sem : e sem começar com -. O nome do arquivo não precisa ser igual ao name, mas manter os dois iguais evita confusão. Sem name, o arquivo é tratado como documentação e ignorado em silêncio, o mesmo vale para um arquivo cuja primeira linha não é ---.

Dê nomes que descrevem o papel (test-runner, db-reader), porque o nome também ajuda o Claude a escolher.

description

É o campo mais importante, porque é a única coisa do agent que o Claude lê antes de decidir delegar. Ele funciona como a regra de um roteador: “quando o pedido parecer com isto, chame este agent”.

Uma boa descrição responde duas perguntas: o que o agent faz e quando usá-lo. A frase Use proactively after code changes faz o Claude chamá-lo sozinho, sem você pedir.

Sobre a sintaxe description: > do exemplo: no YAML, o > abre um bloco “dobrado”. As linhas recuadas abaixo viram uma única linha de texto, com as quebras de linha trocadas por espaço. Serve só para a descrição não ficar com 200 caracteres numa linha só. O resultado é igual a escrever tudo seguido. Se você quiser manter as quebras, o símbolo é |.

Atenção ao tamanho: as descrições de todos os agents ficam carregadas em toda sessão. Quando a soma passa de 15 mil tokens, o Claude Code avisa na partida. Mantenha cada uma em uma ou duas frases e deixe os detalhes no corpo.

tools

É a lista de ferramentas que o agent pode usar. Funciona como uma lista de permissão: o que não está nela, o agent não consegue chamar.

As duas formas são equivalentes:

tools: Read, Grep, Glob, Bash

tools:
  - Read
  - Grep
  - Glob
  - Bash

O que cada ferramenta da lista faz:

Se o campo é omitido, o agent herda todas as ferramentas da sessão, incluindo as de servidores MCP. Se nenhuma entrada da lista corresponde a uma ferramenta que existe, o Claude Code devolve erro em vez de iniciar um agent sem poder nenhum. Servidores MCP são referenciados como mcp__nome-do-servidor, o que libera todas as ferramentas daquele servidor de uma vez.

O campo irmão disallowedTools faz o inverso: é uma lista de proibição, aplicada antes de tools. Use quando é mais curto dizer o que cortar (disallowedTools: Write, Edit) do que listar o que manter.

model

Escolhe qual modelo o agent usa. Valores aceitos: haiku, sonnet, opus, fable, um ID completo de modelo ou inherit.

inherit significa “use o mesmo modelo da conversa principal”, e é o padrão quando o campo some e nenhuma variável de ambiente interfere. A ordem completa de decisão é: o parâmetro que o Claude passa ao chamar, o campo do arquivo, a variável CLAUDE_CODE_SUBAGENT_MODEL e, por fim, o modelo da sessão.

Como decidir:

Com inherit, se você abrir a sessão com um modelo caro, todos os agents herdam o custo. Para um revisor que roda muitas vezes, fixar sonnet costuma economizar.

permissionMode

Define quanto o agent pode fazer sem pedir permissão. Os valores são os mesmos modos de permissão do Claude Code:

No exemplo, permissionMode: plan diz que o revisor só lê e propõe. Duas regras que surpreendem:

• Se a sessão principal já está em bypassPermissions, acceptEdits ou auto, o agent herda esse modo e o campo é ignorado. O campo só vale quando a sessão está em default, dontAsk ou plan.
• Regras de negação (permissions.deny) valem em qualquer modo, inclusive bypassPermissions. É a forma de garantir que algo nunca aconteça.

maxTurns

É o número máximo de voltas do loop do agent (cada volta é uma decisão do modelo, com ou sem chamada de ferramenta). Ao chegar no limite, o agent para e devolve o que tinha até ali como resultado parcial, e você pode retomá-lo depois.

É a proteção contra o loop que gira sem fim e queima dinheiro. Como escolher o valor: rode o agent algumas vezes, observe quantas voltas o trabalho normal exige e deixe uma folga acima disso. Os números do arquivo de exemplo (15, 20, 40) são pontos de partida, não regra. No exemplo, 20 pode cortar a revisão de uma mudança muito grande, e nesse caso o parcial volta e você retoma.

skills

Lista de skills que são carregadas por inteiro no contexto do agent assim que ele começa. Uma skill é um pacote de instruções reutilizável (por exemplo, as convenções da sua API, em Markdown). No exemplo, o revisor já nasce sabendo api-conventions e testing-conventions, então ele aponta violações dessas regras sem precisar procurá-las.

Três detalhes:

• É carregamento completo: o texto inteiro de cada skill entra no contexto, com seu custo em tokens. Liste só as que o agent usa sempre. São aceitas até 32.
• O campo não restringe: o agent continua podendo chamar outras skills por conta própria. Ele apenas pré-carrega estas.
• Os subagents não herdam as skills da conversa principal. Se uma skill importa para o trabalho, ela precisa estar nesta lista (ou o brief deve dizer onde achá-la).

memory

Dá ao agent uma memória que sobrevive entre execuções. O valor escolhe onde ela mora:

Com a memória ligada, as primeiras 200 linhas (ou 25 KB) do arquivo MEMORY.md da pasta entram no prompt do agent, e ele recebe Read, Write e Edit para manter essa pasta. O revisor do exemplo pode, assim, registrar “neste projeto, os testes de integração ficam em tests/e2e” e lembrar na próxima revisão.

O custo escondido: dar escrita ao agent, mesmo restrita à pasta de memória, quebra a ideia de “revisor só de leitura”. Decida se o ganho compensa. project é o valor recomendado para começar, porque deixa a memória visível e versionável.

background

Com background: true, o agent roda sempre em segundo plano, sem bloquear a conversa principal. O resultado chega depois, como uma notificação.

Diferenças em relação ao modo normal (foreground):

Bom para tarefas longas e independentes, como uma revisão enquanto você continua trabalhando. Ruim quando você precisa do resultado para o próximo passo, caso em que esperar em foreground é mais simples. Você também pode mandar um agent que já está rodando para segundo plano com Ctrl+B.

isolation

O único valor existente é worktree. Com ele, o agent trabalha numa cópia temporária do repositório (um git worktree, criada a partir do seu branch principal), e não na sua pasta. Se ele terminar sem alterar nada, a cópia é apagada sozinha. Se alterar, o resultado fica numa cópia separada para você inspecionar e juntar.

Para que serve: deixar agents que editam rodarem ao mesmo tempo sem se atropelarem, e permitir experimentos arriscados (um refactor grande) sem tocar no que você tem aberto. Para um agent que só lê, como o revisor do exemplo, a cópia não traz benefício e tem custo de criação, então isolation: worktree ali é sobra.

O corpo do arquivo

Tudo depois do segundo --- é o prompt de sistema. No exemplo é uma frase só (You are a senior software engineer performing a focused code review.), e a seção 7 mostra como crescer isso para um prompt completo, com método, formato de saída e limites. O agent recebe esse texto mais o ambiente básico (como a pasta de trabalho), e não o prompt de sistema inteiro do Claude Code.

Campos que não estão no exemplo

Ferramentas: o princípio do menor privilégio

Se você omite tools, o agent herda tudo o que a sessão tem. Isso quase nunca é o que se quer. Um revisor com Edit e Write pode “corrigir” o que deveria apenas apontar, e quando o autor do código e o revisor são a mesma pessoa em dois chapéus, a revisão perde o sentido. Dê a cada agent só o que o papel exige:

Um detalhe que pega muita gente: disallowedTools: Bash(git push *) remove o Bash inteiro, porque a restrição por comando não funciona nesse campo. Para bloquear só comandos específicos, use uma regra permissions.deny nas configurações, ou um hook.

Hooks: a trava que não depende do prompt

Escrever “nunca faça DELETE” no prompt é um pedido, e o modelo pode errar. Um hook é uma verificação feita por código. Exemplo do agent que só consulta o banco:

---
name: db-reader
description: Executa consultas somente leitura no banco para responder perguntas sobre os dados.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Bloqueado: só consultas SELECT" >&2
  exit 2
fi
exit 0

O script recebe o JSON da chamada pela entrada padrão. Sair com código 2 bloqueia a ferramenta e devolve a mensagem para o agent. Prompt orienta, hook garante.

Memória persistente

Com memory: project, o agent ganha uma pasta própria (.claude/agent-memory/<nome>/) e as primeiras 200 linhas do MEMORY.md entram no prompt dele. Ele pode registrar o que aprendeu (padrões do projeto, armadilhas recorrentes) e usar na próxima execução. É útil para revisores e depuradores, que se beneficiam de lembrar o que já viram.

Isolamento com worktree

isolation: worktree roda o agent numa cópia temporária do repositório (um git worktree). Se ele não alterar nada, a cópia some sozinha. É o recurso que torna seguro ter dois implementadores editando ao mesmo tempo: cada um trabalha na sua cópia, e você junta os resultados depois.

7. Como escrever um bom agent

Um bom agent é pequeno, tem um papel só e diz exatamente o que devolver. Use este molde para o corpo do prompt:

1. Papel. Uma frase: quem ele é e qual a missão.
2. Quando atua. O que dispara o trabalho e o que ele não faz.
3. Método. Os passos, em ordem, na forma de uma receita curta.
4. Formato da resposta. O que volta, em que estrutura e com que tamanho máximo.
5. Limites. O que ele nunca faz e quando deve parar e perguntar.

Vamos construir um agent passo a passo e ver o que cada parte resolve.

Versão fraca

---
name: helper
description: Ajuda com código
---

Você é um assistente útil que ajuda com tarefas de programação.

Os problemas: a descrição não diz quando delegar (o Claude nunca vai escolher esse agent), o nome não diz nada, não há ferramentas definidas (herda tudo), não há método e não há formato de saída. É o que a Anthropic chama de delegação vaga, e o resultado é trabalho duplicado ou fora de foco.

Versão boa

---
name: test-runner
description: Roda a suíte de testes e reporta só as falhas, com mensagem e trecho do código. Use proactively depois de qualquer mudança em código e antes de declarar uma tarefa pronta.
tools: Bash, Read, Grep
model: haiku
maxTurns: 15
---

Você roda testes e reporta falhas. Não edita código.

Método:
1. Descubra o comando de teste (package.json, Makefile ou README). Se houver mais de um, rode o mais amplo.
2. Execute. Se o comando não existir, pare e diga qual arquivo você procurou.
3. Para cada teste que falhou, leia o trecho do código sob teste.

Formato da resposta (no máximo 40 linhas):
- Resultado: `N passaram, M falharam`.
- Para cada falha: nome do teste, mensagem de erro em uma linha, arquivo e linha do código suspeito, e sua hipótese da causa em uma frase.
- Se tudo passou, responda apenas `Tudo passou (N testes)`.

Nunca cole a saída dos testes que passaram. Nunca corrija o código. Se os testes não rodarem por erro de ambiente, reporte o erro e pare.

O que cada escolha faz:

• A descrição tem o gatilho (“depois de qualquer mudança”) e a palavra proactively, que encoraja o Claude a delegar sem você pedir.
• tools sem Edit e Write impede que ele conserte em vez de reportar.
• model: haiku é suficiente para rodar um comando e resumir a saída, e custa menos.
• maxTurns: 15 põe um teto: se ele não conseguir em 15 voltas, devolve o parcial.
• O formato com limite de linhas protege a conversa principal de receber uma parede de log.

A descrição é o roteador

O Claude escolhe subagents lendo só as descrições. Escreva como se fosse a regra de um roteador:

Mantenha as descrições curtas: todas elas são carregadas em toda sessão, e quando a soma passa de 15 mil tokens o Claude Code avisa na partida.

Quatro modelos de agent para copiar

Explorador (só lê, barato, devolve um mapa):

---
name: explorer
description: Mapeia uma parte do código: onde algo vive, quem chama quem, quais convenções existem. Use proactively antes de planejar ou implementar uma mudança em área desconhecida.
tools: Read, Grep, Glob
model: haiku
---

Você mapeia código. Não edita nada.

Dado um objetivo, encontre os arquivos relevantes e devolva:
- Arquivos centrais (caminho e uma linha sobre o papel de cada um), no máximo 12.
- Fluxo principal: quem chama quem, em poucas linhas.
- Convenções que uma mudança nova precisa seguir (nomes, estrutura de testes, estilo).
- Armadilhas: acoplamentos ou efeitos colaterais que não são óbvios.

Cite sempre caminho e número de linha. Se não achar algo, diga o que procurou. Não resuma o que não leu.

Arquiteto (planeja e fixa contratos antes de qualquer código):

---
name: architect
description: Transforma um objetivo e um mapa do código num plano de implementação com contratos (tipos e assinaturas) e fatias independentes. Use antes de implementar qualquer feature com mais de um arquivo.
tools: Read, Grep, Glob
model: opus
---

Você projeta mudanças. Não edita código.

Entregue um plano com:
1. Contratos: tipos, assinaturas de funções e formatos de dados que as fatias compartilham, escritos em código.
2. Fatias: grupos de arquivos que podem ser implementados sem tocar nos arquivos de outra fatia. Para cada fatia, a lista exata de arquivos.
3. Ordem e dependências entre as fatias.
4. Critério de pronto de cada fatia, verificável por teste ou comando.
5. Riscos e o que ficou fora do escopo.

Se duas fatias precisarem editar o mesmo arquivo, reorganize até que isso não aconteça, ou marque como sequenciais.

Implementador (edita, dentro de uma fatia, com teto de turnos):

---
name: implementer
description: Implementa uma fatia de código definida por um plano, editando só os arquivos listados. Use quando o plano e os contratos já estiverem fixados.
tools: Read, Edit, Write, Bash, Grep, Glob
isolation: worktree
maxTurns: 40
---

Você implementa exatamente a fatia que recebeu.

Regras:
- Edite só os arquivos listados no brief. Se precisar de outro, pare e informe.
- Siga os contratos à risca (nomes, tipos, assinaturas). Se um contrato parecer errado, não o altere: informe.
- Rode o critério de pronto da fatia antes de terminar.

Resposta: arquivos alterados, resultado do critério de pronto, e qualquer desvio do plano com o motivo. Máximo 25 linhas.

Revisor independente (só lê, contexto limpo):

---
name: reviewer
description: Revisa o diff atual procurando bugs, casos de borda, falhas de segurança e desvios do plano. Use proactively depois que as fatias forem implementadas e antes de dar a feature por pronta.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Você revisa. Não edita nada.

1. Rode `git diff` e leia o plano que veio no brief.
2. Procure, nesta ordem: bugs de lógica, casos de borda sem tratamento, riscos de segurança, desvios do plano, convenções quebradas.
3. Para cada achado: arquivo e linha, o que acontece de errado (com um exemplo concreto de entrada), e a correção sugerida.

Classifique cada achado como bloqueante ou sugestão. Não aponte estilo que o linter já cobre. Se não achar nada, diga o que verificou.

Repare em um padrão: quem escreve o código não é quem revisa. Um revisor com contexto limpo não herda as suposições do autor, e é por isso que acha o que o autor não vê.

Agents que são o assistente principal

Além de ser chamado, um agent pode ser a sessão inteira: claude --agent code-reviewer (ou "agent": "code-reviewer" nas configurações). Aí o prompt de sistema da sessão é substituído pelo do agent. É o jeito de ter perfis de trabalho, como um modo de revisão ou um modo de documentação. Para limitar quais subagents essa sessão pode criar, use tools: Agent(worker, researcher), Read, Bash.

8. Os subagents que já vêm prontos

Antes de criar um agent, veja se um desses já resolve. Para trocar o comportamento de um deles, defina um agent com o mesmo nome no seu projeto: a prioridade de local faz o seu vencer (um Explore com model: haiku, por exemplo, deixa as buscas mais baratas).

9. Como um subagent roda

Foreground e background

Em foreground, o subagent bloqueia a conversa principal e os pedidos de permissão aparecem para você. Em background, ele roda ao mesmo tempo, os pedidos de permissão aparecem na sessão principal com o nome do agent, e o resultado chega como notificação num turno posterior. Com Ctrl+B você manda para segundo plano algo que já está rodando. O campo background: true força esse modo.

Como o Claude decide chamar um agent

Existem quatro caminhos:

1. Automático: o Claude lê as descrições e escolhe.
2. Por linguagem natural: “use o test-runner para corrigir os testes que falham”.
3. Por menção: @"code-reviewer (agent)" olhe as mudanças de autenticação garante aquele agent. Sua mensagem inteira ainda vai para o Claude, que escreve o brief.
4. Como sessão inteira, com --agent.

Continuar o trabalho de um agent

Cada chamada cria uma instância nova. Para retomar uma que terminou, o Claude usa SendMessage com o ID ou o nome do agent, e ele volta com o histórico completo. Explore e Plan são de uma tacada só e não retomam. As transcrições ficam em ~/.claude/projects/<projeto>/<sessão>/subagents/ e são apagadas depois de 30 dias por padrão.

Limites

• Subagents podem criar outros subagents, até 3 camadas abaixo da conversa principal (configurável em CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH).
• Até 20 subagents rodando ao mesmo tempo por padrão.
• Subagents herdam as ferramentas da sessão menos uma lista fixa (por exemplo AskUserQuestion), então um subagent não pode abrir uma pergunta para você. Se ele precisa de uma decisão, deve devolver a pergunta no relatório.

Parte 3: Orquestração

10. Os cinco padrões

Orquestrar é decidir como as partes se conectam. A Anthropic descreve cinco padrões que cobrem quase tudo. Cada um resolve um formato de problema.

Encadeamento (prompt chaining)

Uma tarefa dividida em etapas sequenciais, cada uma lendo a saída da anterior, com um gate (uma verificação) entre elas. Serve quando os passos são conhecidos e fixos. Troca velocidade por precisão. Exemplo: gerar um esboço, verificar se cumpre o critério, só então desenvolver.

Roteamento

Um classificador olha a entrada e a manda para o especialista certo. Serve quando há categorias distintas que se tratam melhor separadas e a classificação é confiável. Exemplo: separar pedidos em bug, feature e pergunta, cada um com seu agent. Também serve para custo: perguntas fáceis vão para um modelo pequeno.

Paralelização

Partes independentes rodam ao mesmo tempo e um passo final junta. Há duas formas: fatiar (cada worker faz uma parte diferente) e votar (vários fazem a mesma tarefa e você compara). Exemplo de votação: três revisores independentes olham o mesmo diff, e vale o achado que mais de um repetiu.

Orquestrador e workers

Um agent central decide as subtarefas olhando a entrada, delega para workers e junta os resultados. A diferença para a paralelização é que as subtarefas não existem antes: o orquestrador as inventa conforme o pedido. É o padrão de quase toda implementação de feature em vários arquivos, e é o foco das próximas seções.

Avaliador e otimizador

Um agent produz, outro critica, e o ciclo se repete até passar. Funciona quando existe critério claro e o feedback melhora de fato o resultado. Exemplo: o implementador escreve, o test-runner e o reviewer avaliam, e o implementador corrige até os dois aprovarem. Ponha sempre um teto de rodadas, senão o ciclo pode não terminar.

Qual escolher

Os padrões se combinam. Uma feature costuma ser um orquestrador (padrão 4) que conduz um encadeamento com gates (padrão 1), paraleliza as fatias independentes (padrão 3) e fecha com um loop de avaliação (padrão 5).

11. O brief: a mensagem que decide tudo

Como o subagent só conhece o que está no brief (seção 5), o brief é o artefato mais importante da orquestração. Na pesquisa multiagente da Anthropic, delegações vagas fizeram subagents duplicarem trabalho: um pesquisava a crise de chips de 2021 enquanto outros dois pesquisavam a mesma cadeia de suprimentos de 2025.

Um brief completo tem sete partes:

Brief fraco:

Implemente o filtro por tag.

Brief forte:

Objetivo: a lista de tarefas deve poder ser filtrada por uma ou mais tags.

Contexto: o estado vive em src/store/tasks.ts (Zustand). Já decidimos que o filtro
fica no store e a UI só lê o resultado. Não use useEffect para filtrar.

Escopo: edite só src/store/tasks.ts e src/store/tasks.test.ts.
Fora de escopo: componentes em src/components, que outro agent está fazendo.

Contrato (já fixado, não altere):
  type TagFilter = { tags: string[]; mode: 'any' | 'all' }
  setTagFilter(filter: TagFilter): void
  selectVisibleTasks(state): Task[]

Critério de pronto: `pnpm test src/store` passa, incluindo testes novos para
mode 'any', mode 'all' e lista de tags vazia (que deve devolver todas as tarefas).

Relatório (no máximo 20 linhas): arquivos alterados, saída do critério de pronto,
desvios do contrato (se houver, com motivo).

Regras para um brief que funciona:

• Escreva como se o agent nunca tivesse visto o projeto, porque é verdade.
• Inclua o motivo das decisões. Um agent que sabe o porquê toma melhores decisões nos casos que você não previu.
• Diga o tamanho da resposta. Sem limite, o relatório volta enorme e polui o contexto principal, anulando a vantagem do isolamento.
• Restate as regras do projeto de que ele precisa. O CLAUDE.md chega ao subagent, mas regras ditas na conversa não.
• Pedir ao agent que diga o que não conseguiu fazer é tão importante quanto pedir o que fez.

12. O orquestrador

O orquestrador é a sessão principal (ou um agent com o papel de lead). O trabalho dele é decidir, delegar e verificar. Ele não deve fazer o trabalho braçal, porque isso gasta o contexto que ele precisa para conduzir o todo.

O que ele faz, em ordem:

1. Entende o pedido e decide o tamanho do esforço. A Anthropic usa uma escala parecida com esta: busca simples, um agent com poucas chamadas; comparação direta, 2 a 4 subagents; trabalho amplo, mais de 10 com responsabilidades divididas. Em código, a escala costuma ser menor: de 1 a 3 agents por etapa.
2. Escreve um brief para cada worker (seção 11).
3. Dispara os workers independentes juntos, na mesma mensagem, para rodarem em paralelo.
4. Lê os relatórios e verifica o que importa. Um relatório diz o que o agent acredita ter feito. Antes de aceitar, confira o diff ou rode o teste você mesmo.
5. Decide o próximo passo: avançar, repetir uma fatia com feedback ou mudar o plano.
6. Responde a você com o estado real, incluindo o que não foi verificado.

Você instrui o orquestrador no CLAUDE.md do projeto. Um trecho que costuma funcionar:

## Como delegar

- Para qualquer mudança em mais de um arquivo: explorer, depois architect, depois implementers.
- Dispare em paralelo só fatias que não tocam os mesmos arquivos.
- Todo brief inclui objetivo, contexto, escopo, contratos, critério de pronto e limite de tamanho do relatório.
- Quem implementa não revisa. Depois de implementar, rode test-runner e reviewer.
- Nunca declare a feature pronta sem ter rodado a suíte e lido o diff.

13. Orquestrando uma feature de ponta a ponta

Exemplo: em um app React com Zustand, adicionar filtro por tag na lista de tarefas. O pipeline:

Etapa 1: explorar

O orquestrador chama o explorer com o objetivo. O explorador lê o store, os componentes da lista e os testes, e devolve o mapa: onde o estado vive, quem renderiza a lista, qual o padrão de teste, que armadilhas existem (por exemplo, um seletor que outra tela também usa). Só o mapa volta, e as 30 leituras ficam no contexto descartável dele.

Etapa 2: planejar com contratos

O architect recebe o objetivo e o mapa. A saída que importa são os contratos (tipos e assinaturas) e as fatias:

• Fatia A: src/store/tasks.ts e src/store/tasks.test.ts (estado e seletor).
• Fatia B: src/components/TaskList.tsx, src/components/TagFilterBar.tsx e testes (interface).

As fatias só são paralelizáveis porque os contratos foram escritos antes: a fatia B pode usar setTagFilter e selectVisibleTasks sem esperar a A existir. Esta é a regra central da orquestração: fixe as interfaces primeiro e a paralelização vira segura.

Etapa 3: implementar em paralelo

O orquestrador dispara dois implementer na mesma mensagem, cada um com isolation: worktree e um brief como o da seção 11. Cada um altera só a sua fatia, na sua cópia do repositório, e roda o critério de pronto próprio.

Ao receber os dois relatórios, o orquestrador junta as mudanças (o conflito é raro, porque os arquivos são disjuntos) e confere se os contratos foram respeitados lendo as assinaturas no código.

Etapa 4: testar

O test-runner roda a suíte inteira. Só as falhas voltam, com hipótese de causa. Se algo falha, o orquestrador devolve o erro ao implementador da fatia responsável, com o relatório do test-runner dentro do brief, e repete a etapa. Defina um teto (por exemplo, 3 rodadas) e, se estourar, pare e traga o problema para você.

Etapa 5: revisar com contexto limpo

O reviewer lê o diff e o plano e aponta riscos: bugs, casos de borda (lista de tags vazia, tag removida enquanto o filtro está ativo), segurança, desvios do plano. Achados bloqueantes voltam ao implementador. Sugestões você decide.

Etapa 6: você decide

O orquestrador entrega um resumo: o que mudou, o que foi testado, o que o revisor apontou, o que ficou sem verificação. A decisão de aceitar é sua.

O que fica em paralelo e o que fica em fila

A maior parte desse pipeline é sequencial, e isso é intencional. Só a implementação das fatias roda em paralelo, e só porque os contratos desacoplaram as partes. A pesquisa da Anthropic sobre multiagente avisa que programação tem muitas dependências entre as partes e que paralelizar demais é um erro comum. Antes de paralelizar, pergunte: o worker B precisa de algo que o A ainda vai produzir? Se sim, fixe o contrato ou deixe em fila.

14. Regras de paralelismo

15. Verificação: confie no ambiente, não no relatório

Um agent fala em primeira pessoa e com confiança, mesmo quando errou. “Implementei e os testes passam” é uma afirmação, e só vira fato depois que alguém roda o teste. Por isso o desenho do pipeline coloca verificação fora do agent que fez o trabalho:

• O critério de pronto de cada fatia é um comando, não uma opinião.
• O test-runner roda a suíte inteira depois de juntar as fatias, porque cada fatia passar sozinha não garante que o conjunto passa.
• O reviewer é um agent separado, com contexto limpo.
• O orquestrador lê o diff antes de afirmar qualquer coisa a você.

O princípio vem do loop da seção 1: o agent só sabe se avançou quando o ambiente responde (teste, tipo, linter, execução). Quanto mais objetivo o sinal, mais confiável o pipeline.

Parte 4: Prática

16. Erros comuns e como evitar

17. Avaliar e melhorar seus agents

Um agent é código com um prompt no meio, e prompt sem teste regride em silêncio. A Anthropic descreve um método simples que funciona em escala pequena:

1. Monte cerca de 20 casos reais de uso. No começo, mudanças no prompt têm efeito grande e poucos casos já mostram a diferença.
2. Para cada caso, defina o que seria um bom resultado. Avalie o resultado final e se o caminho foi razoável, porque o mesmo objetivo pode ser alcançado por rotas diferentes.
3. Use um modelo como juiz com uma rubrica curta (correção, completude, formato, eficiência), e confirme com leitura humana. Pessoas pegam falhas que a automação deixa passar.
4. Ao mudar o prompt, rode os mesmos casos e compare.
5. Leia as transcrições. Os subagents ficam em ~/.claude/projects/.../subagents/, e ver passo a passo onde o agent errou ensina mais do que qualquer teoria.

Dois hábitos que pagam bem: simular o agent à mão (rode o prompt e as ferramentas passo a passo e veja onde você mesmo ficaria perdido) e tratar as descrições das ferramentas como interface. A Anthropic relata que um agent que reescreveu descrições ruins de ferramentas reduziu o tempo de tarefa em 40%.

18. Checklist de um agent bem projetado

• Uma responsabilidade só, resumível em uma frase.
• Descrição com gatilho claro (quando usar) e, se for o caso, use proactively.
• tools como lista de permissão, com o mínimo necessário.
• Modelo adequado à dificuldade (haiku para ler e rodar, sonnet para o meio-termo, opus para planejar).
• Corpo com papel, método, formato da resposta e limites.
• Formato de saída com tamanho máximo.
• maxTurns definido para agents que editam ou pesquisam livremente.
• Regras críticas garantidas por hook, não só por prompt.
• Escritores paralelos com isolation: worktree.
• Testado com uns 20 casos reais.

Checklist de uma orquestração:

• Contratos (tipos e assinaturas) definidos antes de dividir.
• Fatias com arquivos disjuntos.
• Brief com objetivo, contexto, escopo, contratos, critério de pronto e formato de relatório.
• Critério de pronto executável por comando.
• Quem escreve não revisa.
• Teto de rodadas de correção.
• O orquestrador verifica antes de afirmar que terminou.
• Você revisa o resultado final.

19. Exercícios

1. Crie um agent explorer (seção 7) em ~/.claude/agents/ e peça para ele mapear um projeto que você conhece. Compare o relatório com o que você sabe. O que ele errou? Que linha do prompt corrigiria isso?
2. Escreva um brief para a fatia B do exemplo (a interface), usando as sete partes da seção 11. Dê para outra pessoa ler e veja se ela entende a tarefa sem perguntar nada.
3. Crie um agent db-reader com o hook da seção 6 e tente fazê-lo rodar um DELETE. Confira se o hook bloqueia.
4. Implemente uma feature pequena do seu projeto com o pipeline completo. Anote: quanto custou, onde a conversa principal ficou mais limpa, onde um subagent errou por falta de contexto.
5. Rode o mesmo pedido com um agent único e com o pipeline. Qual resultou em código melhor? E mais barato? Em que tamanho de tarefa a balança vira?

20. Glossário

Parte 5: Vocabulário de agentes

As quatro seções a seguir reúnem os nomes que a documentação e a prática de agentes usam para as mesmas peças. Os nomes “gerente”, “supervisor” e “memória entre passos” são usados aqui por convenção, sem fonte oficial; onde o texto cita documentação, ele traz a fonte.

21. Workflow ou laço autônomo, e quando parar

A seção 1 já separou workflow (o seu código decide o caminho) de agent (o modelo decide a cada passo). Aqui o foco é a decisão de arquitetura que isso implica, porque ela é a pergunta mais frequente de projeto: este problema pede um fluxo fixo ou um laço autônomo?

Um fluxo fixo basta quando você consegue escrever os passos antes de ver a entrada. Extrair campos de uma nota fiscal, resumir e depois traduzir, classificar um ticket e despachá-lo para uma fila: em todos esses, a ordem das etapas não depende do que o modelo descobre pelo caminho. Nesse caso o fluxo fixo ganha em tudo que importa em produção. Ele é previsível (a mesma entrada percorre o mesmo caminho), custa pouco (o número de chamadas ao modelo é conhecido), é fácil de testar (cada etapa tem entrada e saída definidas) e falha de um jeito localizável (você sabe em qual passo quebrou). O laço autônomo só se paga quando o número e a ordem dos passos dependem do que o modelo encontra: corrigir um bug num repositório desconhecido, pesquisar um tema aberto, investigar um incidente. A escada da seção 3 diz o mesmo de outro jeito, e vale repeti-la como regra de bolso: comece pelo degrau mais baixo que resolve.

Por dentro, o laço autônomo é o ciclo da seção 1 com uma peça que o código controla: o que fazer a cada resposta do modelo. Na API da Anthropic, cada resposta traz um stop_reason. Se ele é tool_use, o modelo pediu uma ferramenta, o seu código a executa e devolve o resultado numa nova chamada. Se é end_turn, o modelo considera que terminou. O laço mais simples possível é “enquanto o motivo de parada for tool_use, execute e repita”. Esse laço tem uma única condição de saída, e ela depende inteiramente do modelo. Ele para quando o modelo quer parar. Se o modelo entrar num ciclo (ler o mesmo arquivo, rodar o mesmo teste, tentar a mesma correção), nada o interrompe, e a conta cresce a cada volta.

Por isso um laço bem projetado tem quatro condições de parada, e cada uma cobre um tipo de falha diferente:

A resposta final é a única parada “feliz”. As outras três são freios, e cada uma existe porque a anterior não basta. O limite de passos não protege você de um passo muito caro (uma única ferramenta que lê um arquivo de 2 GB), e é o orçamento que cobre isso. O orçamento não protege você de uma ação errada e barata (um rm -rf custa quase nada), e é a confirmação que cobre isso. Quando o laço bate num freio, ele deve devolver o estado parcial e dizer qual freio atuou, como o maxTurns do Claude Code faz ao devolver o resultado parcial, e não simplesmente falhar em silêncio.

A ação de confirmação merece um parágrafo à parte, porque é a única das quatro que envolve uma pessoa. O critério para exigi-la é a reversibilidade, não a gravidade do pedido: ler qualquer coisa é reversível, editar um arquivo versionado é reversível, mas enviar uma mensagem, apagar um banco ou cobrar um cartão não são. No Claude Code, o modo de permissão default (seção 6) já faz isso para escritas, e para regras absolutas existem as regras deny e os hooks da seção 24.

Resta o porquê de definir a parada antes de escrever o laço. Os freios mudam o desenho do resto: o limite de passos decide quanto estado o laço precisa guardar para retomar, o orçamento exige que as ferramentas informem seu custo, e a confirmação exige um ponto onde o laço pode pausar e esperar uma resposta externa. Se você escreve o laço primeiro e acrescenta os freios depois, descobre que o laço não tem onde pendurá-los (ele roda dentro de uma função só, sem estado, sem ponto de pausa). Escrever a parada primeiro também força a pergunta que costuma ser pulada: o que significa “terminou”? Se a resposta é “quando o modelo achar”, o seu critério de pronto é uma opinião, e a seção 15 já mostrou o que acontece com opiniões não verificadas.

22. Gerente, supervisor, paralelização e memória

A seção 10 apresentou cinco padrões e a 12 detalhou um deles, o orquestrador com workers. Os mesmos desenhos aparecem na literatura de agentes e nas provas com outros nomes. Vale saber as duas versões, porque, na prática, a mesma estrutura aparece com nomes diferentes.

Hierarquia de gerente (manager) é o desenho em que um agent central recebe o objetivo, decompõe, delega a especialistas e junta as respostas. É o orquestrador e workers da seção 10, e o Claude Code é um exemplo direto: a sessão principal é o gerente e os subagents são os subordinados. O gerente enxerga o quadro inteiro e os subordinados enxergam só o próprio brief (seção 5), e é essa assimetria que mantém o contexto de cada um pequeno.

O supervisor é uma variação em que o agent central age mais como fiscal do que como planejador: os workers já têm um papel fixo, e o supervisor decide quem fala a seguir, avalia a saída e decide se o trabalho segue, volta ou termina. Na prática a fronteira entre os dois é tênue, e não há uma distinção oficial que eu tenha encontrado. A forma mais segura de lembrar é pela pergunta que cada um responde: o gerente responde “que subtarefas existem?” e o supervisor responde “isto está bom o suficiente para seguir?”. O avaliador e otimizador da seção 10 é o supervisor em ação, com o teto de rodadas como freio.

Hierarquias profundas ficam caras e opacas. O Claude Code limita a 3 camadas de subagents abaixo da conversa principal (seção 9), e a regra geral é manter o menor número de níveis que resolve, porque cada nível adiciona um brief que pode perder informação e um relatório que pode distorcê-la.

Paralelização, no vocabulário usado aqui, cobre os dois formatos da seção 10: fatiar (partes diferentes ao mesmo tempo) e votar (a mesma tarefa várias vezes, comparando). A condição para paralelizar é a independência: nenhum worker pode depender do resultado de outro, e nenhum pode escrever onde outro escreve. Os contratos da seção 13 e as regras da seção 14 existem para criar essa independência. A recompensa é tempo (o trabalho dura o que dura a fatia mais lenta, e não a soma das fatias), e o preço é custo, porque cada worker gasta os próprios tokens.

Memória entre passos é a pergunta de quando o agent precisa lembrar do que aconteceu antes. A resposta depende de qual “antes” se fala:

Num fluxo fixo de etapas independentes, quase nenhuma memória é necessária, porque cada etapa recebe só a saída da anterior. Num laço autônomo longo, o histórico cresce até estourar a janela de contexto, e aí surge a decisão de resumir, descartar ou guardar fora do contexto, que é o tema da aula Prompt e contexto. Memória persistente tem um custo que a seção 6 já apontou (o agent ganha escrita na própria pasta), então ligue-a quando houver algo a aprender, e não por reflexo.

23. Personalizar um agente: instruções, ferramentas e subagents

Personalizar um agente significa mexer nas peças da anatomia da seção 2 sem trocar o modelo. Há três alavancas, e cada uma muda um aspecto diferente do comportamento. A tabela relaciona cada alavanca com o que a aula já mostrou no Claude Code:

As instruções vêm primeiro porque são a alavanca mais barata e a que mais pesa. Um prompt de sistema com papel, método, formato de resposta e limites (o molde da seção 7) transforma um modelo genérico num revisor ou num explorador. O CLAUDE.md cumpre outra função: ele guarda o que vale para o projeto inteiro (convenções, comandos de teste, regras de delegação), enquanto o corpo do agent guarda o que vale só para aquele papel. Misturar os dois é um erro comum, e o sintoma é um CLAUDE.md que cresce até afogar o resto do contexto.

As ferramentas vêm em segundo lugar, e a regra é o menor privilégio, da seção 6. Cada ferramenta que você dá é uma capacidade a mais e também uma superfície a mais para erro. O ponto que a prova tende a explorar é que a descrição da ferramenta é a interface com o modelo: ele escolhe o que chamar lendo o nome e a descrição, e não o código. Duas ferramentas com descrições parecidas confundem o agent do mesmo modo que dois subagents com descrições parecidas confundem o roteamento. A Anthropic relata, no texto sobre o sistema de pesquisa multiagente, um caso em que reescrever descrições ruins reduziu o tempo de tarefa em 40%.

Subagents próprios são a terceira alavanca, e a mais pesada. Eles valem quando uma parte do trabalho pede contexto isolado, outro modelo ou outro conjunto de ferramentas (as razões da seção 4). O mecanismo para limitar a quem um agent pode delegar é a lista em tools: tools: Agent(worker, researcher), Read, Bash permite que a sessão crie só esses dois subagents, o que também é uma forma de limitar o que um agente com instruções ambiciosas consegue fazer.

Uma lacuna que declaro: esta aula descreve as três alavancas só no Claude Code. As mesmas ideias existem quando você monta o laço por conta própria com a API (o prompt de sistema, a lista de ferramentas que você passa na requisição e outras chamadas ao modelo escritas como ferramentas), mas os nomes exatos dos campos do Claude Agent SDK eu não consultei, e a aula 5.2 da trilha é o lugar de cobrir isso.

Um roteiro para personalizar na ordem certa: escreva primeiro a instrução e teste com as ferramentas mínimas, acrescente uma ferramenta só quando o agent travar por falta dela, e crie um subagent só quando a conversa principal começar a poluir ou a custar caro. Cada alavanca acionada sem necessidade deixa o agente mais difícil de entender e de depurar.

24. Hooks como trava determinística

Um hook é um comando (ou outro tipo de manipulador) que o Claude Code executa num ponto fixo do seu ciclo de vida, e que pode inspecionar e, em alguns pontos, bloquear o que está acontecendo. A seção 6 mostrou um exemplo no frontmatter de um agent. Aqui a pergunta é mais geral: quando um hook garante uma regra que o prompt não garante?

A diferença está em quem aplica a regra. Uma instrução no prompt (“nunca apague arquivos”) é lida pelo modelo, que decide se a segue, e nenhuma probabilidade de obediência é igual a 100%. A documentação oficial descreve os hooks como controle determinístico: certas ações acontecem sempre, em vez de depender de o modelo escolher fazê-las. O hook roda como código, no mesmo ponto, com a mesma lógica, não importa o que o modelo “pensou” ou o que um texto malicioso num arquivo lido o convenceu a fazer. É a mesma razão pela qual um banco de dados valida restrições na própria base e não confia que a aplicação sempre as respeite.

Os eventos são os pontos em que um hook pode se plugar. Consultei a documentação oficial em outubro de 2026, e a lista é longa (cerca de 30 eventos, e ela cresce de versão em versão). Os que importam para este estudo:

A coluna “pode bloquear” é a que decide o uso. Para impedir uma ação, o evento tem de ocorrer antes dela: PreToolUse é o ponto clássico, porque o comando ainda não rodou. Um PostToolUse não desfaz nada, só reage ao que já aconteceu (formatar o arquivo editado, por exemplo).

O mecanismo de bloqueio no caso de manipuladores de comando é o código de saída. O hook recebe o JSON da chamada pela entrada padrão (o script da seção 6 lê tool_input.command com jq). Sair com código 0 deixa seguir. Sair com 2 bloqueia, nos eventos que podem bloquear, e o texto escrito em stderr volta para o Claude como motivo, para que ele tente outro caminho. Qualquer outro código de saída é tratado como erro que não bloqueia: a ação prossegue. Essa é a armadilha mais importante da seção, porque um script de validação com bug, que quebra com código 1, deixa tudo passar sem aviso. Escreva o hook para falhar fechado (trate qualquer erro de forma explícita e saia com 2) e teste-o com uma entrada que deve ser bloqueada. A documentação também menciona uma opção onFailure: "block" para mudar esse comportamento, que apareceria a partir da versão 2.1.295. Li isso na página de referência e não testei.

A configuração mora num arquivo de settings, no bloco hooks, com um matcher que escolhe a ferramenta:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

Os locais, segundo a documentação, são ~/.claude/settings.json (todos os seus projetos), .claude/settings.json (o projeto, versionável), .claude/settings.local.json (o projeto, fora do git), as configurações gerenciadas da organização, o hooks/hooks.json de um plugin e o frontmatter de skills e de subagents. As configurações gerenciadas não podem ser desligadas pelos níveis abaixo, o que torna os hooks da organização uma trava que o desenvolvedor individual não remove. Além de comandos, a documentação lista manipuladores http, mcp_tool, prompt e agent. Os dois últimos usam um modelo para julgar, então servem a decisões que pedem julgamento e perdem a garantia determinística: o resultado volta a ser uma decisão probabilística.

Quando usar cada ferramenta de controle? Um resumo:

Um hook não substitui o menor privilégio nem o prompt. Ele é a última camada: o prompt reduz a chance de o modelo tentar a ação errada, a lista de ferramentas reduz o que ele pode tentar, e o hook pega o que passar pelas duas. Por isso o item “regras críticas garantidas por hook, não só por prompt” está no checklist da seção 18.

Fontes

• Custom subagents no Claude Code: arquivo, campos, escopo, herança de ferramentas, limites.
• Hooks no Claude Code (referência) e guia de hooks: eventos, códigos de saída, tipos de manipulador e locais de configuração (consultados em outubro de 2026). Li apenas a primeira parte da página de referência, que é muito longa, então detalhes de esquema de cada evento não foram conferidos.
• Building effective agents: workflows, agents, os cinco padrões e o desenho de ferramentas.
• How we built our multi-agent research system: orquestrador e subagents, escala de esforço, custo, avaliação.

Relacionados

• MCP
• concorrência
• Prompt e contexto