🪪 Anatomia de um subagent
Todo subagent precisa de 5 atributos definidos antes de ser criado. Sem eles, ele falha ou se sobrepõe com outros agentes. A identidade do subagent é seu AGENTS.md dedicado — não o AGENTS.md do projeto geral.
🎯 Os 5 atributos obrigatórios
- 1. Função (1 frase) — "Analisa métricas financeiras e produz relatórios de KPI." Deve caber em uma linha.
- 2. Escopo de dados — Quais pastas, arquivos e bases de dados ele pode acessar. Nada além disso.
- 3. Ferramentas (MCPs) — Quais tools ele tem: SQL, Python, browser, etc. Sem acesso desnecessário.
- 4. Silver Platters de entrada — Quais resumos pré-processados ele lê para ter contexto sem custo.
- 5. SLA + formato de output — Tempo máximo de resposta e o formato exato do que entrega.
💡 Princípio do mínimo necessário
Cada subagent deve ter apenas o acesso mínimo necessário para sua função. CFO Bot não precisa de acesso ao código. CMO Bot não precisa de dados financeiros brutos. Escopo estreito = menos erros e mais segurança.
💰 CFO Bot — especialista financeiro
O CFO Bot é o especialista financeiro da equipe. Ele lê os Silver Platters de /finance, analisa margens, fluxo de caixa e KPIs, e produz relatórios estruturados. Domain isolation: ele nunca toca dados de marketing ou operações.
Configuração típica do CFO Bot
# AGENTS.md — CFO Bot
## Função
Análise financeira: margens, fluxo de caixa,
alertas de KPI e projeções de curto prazo.
## Escopo de dados
- /finance/silver-platters/ (leitura)
- /finance/raw/ (leitura)
- NUNCA: /marketing/, /ops/, /code/
## MCPs disponíveis
- sql-query (read-only, banco financeiro)
- python-calc (cálculos e gráficos)
## SLA
- Relatório mensal: 120s máximo
- Alerta de KPI: 30s máximo
## Output format
JSON estruturado + texto executivo em pt-BRMarco usa CFO Bot
Marco (e-commerce) configura CFO Bot para rodar toda segunda-feira às 8h. O bot lê os dados da semana anterior, produz resumo de margem por categoria, destaca as 3 categorias com pior desempenho e já sugere ação. Marco recebe o briefing antes da reunião de gestão.
📣 CMO Bot — especialista de marketing
O CMO Bot monitora a voz do cliente, tendências de mercado e performance de conteúdo. Ele lê Silver Platters de /marketing e /customer-feedback, produz análise de sentimento, identifica padrões de churn e sugere experimentos.
Domínio de conhecimento do CMO Bot
- Voz do cliente: analisa tickets de suporte, reviews, NPS para padrões recorrentes.
- Performance de conteúdo: métricas de engajamento, taxas de conversão por canal.
- Competidores: monitora movimentos de mercado nos Silver Platters de inteligência competitiva.
- Experimentos: sugere A/B tests com hipótese, métrica e critério de sucesso.
💡 Sally configura CMO Bot
Sally (consultora) usa CMO Bot para auditar os clientes dela. Antes de cada reunião mensal, o bot analisa os dados de marketing do cliente e produz um "relatório de saúde" com 3-5 achados prioritários. Sally chega na reunião já com hipóteses validadas — não começa do zero.
⚙️ Ops Bot — especialista de operações
O Ops Bot monitora processos, SLAs, gargalos e eficiência operacional. Ele lê dados de /ops e Silver Platters de processos, identifica anomalias, calcula capacidade e produz planos de contingência.
Casos de uso do Ops Bot
- •Monitoramento de SLA de fornecedores
- •Detecção de gargalos em processos
- •Planejamento de capacidade
- •Alertas de anomalia em tempo real
- •Relatórios de eficiência semanal
Integrações típicas
- •Jira / Linear (tickets e sprints)
- •Notion / Confluence (processos)
- •Slack (alertas em tempo real)
- •Google Sheets (dashboards)
- •n8n (automação de ações)
🔧 Implementação no Claude Code
No Claude Code, subagents são implementados como instâncias separadas com AGENTS.md dedicados por diretório. O orquestrador inicia subagentes via `Task` tool — cada um com seu próprio contexto limpo.
Estrutura de diretórios por agente
projeto/
├── AGENTS.md # Orquestrador CoS
├── .claude/
│ └── settings.json # Permissões do orquestrador
├── agents/
│ ├── cfo-bot/
│ │ ├── AGENTS.md # Identidade do CFO Bot
│ │ └── prompts/ # Templates de análise
│ ├── cmo-bot/
│ │ └── AGENTS.md
│ └── ops-bot/
│ └── AGENTS.md
└── silver-platters/ # Contexto compartilhado (leitura)Como o orquestrador invoca subagents
O CoS usa a ferramenta Task do Claude Code para spawnar subagentes. Cada Task recebe: contexto específico, instrução atômica, formato de output esperado e timeout máximo.
Obs: Task tool está disponível no Claude Code com permissão de subagent habilitada no settings.json.
🧪 Avaliação por subagent
Cada subagent precisa de seu próprio eval — não basta avaliar o sistema como um todo. Eval por papel isola onde o sistema está falhando: é o CFO Bot que errou nos números, ou o CoS que deu contexto errado para ele?
Framework de eval por subagent
- Isolamento: Testa cada subagent individualmente com inputs controlados.
- Métricas por papel: CFO Bot = precisão numérica. CMO Bot = relevância de insights. Ops Bot = detecção de anomalia.
- Regressão: quando o sistema piora, qual subagent causou a piora?
- Benchmark de latência: cada subagent tem seu SLA — mede se está cumprindo.
⚠️ Erro comum: eval só no output final
Sana avaliava apenas o relatório final do sistema. Quando os números começaram a errar, ela não sabia se o problema era o CFO Bot (análise errada) ou o CoS (síntese errada). Sem eval por subagent, debugging é investigação às cegas.
📋 Resumo do Módulo
Próximo Módulo:
4.4 — A2A: o protocolo agent-to-agent do Google para comunicação entre agentes