O pequeno ajudante

O que é e porque importa

Um subagente é um ajudante que o Claude lança para um trabalho concreto. Tem um contexto só dele: abre ficheiros, procura, lê, e no fim só te devolve o resumo. Todo o material que leu para lá chegar fica lá e não acaba na tua conversa.

Porque importa: a conversa principal tem um espaço limitado. Se o Claude abre cinquenta ficheiros para perceber onde está o login, todo esse texto ocupa o chat e, passado um bocado, o Claude tem mais dificuldade em seguir o fio. Com um subagente, a pesquisa fica a cargo do ajudante e a ti chega uma resposta de poucas linhas.

«Pequeno» aqui quer dizer que faz uma só tarefa, não que seja menos capaz: normalmente um subagente usa o mesmo modelo da conversa principal. Nas sessões normais costuma trabalhar em segundo plano, e entretanto tu continuas a falar com o Claude.

O Claude Code já traz alguns prontos. O que mais uso é o Explore: serve para procurar e perceber o código e é só de leitura, ou seja, não pode escrever nem alterar ficheiros. Depois há os que crias tu, que vemos mais abaixo.

1. Procurar sem encher o chat

É o caso mais simples. Preciso de perceber onde está uma coisa no projeto e não me interessa ver todos os ficheiros que o Claude abre para a encontrar.

Usa um subagente Explore para encontrar onde é tratado o login. Diz-me só os ficheiros e as linhas.

A segunda frase conta tanto como a primeira. «Diz-me só os ficheiros e as linhas» diz ao ajudante o que tem de trazer. Se não o disseres, volta-te um resumo comprido que enche o chat na mesma.

Lembra-te de que o Explore não vê a vossa conversa e arranca também sem o ficheiro CLAUDE.md do projeto, para ser rápido. Por isso, põe na frase o que ele precisa: o que procuras, em que parte da app e o que queres de volta.

2. Três trabalhos ao mesmo tempo

Quando tenho vários trabalhos que não dependem uns dos outros, lanço-os em paralelo. Cada ajudante tem o seu contexto e a sua tarefa, e no fim o Claude junta os resultados.

Lança três subagentes em paralelo: um procura onde é tratado o login, outro lê os logs do último erro e diz-me a causa, e outro escreve os testes para a página de preços. Quando acabarem, faz-me um resumo dos três.

Funciona porque os três trabalhos não se cruzam: encontrar o login não é preciso para ler os logs, e nenhum dos dois mexe nos testes dos preços. Se o segundo trabalho precisa do resultado do primeiro, não é um trabalho em paralelo: fá-lo depois.

3. Ctrl+B e /tasks

Se um trabalho está a demorar e te bloqueia, tipo um comando que está a correr há minutos, carrega em Ctrl+B: passa para segundo plano e tu continuas a escrever. O Ctrl+B funciona tanto com comandos como com ajudantes. Se usas tmux, carrega duas vezes.

Para veres quem está a trabalhar, escreve:

/tasks

Mostra-te o trabalho em segundo plano da sessão: os comandos que estão a correr e os subagentes, incluindo os que acabaram de terminar. Daí podes abrir o trabalho de um ajudante e ler o que fez, ou pará-lo se foi pelo caminho errado.

4. Um ajudante fixo

Se repetes um trabalho muitas vezes, compensa ter um ajudante fixo. É um ficheiro na pasta .claude/agents do projeto: em cima estão o nome, uma descrição de quando o usar e as ferramentas que pode usar, e por baixo as instruções escritas em palavras normais. Não precisas de o escrever à mão: pedes ao Claude.

Cria-me um subagente em .claude/agents que revê o código sem alterar nada, e chama-lhe code-reviewer.

O resultado é parecido com isto:

---
name: code-reviewer
description: Revê o código e assinala os problemas. Não altera nenhum ficheiro.
tools: Read, Grep, Glob
---

És um revisor de código. Lê as alterações que te indico e procura bugs, casos não tratados e partes pouco claras. Para cada problema diz-me o ficheiro, a linha e como o corrigias. Não alteres nada.

A linha que importa é tools: são as ferramentas que o ajudante pode usar. A um revisor bastam as de ler e procurar, ou seja, Read, Grep e Glob. Não devem lá estar Write nem Edit, nem Bash, porque também se podem alterar ficheiros a partir do terminal. Se não tens a certeza, pergunta:

Abre o ficheiro do subagente code-reviewer e diz-me que ferramentas pode usar. Se houver alguma coisa que lhe permita alterar ficheiros, tira-a.

Depois usas assim, quando acabaste uma parte do trabalho:

Põe o subagente code-reviewer a verificar as últimas alterações.

No ficheiro também podes acrescentar uma linha model para escolher o modelo: haiku para trabalhos simples e rápidos, sonnet ou opus para os mais exigentes, inherit para usar o mesmo da conversa.

O ficheiro em .claude/agents vale para esse projeto. Se o puseres em ~/.claude/agents, tens-no em todos os teus projetos. Também existe o comando /agents, mas o mais simples continua a ser pedir ao Claude ou abrir o ficheiro.

5. Quando não os lanço

• Trabalhos pequenos: mudar um texto, uma cor, uma linha. Um ajudante começa do zero e primeiro tem de perceber o projeto: demora mais do que fazer diretamente.
• Trabalhos que mexem nos mesmos ficheiros: dois ajudantes no mesmo ficheiro atropelam-se. Fá-los um a seguir ao outro, ou cada um na sua cópia do projeto, os worktrees. Para um ajudante fixo basta acrescentar no ficheiro dele a linha isolation: worktree.
• Quando quero acompanhar cada passo: o ajudante traz-te o resultado no fim. Se tenho de o corrigir a cada passo, fico na conversa principal.
• Quando é preciso tudo o que dissemos: um ajudante como o Explore começa com um contexto limpo e não vê o nosso chat. Tem de ser explicado do zero, por isso explica bem na frase.

Uma regra

Cada ajudante gasta tokens próprios, e contam para os mesmos limites de utilização da conversa principal. Três ajudantes com uma tarefa clara cada um, sim. Dez lançados «só porque sim», não.

Os erros mais comuns

• Lançar um ajudante para uma alteração de uma linha: fá-la diretamente, é mais rápido.
• Escrever uma frase vaga tipo «vê o login»: diz o que procurar, onde, e o que queres de volta.
• Dar como certo que o ajudante sabe o que falaram: ele não vê o chat, por isso põe-lhe o contexto na frase.
• Pôr dois ajudantes nos mesmos ficheiros ao mesmo tempo: põe-nos a trabalhar um a seguir ao outro, ou cada um no seu worktree.
• Confiar num revisor «só de leitura» sem olhar para a linha tools: abre o ficheiro e confirma que não estão lá Write, Edit nem Bash.
• Lançar muitos «só porque sim»: cada um gasta tokens próprios, por isso lança só os que têm uma tarefa clara.

Checklist

• O trabalho é grande o suficiente para valer um ajudante
• A frase diz o que procurar e o que trazer
• O contexto de que precisa está escrito na frase
• Os trabalhos em paralelo não mexem nos mesmos ficheiros
• Sei que com /tasks vejo quem está a trabalhar
• O revisor fixo só tem ferramentas para ler

Perguntas frequentes