🔬 Anatomia de um subagente (system prompt, ferramentas, saída)
Um arquivo de subagente tem quatro partes: o frontmatter (name/description), o system prompt (quem ele é), as ferramentas permitidas e o formato de saída esperado. Definir bem essas quatro partes é o que separa um agente útil de um que devolve texto solto.
// .claude/agents/pesquisador-empresa.md
--- name: pesquisador-empresa description: Use para pesquisar uma empresa e devolver um CompanyContext estruturado (setor, stack, dores, IA). tools: WebSearch, Read --- És um pesquisador de empresas. Recebes nome + descrição, pesquisas e devolves SÓ um JSON CompanyContext. Não escreves o entregável; só coletas o contexto.
💡 Dica prática
O segredo é restringir as ferramentas e fixar a saída. Um agente com acesso a tudo e formato livre vira imprevisível; um agente com poucas ferramentas e um schema de saída é confiável e fácil de encadear.
name + description
quem ele é
só o necessário
formato fixo
🏢 O agente pesquisador-empresa (coleta contexto estruturado)
Ele recebe nome + descrição, pesquisa e devolve um CompanyContext: setor, stack, dores, concorrentes e iniciativas de IA. É a Fase 1 da Fábrica encarnada num trabalhador — isola a pesquisa pesada e devolve contexto limpo, sem poluir a conversa principal.
Recebe a empresa
O agente principal passa nome + descrição curta. Nada mais — o subagente começa do zero, num contexto isolado.
Pesquisa na web
Usa WebSearch para levantar setor, stack técnico, dores por área e movimentos de IA. Aqui é onde o custo e o ruído ficam contidos.
Estrutura em CompanyContext
Transforma o que achou num JSON com campos fixos. Não é resumo solto — é um objeto previsível, pronto para o próximo agente.
Devolve ao pai
Entrega só o CompanyContext ao agente principal. Toda a pesquisa pesada fica fora — o orquestrador recebe um pacote enxuto.
💡 Por que isolar
Pesquisa enche a janela de contexto de lixo. Ao rodar num subagente, só o resultado limpo volta — o agente principal nunca vê as 30 páginas que foram lidas. Esse é o ganho central de Fase 1 como trabalhador.
nome + descrição
pesquisa isolada
CompanyContext
contexto limpo
✍️ O agente redator-estrategia (rascunha entregável)
Ele recebe o CompanyContext mais um framework (por exemplo, quick wins) e escreve o entregável em Markdown, pronto para a skill gerar-entregavel (do 3.3) formatar. A regra de ouro: pesquisa e redação são trabalhos diferentes — cada agente faz um, e faz bem.
✓ Um agente, um papel
- ✓Cada agente pesquisa OU escreve — nunca os dois
- ✓Saída previsível: dá pra confiar no formato
- ✓Fácil testar e melhorar uma peça por vez
✗ Agente faz-tudo
- ✗Pesquisa + escreve + formata na mesma chamada
- ✗Contexto estoura — a janela enche de ruído
- ✗Difícil depurar: tudo falha junto, sem culpado
💡 Separar para melhorar
Quando pesquisa e redação são agentes distintos, você melhora o redator sem mexer no pesquisador — e vice-versa. Cada um tem um único motivo para mudar. É a mesma lógica de funções pequenas, aplicada a agentes.
contexto + framework
escreve o rascunho
Markdown
um papel por agente
🧾 Saída estruturada (schema, JSON confiável)
Peça ao agente para devolver JSON num formato fixo — um schema — como os modelos reais CompanyInput e ResearchOutput da Fábrica. Saída estruturada é exatamente o que permite ENCADEAR agentes; texto solto quebra o pipeline na primeira junção.
// schema CompanyContext (JSON de saída)
{
"company_name": "Stripe",
"sector": "Pagamentos B2B / fintech",
"tech_stack": ["Ruby", "Go", "AWS"],
"pain_points": ["onboarding lento", "fraude"],
"competitors": ["Adyen", "PayPal"],
"ai_initiatives": ["Radar (antifraude)"],
"maturity_1_5": 4
}
📊 Por que JSON e não texto
- •Campos com nome fixo: o próximo agente sabe onde buscar cada dado.
- •Validável: dá pra checar se
maturity_1_5veio entre 1 e 5. - •Encadeável: o JSON entra direto no
redator-estrategiasem parsing frágil.
💡 Schema é contrato
Um schema é um contrato — campos previsíveis encadeiam agentes. Definiu os campos uma vez, e qualquer agente que produza ou consuma esse objeto vira plugável. É assim que peças soltas viram pipeline.
formato fixo
campos previsíveis
dá pra checar
agente → agente
🎛️ Orquestrar skill + agentes juntos
O agente principal chama o pesquisador-empresa, passa o CompanyContext ao redator-estrategia e então usa a skill gerar-entregavel para produzir o arquivo. É a Fábrica em miniatura: pesquisa → redação → documento.
// o que você pede ao Claude Code
1. pesquisador-empresa("Stripe") -> CompanyContext
2. redator-estrategia(context, framework="quick-wins") -> Markdown
3. skill gerar-entregavel(markdown, "pptx") -> deck.pptx
Isso é o mesmo encadeamento dos modelos reais da arquitetura: CompanyInput → ResearchOutput → SynthesisOutput → GenerationResult. Cada seta é um trabalhador entregando um objeto estruturado ao próximo. O orquestrador só costura as peças.
🧩 Como a Fábrica cresce (Extension Points)
- •Novo entregável: um novo prompt + registrá-lo, e o orquestrador já o inclui.
- •Novo provedor: um novo client com
generate()— troca o motor sem mexer no resto. - •Novo formato: um novo generator plugado ao orquestrador de geração.
💡 Peças plugáveis
Porque cada etapa é um objeto estruturado, você pluga uma peça nova sem reescrever as outras. Adicionar um entregável, um provedor ou um formato é encaixar — não reformar. Foi assim que projetou: orquestrar, não amarrar.
pesquisador-empresa
redator-estrategia
gerar-entregavel
o orquestrador
⚡ Quando paralelizar agentes
Dispare vários subagentes de uma vez quando as tarefas são independentes (sem estado compartilhado) — por exemplo, pesquisar 3 empresas em paralelo. Se uma depende da saída da outra, é sequencial. Saber a diferença evita bugs sutis e ganha tempo onde dá.
✓ Paralelize quando
- ✓As tarefas são independentes entre si
- ✓Não há estado compartilhado durante o trabalho
- ✓Só no fim você junta os resultados
✗ Mantenha sequencial
- ✗Uma tarefa depende da saída da outra
- ✗Há estado compartilhado sendo alterado
- ✗A ordem importa para o resultado final
💡 Teste rápido
Pergunte: "o agente B precisa do que o agente A produziu?". Se sim, sequencial. Se não, paralelo. No nosso caso, redator-estrategia depende do pesquisador-empresa (sequencial), mas pesquisar 3 empresas é paralelo.
tarefas independentes
uma depende da outra
estado compartilhado
tempo sem bugs
✅ Resumo do módulo
🎯 Missão 3.4 — pesquisador-empresa no ar
Coloque o primeiro trabalhador da Fábrica em pé:
- Criar
.claude/agents/pesquisador-empresa.md(system prompt + tools + saída). - Fixar a saída como o schema CompanyContext.
- Rodar para 1 empresa real.
- Conferir que o JSON volta preenchido e encadeável.
Sucesso: o agente pesquisador-empresa retorna um CompanyContext preenchido. O que você ganhou: o primeiro trabalhador da Fábrica — pronto para alimentar o redator e a skill de documentos.
Próximo módulo:
Trilha 4 — A Fábrica (pesquisa ao vivo, os 15 prompts, orquestração ponta a ponta)