Seu Primeiro Subagente no Claude Code

Do CLAUDE.md ao Subagente Especializado em 30 Minutos

Tipo: Tutorial · Autor: Aura Research Board · Data: Maio 2026 · Nível: Intermediário, com Tier 0 concluído · Aura Company

O Que Você Vai Construir

Um subagente especializado (por exemplo, um revisor de testes ou um explorador de codebase) invocável dentro do Claude Code.
Um CLAUDE.md que codifica as convenções do projeto, que é context engineering na prática.
O entendimento de quando delegar a um subagente e quando resolver no agente principal.
Para líderes que vão só ler: isolamento de contexto e escopo de ferramentas de um subagente são, na prática, decisões de governança e de custo, não apenas técnicas.

Pré-requisitos

Claude Code instalado e atualizado (no Opus 4.7, note que o padrão é criar menos subagentes, e aqui criamos um explícito).
Um repositório de exemplo, de preferência um projeto pequeno com testes.
Os módulos M0.5 - Gerenciamento de Contexto e M0.6 - Setup Profissional Cursor e Claude.

Conceito: o Que É um Subagente

Um subagente é um agente com escopo, instruções e, opcionalmente, ferramentas próprias, invocado pelo agente principal para uma subtarefa. Os motivos para usar são três: isolar contexto (não poluir a janela principal, o que liga com o context rot de Context Engineering em Escala - Memoria e Context Rot), especializar e paralelizar. Quando não usar: tarefas curtas e lineares, em que o subagente só adiciona custo de coordenação.

Passo 1: Criar o CLAUDE.md

A estrutura mínima cobre stack, convenções de nomenclatura, estrutura de pastas, regras de teste e decisões arquiteturais. O princípio, vindo do whitepaper de context engineering, é que o melhor contexto é o que já está lá quando o modelo precisa, sem inclusão manual.

Passo 2: Definir o Subagente

Defina a descrição (quando acionar), o prompt de sistema e o escopo de ferramentas. A boa prática é dar uma descrição clara do gatilho e o menor escopo de ferramentas possível, aplicando o princípio do menor privilégio, que liga com Governanca de Agentes em Producao.

Passo 3: Invocar e Observar

Rode uma tarefa que dispare o subagente e observe o trace, que no Opus 4.7 traz mais updates de progresso. Acompanhar o trace é o que ensina onde o subagente acerta e onde erra.

Passo 4: Iterar com Verificação

Adicione um critério de verificação, por exemplo, o subagente deve rodar os testes e reportar o resultado. Isso introduz a ideia de feedback loop, que é a base da harness engineering (ver Harness Engineering - O Software ao Redor do Modelo).

Erros Comuns

Subagente com escopo amplo demais, que acaba virando o agente principal.
CLAUDE.md genérico demais, que não muda o comportamento.
Esquecer de limitar ferramentas, o que vira risco de segurança e de custo.

Próximos Passos

Evolua para múltiplos subagentes coordenados em Padroes de Orquestracao Multi-Agente e empacote conhecimento como Skill, tema que aparece em A Era dos Protocolos - MCP A2A e a Agentic AI Foundation.

Conexões no Currículo

Módulos relacionados: M0.5 - Gerenciamento de Contexto · M0.6 - Setup Profissional Cursor e Claude

Disciplinas: D3 - Engenharia de Agentes