Aula 12Subagentes: ajudantes para tarefas à parte

Objetivos

Ao final desta aula você vai saber:

• O que é um subagente, um ajudante com a própria memória de trabalho
• Por que um ajudante deixa a conversa principal mais leve
• Como os ajudantes aparecem no terminal enquanto trabalham, em segundo plano
• Pedir um ajudante para uma tarefa à parte e conferir o contexto antes e depois
• Se quiser, criar um ajudante seu, só de leitura, e abrir o Claude de novo para ele aparecer

Na Aula 07, você viu que a conversa tem uma memória de trabalho, o contexto, e que ela enche. Ler muitos arquivos enche rápido, e quase tudo o que aparece no caminho nem importa para a tarefa. Para isso, o Claude pode chamar ajudantes. Esta é uma aula de "saiba que existe": o Claude já usa esses ajudantes sozinho, e você aprende a reconhecer um, a pedir um e, se quiser, a criar o seu.

Para esta aula: a pasta da sua página (a confeitaria, ou a da sua ideia). As regras da casa da Aula 11 ajudam, mas não são obrigatórias. Não precisa de GitHub.

O que é um subagente

Um subagente (subagent) é um ajudante: um Claude à parte, com a própria memória de trabalho, que faz uma parte da tarefa e volta só com o resumo. Tudo o que ele leu no caminho fica com ele; para a sua conversa, volta só a resposta. Por isso, a conversa principal não enche.

Duas coisas para saber desde já:

• Em geral, o ajudante começa sem a conversa de vocês. O Claude manda para ele um recado com a tarefa, e só o resultado volta. Por isso, diga no pedido o que você quer de volta, como "me traga só a lista".
• O ajudante também gasta do seu plano. Ele poupa a memória de trabalho da conversa, não o uso (Aula 08).

O Claude já usa sozinho

Quando precisa ler muitos arquivos para entender alguma coisa, o Claude pode mandar um ajudante de exploração, que só lê e não muda nada. No Plan Mode, ele usa outro ajudante para pesquisar antes de montar o plano. Você não precisa pedir: ele decide.

Os ajudantes que o Claude chama trabalham em segundo plano: enquanto isso, a conversa continua, e você pode seguir pedindo outras coisas. No terminal, você percebe assim:

• na conversa, aparece uma linha com o nome do ajudante e, entre parênteses, a tarefa dele;
• embaixo da caixa de mensagem, aparece uma linha para cada ajudante que está trabalhando;
• se um ajudante precisar de licença para alguma coisa, o pedido aparece na conversa principal, com o nome dele, e você aprova ou recusa, como sempre;
• quando ele termina, a linha some, e o resultado chega na conversa. Por alguns segundos, o rodapé mostra /tasks to see subagents: o /tasks lista o trabalho em segundo plano da conversa.

Experimente: um ajudante para revisar os textos

1. Antes de pedir, digite /context e anote o total que ele mostra, como na Aula 07.
2. Peça:

Use um subagente para revisar o português de todos os textos da página e
me trazer só a lista de erros, sem mudar nada.

3. Enquanto o ajudante trabalha, repare na linha dele embaixo da caixa de mensagem. Quando ele termina, a lista chega na conversa, mais ou menos assim (a sua vai ser outra, ou pode vir vazia, se não houver erros):

Encontrei 3 erros nos textos da página:

1. Cardápio: "Torta de limao" está sem o til. O certo é "Torta de limão".
2. Formulário: "Data de entrga". O certo é "Data de entrega".
3. Horário: "terca a domingo". O certo é "terça a domingo".

4. Digite /context de novo e compare: a conversa principal quase não cresceu. Tudo o que o ajudante leu ficou com ele.

Critério de pronto: a lista de erros aparece na conversa, a página continua igual e o /context quase não mudou.

💡 Se o Claude fizer a revisão sozinho, sem chamar ajudante, peça de novo, mais direto: "use um subagente para isso".

Para corrigir, peça na conversa principal, no Manual: "corrija os erros da lista". Aprove mudança por mudança e confira a página no navegador. Ficou bom? "Guarde uma versão com os textos corrigidos."

Opcional: um ajudante seu, só de leitura

Se você vai revisar os textos de vez em quando, dá para ter um ajudante seu, com nome e com as regras dele. Peça:

Crie um subagente do projeto chamado revisor-de-textos, que só lê os
arquivos, aponta erros de português e de acentuação e nunca muda nada.

O Claude escreve um arquivo novo, revisor-de-textos.md, na pasta .claude/agents/, dentro da pasta da sua página. A pasta .claude é protegida, e o Claude pede licença para escrever nela. Leia o pedido e escolha Yes, que vale só para esta vez. Para entender o arquivo, peça: "me explique em português simples o que o arquivo do revisor-de-textos diz".

A pasta nova pede para abrir o Claude de novo. Quando a pasta agents não existia no começo da conversa, como acontece com o primeiro ajudante, a conversa aberta não enxerga o ajudante novo. Saia com /exit e abra o Claude de novo com claude --continue, que volta para a mesma conversa (Aula 10). Confira se aparece manual mode on (se não aparecer, aperte Shift + Tab até aparecer) e peça:

Use o revisor-de-textos para revisar a página.

Na conversa, aparece a linha com o nome revisor-de-textos e a tarefa dele. Daqui para a frente, o Claude também pode chamar o revisor sozinho, quando um pedido combinar com o que o arquivo dele diz. E, como a pasta já existe, os próximos ajudantes que você criar aparecem sem abrir o Claude de novo.

Para ir além (opcional): subagentes por dentro

🔧 Para ir além (para quem já programa; pode pular): esta parte mostra o arquivo de um subagente, as ferramentas e o modelo de cada um, os ajudantes que já vêm prontos, o modo fork, como chamar pelo nome, a memória própria, as skills pré-carregadas e o /agents. Se você nunca programou, pule direto para o Na prática: tudo o que ele pede já foi explicado acima.

Como é o arquivo

Um subagente é um arquivo Markdown com um cabeçalho em YAML (o frontmatter) entre duas linhas ---. Os do projeto ficam em .claude/agents/ (vão para o Git, e o time inteiro usa); os pessoais, em ~/.claude/agents/ (valem em todos os seus projetos). O revisor-de-textos sai mais ou menos assim:

---
name: revisor-de-textos
description: Revisa os textos da página procurando erros de português e de acentuação. Use quando pedirem para revisar o português da página.
tools: Read, Grep, Glob
---

Você é revisor de textos em português do Brasil. Ao ser chamado:

1. Leia os arquivos da página.
2. Aponte cada erro de português ou de acentuação, com o arquivo, o trecho
   errado e a correção.
3. Devolva só a lista, curta. Se não houver erros, diga isso.

Nunca mude nenhum arquivo.

Só name e description são obrigatórios. A descrição é o que faz o Claude saber quando chamar o ajudante. Sem tools, ele herda todas as ferramentas disponíveis para subagentes; com Read, Grep, Glob, ele só lê e busca. Num projeto de código, um revisor costuma ganhar também o Bash, para rodar git diff, e os comandos dele passam pelas mesmas regras de permissão da sua sessão:

Crie um subagente de projeto chamado revisor-de-codigo em .claude/agents/
que revise as mudanças recentes procurando bugs, testes enfraquecidos e
valores fixos no código. Ele pode ler arquivos e rodar git diff, mas não
deve editar nada.

O Claude Code vigia as pastas agents: um arquivo novo ou editado vale em poucos segundos, sem reiniciar. Os três casos que pedem reiniciar: o primeiro arquivo numa pasta agents que não existia no começo da sessão; um subagente numa pasta adicionada com --add-dir ou /add-dir; e as sessões abertas com --disable-slash-commands.

Os ajudantes que já vêm prontos

Há outros, chamados em casos específicos, como o claude-code-guide, que responde perguntas sobre o próprio Claude Code. Os subagentes criados por você carregam os CLAUDE.md da sessão, mas não a memória automática dela.

Ferramentas e modelo

• Ferramentas: tools lista o que o ajudante pode usar, e disallowedTools tira ferramentas da lista herdada. Um ajudante em segundo plano, que é o padrão, recebe um conjunto menor de ferramentas.
• Modelo: model: sonnet, opus, haiku, fable ou inherit (o mesmo da conversa). A ordem é: o modelo que o Claude pede na chamada, o do arquivo, a variável CLAUDE_CODE_SUBAGENT_MODEL e, por fim, o da conversa principal. Um modelo menor gasta menos do plano.

O modo fork

Um fork é um subagente que começa com uma cópia da conversa inteira, em vez de começar do zero. As ferramentas que ele usa continuam fora da sua conversa, e só o resultado volta; mas ele perde a vantagem de começar sem viés. Para uma revisão imparcial, peça um subagente comum.

O modo fork vem ligado desde a v2.1.302 (no terminal interativo, desde a v2.1.232): o Claude pode abrir forks sozinho, e os ajudantes que ele chama não fazem a conversa esperar. Você mesmo abre um fork com /subtask <tarefa>. Para o Claude poder esperar um ajudante, desligue o modo fork com CLAUDE_CODE_FORK_SUBAGENT=0 no bloco env do settings.json e abra o claude de novo; para barrar só os forks, "Agent(fork)" no permissions.deny. Com o modo fork desligado, Ctrl + B manda para o segundo plano o que o Claude está esperando.

O painel e o /tasks

O painel embaixo da caixa de mensagem tem uma linha por ajudante, e os ajudantes que chamam outros aparecem em árvore. Num fork, ↑ e ↓ andam pelas linhas, Enter abre a conversa dele, x para o fork e Esc volta para a caixa de mensagem. O /tasks mostra o trabalho em segundo plano da sessão, inclusive os ajudantes que acabaram de terminar, e Enter abre a conversa de cada um. Ctrl + X Ctrl + K para todos os ajudantes em segundo plano (aperte duas vezes em até 3 segundos para confirmar).

Chamar pelo nome

• Em linguagem natural: "Use o revisor-de-textos para revisar a página." O Claude decide se delega.
• Com @: digite @ e escolha o ajudante na lista, ou escreva @agent-revisor-de-textos. Assim ele roda com certeza.
• A sessão inteira como o ajudante: claude --agent revisor-de-textos abre uma sessão com as ferramentas, as instruções e o modelo dele.

Memória própria e skills pré-carregadas

• Memória própria: memory: project dá ao ajudante uma pasta para guardar o que aprende entre conversas, em .claude/agent-memory/<nome>/, que vai para o Git. memory: user fica em ~/.claude/agent-memory/<nome>/, para todos os projetos, e memory: local, em .claude/agent-memory-local/<nome>/, fora do Git. Ela faz parte da memória automática: com a memória automática desligada, o campo não tem efeito. Atenção: com memory, o ajudante ganha Read, Write e Edit para cuidar das anotações, então um revisor "só de leitura" deixa de ser.
• Skills pré-carregadas: a chave skills lista skills pelo nome (Aula 13). Diferente da conversa principal, aqui a skill inteira entra no contexto do ajudante logo no começo.

O /agents de hoje

Até a v2.1.197, o /agents abria um assistente para criar e gerenciar subagentes. Hoje, ele só mostra um lembrete: peça ao Claude ou edite os arquivos em .claude/agents/ e ~/.claude/agents/.

Quer ir mais fundo? Veja a página de subagentes da documentação oficial (em inglês).

Na prática

Use a pasta da sua página (a confeitaria, ou a da sua ideia).

1. Abra o terminal, entre na pasta e abra o Claude Code: cd Documents/confeitaria, com o nome da sua pasta, e depois claude. Aperte Shift + Tab uma vez e confira se aparece manual mode on.
2. Digite /context e anote o total.
3. Peça: "use um subagente para revisar o português de todos os textos da página e me trazer só a lista de erros, sem mudar nada". Repare na linha do ajudante embaixo da caixa de mensagem enquanto ele trabalha.
4. Quando a lista chegar, digite /context de novo e compare. Está pronto quando a lista aparece e o total quase não mudou.
5. Peça "corrija os erros da lista", aprove mudança por mudança, confira no navegador e peça "guarde uma versão com os textos corrigidos".
6. Opcional: peça o revisor-de-textos, como está lá em cima, e aprove a escrita na pasta .claude. Saia com /exit, abra de novo com claude --continue, confira o manual mode on e peça: "use o revisor-de-textos para revisar a página".

Resumo

• Um subagente é um ajudante: um Claude à parte, com a própria memória de trabalho, que faz uma parte da tarefa e volta só com o resumo. A conversa principal quase não cresce.
• O Claude já usa ajudantes sozinho, para ler muita coisa. Eles trabalham em segundo plano: no terminal, aparecem numa linha embaixo da caixa de mensagem, e o /tasks lista o que está rodando.
• Em geral, o ajudante começa sem a conversa: diga no pedido o que você quer de volta. E ele também gasta do seu plano.
• Para criar um ajudante seu, peça ao Claude. Ele fica num arquivo em .claude/agents/. Se a pasta agents acabou de nascer, saia com /exit e abra de novo com claude --continue.

Na próxima aula, você vai conhecer as receitas que o Claude segue para fazer uma tarefa do seu jeito: as skills.