📖 Glossario vivo
Termos centrais desta trilha. Volte aqui sempre que precisar.
O que sao subagentes
Imagine assim: voce e um gerente de projeto. Em vez de fazer tudo sozinho, voce delega tarefas especificas para membros da equipe, cada um com seu proprio espaco de trabalho. Quando terminam, te entregam o resultado. E exatamente isso que subagentes fazem.
Ate agora voce usou o Claude Code como um unico agente, conversando diretamente com ele. Mas o Claude Code tem uma capacidade poderosa: ele pode lancar outros agentes para executar tarefas em paralelo. Esses agentes filhos sao chamados de subagentes.
Cada subagente recebe uma instrucao especifica, trabalha de forma independente (com seu proprio contexto e ferramentas), e retorna o resultado ao agente pai quando termina. O pai nao precisa ficar esperando um subagente terminar para lancar outro. Isso permite que voce multiplique a capacidade de trabalho do Claude Code sem aumentar a complexidade do contexto principal.
Em 1 frase: subagentes sao instancias independentes do Claude Code que o agente principal lanca para fazer trabalho em paralelo.
A Task tool
A Task tool e o mecanismo que o Claude Code usa internamente para criar subagentes. Quando o Claude decide que precisa delegar uma tarefa, ele invoca a Task tool passando uma descricao do que o subagente deve fazer. O subagente recebe essa instrucao, executa o trabalho e retorna o resultado textual ao pai.
Na pratica, voce nao precisa chamar a Task tool explicitamente. Basta instruir o Claude com algo como "faca essas tres coisas em paralelo" ou "crie um subagente para analisar os testes enquanto voce refatora o codigo". O Claude entende e orquestra automaticamente. O ponto importante e que cada Task cria um novo contexto, com seu proprio CLAUDE.md carregado, e nao compartilha estado em memoria com o pai.
Como funciona por dentro
1. O agente pai decide delegar e invoca Task(prompt="...")
2. O sistema cria uma nova sessao do Claude Code com o prompt fornecido
3. O subagente executa, usando suas proprias ferramentas (Read, Edit, Bash...)
4. Ao terminar, o resultado textual volta ao pai como retorno da Task
5. O pai continua seu trabalho com essa informacao
Em 1 frase: a Task tool cria um subagente com prompt proprio, executa isoladamente e devolve o resultado ao pai.
Tipos de agente disponiveis
Nem todo subagente precisa ter permissao total. O Claude Code permite lancar agentes com diferentes niveis de acesso, seguindo o principio do menor privilegio: dar apenas as permissoes necessarias para a tarefa. Isso reduz risco e evita que um subagente mude algo que nao devia.
Read-only
So le arquivos e analisa. Nao edita nada. Ideal para: analise de codebase, busca de padroes, auditoria.
Full access
Le, edita arquivos e roda comandos. O padrao para tarefas que precisam modificar o codigo.
Background
Roda em segundo plano enquanto o pai continua. Ideal para tarefas longas como builds ou test suites.
Em 1 frase: escolha o tipo de agente pelo nivel de permissao necessario: leitura, escrita completa ou background.
Comunicacao pai-filho
A comunicacao entre pai e filho segue um modelo simples: o pai envia uma instrucao (o prompt da Task) e o filho retorna um resultado textual. Nao ha estado compartilhado em memoria entre eles. Se o filho precisa de informacao do codebase, ele proprio a busca usando suas ferramentas.
O ponto chave: o prompt da Task precisa ser completo e auto-contido. O subagente nao tem acesso ao historico da conversa do pai. Se voce quer que ele siga um padrao especifico, inclua isso no prompt. Pense como se estivesse escrevendo uma instrucao para um colega que acabou de chegar no projeto.
Erro comum
Assumir que o subagente "sabe" o que o pai discutiu antes. O subagente comeca do zero. Se a informacao e critica, passe-a explicitamente no prompt da Task.
Em 1 frase: o pai manda instrucao, o filho devolve texto; nao ha memoria compartilhada entre eles.
Isolamento e worktrees
Quando dois agentes editam os mesmos arquivos ao mesmo tempo, surgem conflitos. A solucao e o isolamento via worktrees. Um git worktree e um diretorio de trabalho extra ligado ao mesmo repositorio, cada um com sua branch. Cada subagente trabalha num worktree proprio, sem pisar no espaco do outro.
O Claude Code pode criar worktrees automaticamente ao lancar subagentes. No final, as branches dos worktrees sao mergeadas de volta na branch principal. E como se cada membro da equipe tivesse sua propria copia do projeto para trabalhar, e depois juntassem tudo.
Em 1 frase: worktrees dao a cada subagente seu proprio espaco de trabalho isolado, evitando conflitos de arquivo.
Quando usar vs nao usar
Subagentes nao sao de graca. Cada um consome tokens para carregar o contexto (CLAUDE.md, ferramentas, etc.) e tem um overhead de inicializacao. Para tarefas simples que o agente principal resolve em segundos, lancar um subagente e desperdicio. A regra pratica: use subagentes quando a tarefa e independente, substancial (mais de 30 segundos de trabalho) e paralelizavel.
Use subagentes quando
- - Tarefas sao independentes entre si
- - Cada tarefa leva mais de 30 segundos
- - Voce quer proteger o contexto do pai
- - Precisa editar arquivos diferentes em paralelo
- - Quer especializar agentes (testes vs docs vs lint)
Nao use subagentes quando
- - A tarefa e trivial (renomear uma variavel)
- - As tarefas dependem do resultado uma da outra
- - O contexto ja esta quase no limite
- - Voce precisa de interacao em tempo real
- - O custo em tokens nao se justifica
Em 1 frase: subagentes valem para tarefas independentes e substanciais; nao para tudo.
🧾 Resumo do Modulo
Proximo modulo:
4.2 — Paralelismo Real: lancando multiplos agents e coletando resultados na pratica.