Passar tarefas a subagentes do Claude Code

Há trabalhos que enchem uma conversa de material que nunca mais vais ver: um log de 4000 linhas, uma bateria de testes completa, uma pesquisa por centenas de ficheiros. Um subagente faz esse trabalho numa conversa à parte, só dele, e devolve apenas o relatório. A tua conversa principal fica com a resposta, e não com o monte de onde ela veio.

Este guia constrói um subagente para ler logs do servidor, mostra o que ele sabe quando arranca, e acaba no que os subagentes de um repositório podem fazer na tua máquina antes de confiares na pasta.

O que é um subagente

Um subagente é um ajudante que o Claude arranca para uma tarefa. Tem:

• o seu próprio contexto, que começa vazio. Não vê a tua conversa, só a tarefa que o Claude lhe escreve.
• as suas próprias instruções, escritas no ficheiro dele.
• as suas próprias ferramentas, que podem ser menos do que as da conversa principal.
• o seu próprio modelo, que pode ser um mais barato.

Quando acaba, o relatório volta para a conversa principal, e tudo o que ele leu pelo caminho fica para trás.

O Claude Code traz alguns subagentes de origem e usa-os por iniciativa própria. O Explore pesquisa e lê código sem mudar nada, o Plan faz a pesquisa no modo Planear (plan), e o general-purpose trata de tarefas com vários passos. Os teus próprios, escreve-los para os trabalhos que repetes.

O teu primeiro subagente

Os subagentes são ficheiros Markdown numa pasta .claude/agents/. Este lê logs, não consegue mudar nada, e corre no Haiku, o modelo Claude mais pequeno e mais barato.

---
name: log-reader
description: Reads server log files and reports what matters. Use when the user asks about errors, warnings or problems in a log.
tools: Read, Grep, Glob
model: haiku
---

You read log files and report back briefly.

Group the entries by kind of problem. For each group, give a count,
the first and last time, and one example line.
Put the problem most likely to hurt real users first.
Do not suggest fixes unless asked.
Never paste more than five log lines in total.

• name e description são obrigatórios. O Claude lê a descrição para decidir quando o subagente serve para um pedido.
• tools lista as únicas ferramentas que ele pode usar. Read, Grep e Glob leem e procuram ficheiros. Sem Edit, Write nem Bash, não consegue mudar nada.
• model aceita haiku, sonnet, opus, fable ou inherit. Se o deixares de fora, o subagente corre no mesmo modelo da tua conversa.
• O corpo são as instruções do subagente. Substituem as instruções habituais do Claude Code, por isso diz claramente o que queres de volta.

O ficheiro pode ser escrito em português. Usámos inglês porque é assim que vais encontrar a maior parte dos exemplos.

Guarda-o em .claude/agents/ dentro de um projeto para o usares aí, ou em ~/.claude/agents/ para o usares em todos os projetos. Também podes pedir ao Claude que escreva o ficheiro. O comando /agents deixou de o fazer no Claude Code 2.1.198, e agora só te indica estas pastas.

Depois, pede-o pelo nome:

> Use the log-reader subagent to check logs/error.log and tell me what is wrong

Para teres a certeza de que corre esse subagente, menciona-o com @agent-log-reader no início do pedido, ou escolhe-o na lista que abre quando escreves @.

O que aconteceu no nosso teste

Demos-lhe um log de erros do nginx com 4000 linhas (368 KB), com alguns problemas no meio do ruído. O subagente correu no Haiku, como diz o ficheiro, e trabalhou só com Read e Grep. O ficheiro era grande demais para uma só leitura, por isso pesquisou-o aos bocados. O relatório apontou 10 falhas de ligação ao PHP-FPM como o problema que afetava os visitantes, e 65 pedidos de robôs a wp-login.php.

O log em si nunca entrou na conversa principal. A conversa principal leu só o relatório, e mais 60 linhas do ficheiro quando quis confirmar uma coisa.

Confirmar foi a decisão certa. O primeiro relatório dava conta de 75 das 4000 linhas e não dizia nada sobre as outras. A conversa principal reparou, mandou o mesmo subagente voltar ao trabalho com uma nova pergunta, e recebeu contagens que batiam certo: 3882 linhas de info, 75 erros e 43 avisos. A conversa principal só sabe o que o relatório diz, por isso pede contagens que tenham de bater certo, e lê o relatório como lerias o de um colega.

Deixa o Claude escolher o subagente

Não precisas de dizer o nome. No nosso teste, bastou a pergunta simples abaixo: o Claude escolheu o log-reader pela descrição.

> What is going wrong in logs/error.log?

Se um subagente nunca é escolhido, aproxima a descrição das palavras que usas quando pedes. Se é escolhido vezes demais, torna a descrição mais estreita.

O que um subagente sabe quando arranca

Um subagente começa com:

• as suas próprias instruções, e dados como a pasta de trabalho
• a tarefa que o Claude lhe escreveu
• os teus ficheiros CLAUDE.md, os mesmos que a conversa principal carrega (o Explore e o Plan de origem saltam-nos)
• o estado do git do projeto

Não recebe a tua conversa, os ficheiros que o Claude já leu, nem a tua memória automática. Se alguma coisa que disseste antes conta para a tarefa, como "ignora a pasta vendor", volta a dizê-la no pedido.

Cada subagente trabalha na sua própria janela de contexto e faz os seus próprios pedidos, que contam para os mesmos limites de utilização da tua conversa. Um subagente no Haiku custa menos num trabalho como ler logs, mas não é de graça.

Desligar um subagente

Uma regra de bloqueio impede o Claude de usar um subagente, seja teu ou de origem:

{
  "permissions": {
    "deny": ["Agent(log-reader)"]
  }
}

No nosso teste, com essa regra, o Claude nunca chamou o subagente e contou as linhas ele próprio. Uma regra de bloqueio só com Agent desliga todos os subagentes.

Subagentes do repositório de outra pessoa

A pasta .claude/agents/ de um projeto vem com o repositório, tal como o .mcp.json. A documentação diz que, até confiares na pasta, o Claude Code salta duas partes de um subagente de projeto: os hooks do ficheiro dele e os servidores MCP definidos no ficheiro dele. Vimos a primeira: um hook no ficheiro de um subagente não correu numa pasta nunca marcada como de confiança.

O modo de permissões do subagente é outra história. Um ficheiro de subagente pode definir permissionMode e, quando a tua sessão está no modo Manual (default), o subagente corre no modo que o ficheiro dele define. Testámos isto com claude -p no modo Manual, em duas pastas nunca marcadas como de confiança:

• Um subagente com Read, Write e Edit e sem permissionMode tentou escrever um ficheiro e foi bloqueado: Claude requested permissions to write to ... but you haven't granted it yet.
• O mesmo subagente com permissionMode: acceptEdits no ficheiro escreveu o ficheiro, sem perguntar nada.
• Um subagente só com Bash e permissionMode: auto correu um comando da shell que escreveu um ficheiro, sem perguntar nada. No modo automático, um classificador decide que comandos correm sem perguntar, e deixou passar este.

Isto é diferente do "defaultMode": "auto", que o Claude Code ignora nas definições de um projeto precisamente para que um repositório não consiga pôr a tua sessão no modo automático. Um subagente do projeto consegue, pelo menos para o trabalho dele.

A documentação diz que o modo Aceitar edições (acceptEdits) cobre edições de ficheiros e comandos de ficheiros comuns dentro das pastas do projeto, e não noutros sítios da máquina. O modo automático depende do classificador, que avalia cada comando.

Numa sessão interativa numa pasta nova, a caixa de confiança vem primeiro, por isso já disseste que sim à pasta quando o permissionMode de um subagente se aplica. Mesmo assim, um subagente pode trabalhar com menos pedidos de permissão do que esperarias no modo Manual, por isso lê os ficheiros primeiro.

Quando um subagente não aparece

• Confirma a primeira linha. O ficheiro tem de começar com --- logo na primeira linha, ou o Claude Code lê-o como um documento simples.
• Confirma o name e a description. Um ficheiro sem name é tratado como documentação, e um sem description é ignorado. Nenhum dos dois mostra erro na sessão.
• Confirma os nomes dos campos. Têm de coincidir exatamente, como disallowedTools e permissionMode. Um campo desconhecido é ignorado sem erro.
• Reinicia depois de criares a pasta. O Claude Code vigia a pasta .claude/agents/ e apanha as alterações em segundos, mas só se a pasta já existia quando a sessão começou.
• Para saberes porque é que um ficheiro foi ignorado, corre claude --debug e lê o registo de depuração.

Fontes

• Create custom subagents, documentação do Claude Code (em inglês)
• Configure permissions, documentação do Claude Code, incluindo "What runs before you trust a folder" (em inglês)
• Run Claude Code programmatically, documentação do Claude Code, sobre o --bare (em inglês)