Passe tarefas para subagentes do Claude Code

Alguns trabalhos enchem a conversa de material que você nunca mais vai olhar: um log de 4.000 linhas, uma rodada completa de testes, uma busca em centenas de arquivos. Um subagente faz esse trabalho em uma conversa separada, só dele, e devolve apenas o relatório. A sua conversa principal fica com a resposta, e não com a pilha de onde ela saiu.

Este guia monta um subagente para ler logs de servidor, mostra o que ele sabe quando começa e termina com o que os subagentes de um repositório podem fazer na sua máquina antes de você confiar na pasta.

O que é um subagente

Um subagente é um ajudante que o Claude inicia para uma tarefa. Ele tem:

• contexto próprio, que começa vazio. Ele não vê a sua conversa, só a tarefa que o Claude escreve para ele.
• instruções próprias, escritas no arquivo dele.
• ferramentas próprias, que podem ser só uma parte das da conversa principal.
• modelo próprio, que pode ser mais barato.

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

O Claude Code já vem com alguns subagentes prontos e os usa por conta própria. O Explore busca e lê código sem mudar nada, o Plan faz a pesquisa no modo Planejar (plan), e o general-purpose cuida de tarefas com várias etapas. Os seus próprios, você escreve para os trabalhos que se repetem.

Seu primeiro subagente

Subagentes são arquivos Markdown em uma pasta .claude/agents/. Este lê logs, não consegue mudar nada e roda no Haiku, o menor e mais barato dos modelos Claude.

---
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 buscam arquivos. Sem Edit, Write ou Bash, ele não consegue mudar nada.
• model aceita haiku, sonnet, opus, fable ou inherit. Se você deixar o campo de fora, o subagente roda no mesmo modelo da sua conversa.
• O corpo são as instruções do subagente. Elas substituem as instruções normais do Claude Code, então diga com clareza o que você quer de volta.

O arquivo pode ser escrito em português. Usamos inglês porque é assim que você vai encontrar a maioria dos exemplos.

Salve o arquivo em .claude/agents/ dentro de um projeto para usar ali, ou em ~/.claude/agents/ para usar em todos os projetos. Você também pode pedir para o Claude escrever o arquivo. O comando /agents deixou de fazer isso no Claude Code 2.1.198 e agora só indica essas pastas.

Depois, peça pelo nome:

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

Para garantir que é esse subagente que roda, mencione ele com @agent-log-reader no começo do pedido, ou escolha na lista que abre quando você digita @.

O que aconteceu no nosso teste

Demos a ele um log de erros do nginx com 4.000 linhas (368 KB), com alguns problemas misturados no meio do ruído. O subagente rodou no Haiku, como diz o arquivo, e trabalhou só com Read e Grep. O arquivo era grande demais para uma leitura só, então ele fez buscas por partes. O relatório apontou 10 falhas de conexão com o PHP-FPM como o problema que afetava os visitantes, e 65 requisições de robôs para wp-login.php.

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

Conferir foi a decisão certa. O primeiro relatório cobria 75 das 4.000 linhas e não dizia nada sobre o resto. A conversa principal percebeu, mandou o mesmo subagente de volta com uma nova pergunta e recebeu contagens que fechavam: 3.882 linhas de info, 75 erros e 43 avisos. A conversa principal só sabe o que o relatório diz, então peça contagens que precisem fechar, e leia o relatório como leria o de um colega.

Deixe o Claude escolher o subagente

Você não precisa 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, aproxime a descrição das palavras que você usa quando pede. Se ele é escolhido vezes demais, deixe a descrição mais específica.

O que um subagente sabe quando começa

Um subagente começa com:

• as instruções dele, e informações como a pasta de trabalho
• a tarefa que o Claude escreveu para ele
• os seus arquivos CLAUDE.md, os mesmos que a conversa principal carrega (o Explore e o Plan prontos pulam esses arquivos)
• o status do git do projeto

Ele não recebe a sua conversa, os arquivos que o Claude já leu nem a sua memória automática. Se algo que você disse antes importa para a tarefa, como "ignore a pasta vendor", diga de novo no pedido.

Cada subagente trabalha na própria janela de contexto e faz as próprias requisições, que contam para os mesmos limites de uso da sua conversa. Um subagente no Haiku custa menos em um trabalho como ler logs, mas não sai de graça.

Desligue um subagente

Uma regra de bloqueio impede o Claude de usar um subagente, seja seu ou um dos prontos:

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

No nosso teste, com essa regra, o Claude nunca chamou o subagente e contou as linhas ele mesmo. 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 junto com o repositório, como o .mcp.json. A documentação diz que, até você confiar na pasta, o Claude Code pula duas partes de um subagente de projeto: os hooks e os servidores MCP definidos no arquivo dele. Vimos a primeira: um hook no arquivo de um subagente não rodou em uma pasta nunca marcada como confiável.

O modo de permissão do subagente é outra história. Um arquivo de subagente pode definir permissionMode e, quando a sua sessão está no modo Manual (default), o subagente roda no modo que o arquivo dele define. Testamos isso com claude -p no modo Manual, em duas pastas nunca marcadas como confiáveis:

• Um subagente com Read, Write e Edit e sem permissionMode tentou gravar um arquivo e foi bloqueado: Claude requested permissions to write to ... but you haven't granted it yet.
• O mesmo subagente com permissionMode: acceptEdits no arquivo gravou o arquivo, sem perguntar nada.
• Um subagente só com Bash e permissionMode: auto rodou um comando do terminal que gravou um arquivo, sem perguntar nada. No modo Automático, um classificador decide quais comandos rodam sem perguntar, e ele liberou esse.

Isso é diferente do "defaultMode": "auto", que o Claude Code ignora nas configurações de um projeto justamente para que um repositório não consiga colocar a sua 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 arquivos e comandos comuns de arquivos dentro das pastas do projeto, e não em outros lugares da máquina. O modo Automático depende do classificador, que avalia cada comando.

Em uma sessão interativa em uma pasta nova, a caixa de confiança vem primeiro, então você já disse sim para a pasta quando o permissionMode de um subagente passa a valer. Mesmo assim, um subagente pode trabalhar com menos pedidos de permissão do que você esperaria no modo Manual, então leia os arquivos antes.

Quando um subagente não aparece

• Confira a primeira linha. O arquivo precisa começar com --- logo na primeira linha, senão o Claude Code lê o arquivo como um documento comum.
• Confira o name e a description. Um arquivo sem name é tratado como documentação, e um sem description é ignorado. Nenhum dos dois mostra erro na sessão.
• Confira os nomes dos campos. Eles precisam bater exatamente, como disallowedTools e permissionMode. Um campo desconhecido é ignorado sem erro.
• Reinicie depois de criar a pasta. O Claude Code monitora a pasta .claude/agents/ e pega as mudanças em segundos, mas só se a pasta já existisse quando a sessão começou.
• Para saber por que um arquivo foi ignorado, rode claude --debug e leia o log 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)