Aula 12Subagentes: ajudantes para tarefas à parte

🖥️ Versão Desktop. Nesta versão do curso, você usa o Claude Code no app Claude Desktop, na aba Code. Quase tudo é feito por janelas e botões. Quando uma aula pedir para digitar um comando, ela mostra exatamente o que digitar. Nesta aula, você não digita nenhum comando: os ajudantes aparecem no painel Background tasks, e o contexto, no anel de uso. A parte opcional do fim cita alguns comandos do terminal, para quem já programa.

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 app enquanto trabalham, no painel Background tasks
• Pedir um ajudante para uma tarefa à parte e conferir o anel de uso antes e depois
• Se quiser, criar um ajudante seu, só de leitura, e abrir uma conversa nova 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 modo Plan, 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 app, você acompanha assim:

• abra o menu ⋮, na barra de título da conversa, e escolha Background tasks (tarefas em segundo plano). A opção aparece quando a conversa já tem trabalho em segundo plano: antes do primeiro ajudante, não adianta procurar;
• no painel que abre, clique num ajudante para ver o que ele está fazendo, no painel do subagente, ou para pará-lo;
• se um ajudante precisar de licença para alguma coisa, o pedido aparece na conversa principal, com o nome dele, e você aceita ou recusa, como sempre;
• quando ele termina, o resultado chega na conversa.

Experimente: um ajudante para revisar os textos

Na aba Code, clique em + New. Na linha abaixo da caixa de mensagem, escolha Local e a pasta da sua página. Antes da primeira mensagem, escolha Manual no seletor de modo, na mesma linha.

1. Antes de pedir, clique no anel de uso, ao lado do seletor de modelo, e anote quanto do contexto a conversa já ocupou, como na Aula 07.
2. Escreva na caixa de mensagem:

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, abra ⋮ → Background tasks e clique nele para ver o que ele está lendo. 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. Clique no anel de uso 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 anel de uso 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". O app mostra o diff de cada mudança: leia e aceite. Confira a página no painel Browser e, se ficou bom, peça "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. Escreva na caixa de mensagem:

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 arquivo novo e aceite só 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 uma conversa nova. 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. Clique em + New e confira, na linha abaixo da caixa de mensagem, a pasta da página e o Manual. Na conversa nova, peça:

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

Enquanto ele trabalha, o revisor-de-textos aparece em ⋮ → Background tasks. Se nem na conversa nova o Claude achar o ajudante, feche o app e abra de novo. 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 conversa nova.

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 e as skills pré-carregadas. 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 app e o terminal usam as mesmas pastas. 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.

Para ver o arquivo, clique no caminho dele na conversa: ele abre no painel de arquivos, e o que você digitar ali é salvo sozinho. 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. O caso que pede reiniciar é o primeiro arquivo numa pasta agents que não existia no começo da sessão.

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, também nas sessões do app no seu computador: o Claude pode abrir forks sozinho, e os ajudantes que ele chama não fazem a conversa esperar. Para o Claude poder esperar um ajudante, desligue o modo fork com CLAUDE_CODE_FORK_SUBAGENT=0 no bloco env do settings.json; para barrar só os forks, "Agent(fork)" no permissions.deny. No terminal, você mesmo abre um fork com /subtask <tarefa>.

Chamar pelo nome

• Em linguagem natural: "Use o revisor-de-textos para revisar a página." O Claude decide se delega. Se ele fizer o trabalho sozinho, seja mais direto: "Use o subagente revisor-de-textos para isso."
• No terminal, dá para garantir com @agent-revisor-de-textos e abrir uma sessão inteira como o ajudante, com claude --agent revisor-de-textos. O claude --agent é só do terminal.

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

No terminal, 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/. No app, o caminho é o mesmo: pedir ao Claude.

Quer ir mais fundo? Veja a página de subagentes da documentação oficial (em inglês) e, para o painel do app, a seção Watch background tasks.

Na prática

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

1. Na aba Code, clique em + New. Na linha abaixo da caixa de mensagem, escolha Local e a pasta da sua página. Antes da primeira mensagem, escolha Manual no seletor de modo, na mesma linha.
2. Clique no anel de uso, ao lado do seletor de modelo, e anote quanto do contexto a conversa já ocupou.
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". Enquanto ele trabalha, abra ⋮ → Background tasks e clique nele.
4. Quando a lista chegar, clique no anel de uso de novo e compare. Está pronto quando a lista aparece e o anel quase não mudou.
5. Peça "corrija os erros da lista", aceite cada mudança, confira no painel Browser 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 aceite a escrita na pasta .claude. Clique em + New, confira a pasta e o Manual 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 app, aparecem em ⋮ → Background tasks, e um clique mostra o que cada um está fazendo.
• 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, abra uma conversa nova, com + New.

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