E3 · Explorador só de leitura
10 minCrie .claude/agents/explorador.md no projeto de treino e rode o conferidor.
Pronto quando: o conferidor imprime explorador · tools: Read, Grep, Glob · model: inherit · escreve: não.
Aula 2 · 18 min
Subagentes: contexto limpo, retorno curto
Um subagente faz a parte barulhenta numa janela de contexto própria e devolve só o resumo. Ele vale pelo que não volta: logs, buscas e arquivos que a conversa principal nunca mais vai ler. Nesta aula você escreve um subagente só de leitura com retorno de até 12 linhas e confere, de verdade, o tamanho do que voltou.
Começar a aula
Nesta aula você vai
- 1O que o subagente recebe e o que ele devolve
- 2O arquivo .claude/agents/[nome].md e os campos que importam
- 3Ferramentas restritas: o que a lista trava e o que só a instrução pede
- 4Retorno com formato fixo e linha de confiança
Objetivo: criar um subagente só de leitura com retorno de até 12 linhas e conferir que a resposta dele cabe na conversa principal.
01Ida e volta de um subagente
Comportamento do Claude Code 2.1.303, pela doc oficial lida em 19/10/2026. Clique em cada etapa.
Clique em cada bloco do diagrama para ver o que ele faz.
Fork é outra coisa: herda a conversa inteira (/subtask) e perde o isolamento de entrada. Bom para tarefa lateral que precisa do que já foi dito.
02Os campos que decidem
Do frontmatter suportado, quatro mudam o comportamento no dia a dia.
1. description
O Claude delega quando a tarefa casa com a descrição. Escreva quando usar e quando não usar, em uma frase.
Arquivo novo em .claude/agents/ entra sem reiniciar, exceto quando a pasta agents/ não existia no início da sessão.
2. tools
Lista do que pode usar. Sem o campo, herda as da conversa. Sem Write, Edit e Bash, ele não grava nada, por mais que o modelo queira.
disallowedTools com especificador, como Bash(git push *), remove a ferramenta inteira; para bloquear só o comando, use permissions.deny.
3. model
Aceita apelido ou inherit. Escolha pelo nível do papel (aula 7), não pelo nome do dia: os nomes mudam.
O kit do runtime usa opus, sonnet e haiku nos três papéis; trate isso como exemplo de níveis diferentes.
4. Corpo
O corpo do arquivo vira o prompt de sistema. Ponha nele o formato da resposta: número máximo de linhas, caminho:linha como prova e uma linha final de confiança.
É o formato que deixa o orquestrador ler 10 resumos sem encher a própria janela.
03Um explorador só de leitura
Crie o arquivo, confira os campos sem gastar cota e depois faça uma chamada real.
.claude/agents/explorador.md · em ~/treino-multi
--- name: explorador description: Procura no projeto e devolve só o resumo. Use para varrer muitos arquivos sem encher a conversa principal. tools: Read, Grep, Glob model: inherit --- Você é o explorador. Não altere nada. Devolva no máximo 12 linhas: 1. A resposta em uma frase. 2. Até 8 linhas no formato caminho:linha — o que tem lá. 3. Última linha: CONFIANÇA alta|média|baixa e o que você não conferiu.
Terminal · ensaio sem cota: conferir os subagentes do projeto
cd ~/treino-multi
python3 - .claude/agents/*.md <<'PY'
import sys, re
for f in sys.argv[1:]:
m = re.match(r"---\n(.*?)\n---", open(f, encoding="utf-8").read(), re.S)
if not m:
print(f, "→ SEM frontmatter"); continue
d = {k.strip(): v.strip() for k, v in (l.split(":", 1) for l in m.group(1).splitlines() if ":" in l)}
tools = d.get("tools", "(herda todas)")
escreve = "tools" not in d or any(x in tools for x in ("Write", "Edit", "Bash"))
print(f"{d.get('name', '?')} · tools: {tools} · model: {d.get('model', '(herda)')} · escreve: {'sim' if escreve else 'não'}")
PYTerminal · chamada real (gasta um pouco da cota)
cd ~/treino-multi claude -p "Use o subagente explorador para descobrir onde este projeto define a própria versão e quais arquivos citam essa versão. Repita apenas o resumo que ele devolver, sem comentar." < /dev/null > resposta.md grep -c "^CONFIANÇA" resposta.md; wc -l < resposta.md
Exemplo do repositório
## conferidor (sem cota) executor · tools: Read, Write, Edit, Bash, Grep, Glob · model: sonnet · escreve: sim explorador · tools: Read, Grep, Glob · model: inherit · escreve: não planejador · tools: Read, Grep, Glob · model: opus · escreve: não revisor · tools: Read, Bash, Grep, Glob · model: haiku · escreve: sim ## resposta.md (chamada real, 29 s) A versão é 0.3.0 e a fonte da verdade é o arquivo VERSION na raiz. Não existe package.json nem pyproject, e nenhuma constante no código define a versão. Ela também aparece em mais 6 arquivos, num total de 9 ocorrências: - `VERSION:1`: `0.3.0` (definição) - `CHANGELOG.md:3`: `## 0.3.0 — 2026-10-05` - `runtime/mods/runtime-guarda/.claude-plugin/plugin.json:3`: `"version": "0.3.0"` - `runtime/mods/runtime-painel/.claude-plugin/plugin.json:3`: `"version": "0.3.0"` - `guia/index.html:329` e `:335`: rótulo "Fase 3 · 0.3.0" e rodapé "INEMA Agent Runtime 0.3.0" (… guia/en e guia/es, as mesmas duas citações …) CONFIANÇA alta. Não conferi o que o .gitignore exclui nem os outros números de versão (0.1.0, 0.2.0), e não verifiquei se algum script lê o VERSION.
Os títulos com ## separam as duas rodadas. Cortes declarados: duas linhas do guia traduzido e uma linha final que o CLAUDE.md global da máquina da captura acrescenta. Na sua máquina, wc -l deve ficar entre 10 e 15.
O conferidor marcou revisor · … · escreve: sim. O arquivo do kit diz "Não altere arquivos", mas a lista de ferramentas inclui Bash, e Bash grava. A instrução é um pedido ao modelo; a lista de ferramentas é a trava.
revisor · tools: Read, Bash, Grep, Glob · model: haiku · escreve: sim
O revisor precisa de Bash para rodar os critérios. Para ele não gravar de fato, a saída é sandbox (aula 5) ou regra de permissão; guarda contra apagar e escrever é assunto do curso 4. E a chamada real sem < /dev/null espera 3 s pelo stdin e avisa: Warning: no stdin data received in 3s.
04Prática
O ensaio confere o arquivo; a chamada real confere o retorno.
E4 · Retorno que cabe
10 minFaça a chamada real. Depois troque a pergunta por uma do seu projeto de verdade, com o mesmo subagente.
Pronto quando: grep -c "^CONFIANÇA" resposta.md → 1 e wc -l < resposta.md → no máximo 15, nas duas perguntas.
05Teste da aula
Pergunta 1 de 4
O que volta do subagente para a conversa principal?competência
Correto
Só a resposta final volta. É por isso que o formato do retorno, escrito no corpo do arquivo, é a parte mais importante.Não é essa
Só a resposta final volta. É por isso que o formato do retorno, escrito no corpo do arquivo, é a parte mais importante.Rever: Ida e volta de um subagentePergunta 2 de 4
O subagente recebe o histórico da conversa principal?competência
Correto
Subagente comum começa limpo. O fork herda a conversa inteira, e com isso perde o isolamento de entrada.Não é essa
Subagente comum começa limpo. O fork herda a conversa inteira, e com isso perde o isolamento de entrada.Rever: Ida e volta de um subagentePergunta 3 de 4
Um revisor tem tools: Read, Bash, Grep, Glob e a instrução "não altere arquivos". Ele consegue gravar?
Correto
Com Bash ele pode escrever com echo, sed ou rm. Para travar de fato: sandbox (aula 5) ou regra de permissão (curso 4).Não é essa
Com Bash ele pode escrever com echo, sed ou rm. Para travar de fato: sandbox (aula 5) ou regra de permissão (curso 4).Rever: Um explorador só de leituraPergunta 4 de 4
Quando NÃO vale delegar para um subagente?
Correto
Ida e volta e contexto compartilhado ficam na conversa principal; o subagente começa do zero e teria de reler tudo.Não é essa
Ida e volta e contexto compartilhado ficam na conversa principal; o subagente começa do zero e teria de reler tudo.Rever: Ida e volta de um subagenteTeste concluído
Você acertou {a} de {n}. Acertando todas, a aula é marcada como concluída.Escolha uma alternativa. A explicação aparece depois da sua tentativa.
06Em três frases
Vale pelo que não voltaLogs, buscas e arquivos ficam na janela do subagente; volta só o resumo.
Ferramenta é travaRead, Grep, Glob não grava; Bash grava, diga a instrução o que disser.
Formato fixoMáximo de linhas, caminho:linha como prova e linha de confiança, escritos no corpo do arquivo.