📖 O que é o "Guide"
O termo "Subagente Claude Code Guide" que circula nos times normalmente se refere a uma de duas coisas: (1) a página oficial de documentação sobre subagentes; ou (2) um subagente interno que o time cria pra ensinar Claude a usar os padrões dessa documentação.
📘 Sentido 1 — A doc
- • Página em docs.anthropic.com
- • Cobre subagentes built-in
- • Mostra formato AGENT.md completo
- • Quickstart de subagente customizado
- • Padrões de trabalho oficiais
🤖 Sentido 2 — O clone
- • Subagente que o time mantém no repo
- • Carrega a doc como contexto
- • "Pergunta pro Guide" vira hábito do time
- • Atualizado quando a doc muda
- • Vive em
.claude/agents/guide.md
💡 Dica prática
Em sala: deixe claro que "o Guide" não é uma feature plug-and-play. É um padrão cultural — o time decide adotar a doc oficial como referência única e (opcionalmente) cria um subagente que materialize isso.
🔗 Documentação canônica
A única URL que você precisa decorar: docs.anthropic.com/en/docs/claude-code/sub-agents. Tudo o resto se deriva dela ou complementa ela.
📚 Mapa de referências oficiais
# Doc canônica (subagentes Claude Code)
https://docs.anthropic.com/en/docs/claude-code/sub-agents
# Auto Mode e handoffs multi-agente (engineering blog)
https://www.anthropic.com/engineering/claude-code-auto-mode
# Webinar avançado (PDF)
resources.anthropic.com/.../Claude Code Advanced Patterns
_ Subagents, MCP, and Scaling to Real Codebases.pdf
# Case de paralelização extrema
https://www.anthropic.com/engineering/building-c-compiler
# Claude Agent SDK (construir agentes via API)
https://www.anthropic.com/engineering/
building-agents-with-the-claude-agent-sdkA doc canônica documenta: built-ins (Explore, Plan, general-purpose), AGENT.md completo, fork mode, exemplos prontos.
Built-ins documentados
Explore e Plan pulam CLAUDE.md e git status do pai pra ficar leves. general-purpose é o fallback.
AGENT.md com frontmatter
Campos: name, description, model, tools, disallowedTools. denylist é aplicada antes do allowlist.
Escopo
.claude/agents/ (projeto) ou ~/.claude/agents/ (usuário). Escaneados recursivamente. Nomes duplicados: mantém um e descarta o outro sem aviso.
Memória persistente
Três escopos: user, project, local. Recomendado: project como padrão.
🆚 Diferença pra Agent SDK
Confusão clássica: subagentes Claude Code e Claude Agent SDK resolvem problemas diferentes.
| Aspecto | Subagentes Claude Code | Claude Agent SDK |
|---|---|---|
| Onde roda | Dentro do CLI Claude Code | Sua aplicação (API) |
| Forma de uso | AGENT.md + delegação automática | Código (SDK chama API) |
| Quem chama | Claude (orchestrator) | Você no seu programa |
| Caso típico | Dev solo escalando sessão | Produto em produção com agentes |
| Paralelização | "Em paralelo, faça X e Y" | Suporte nativo no SDK |
🧭 Regra de bolso
Vai usar agente dentro de uma sessão Claude Code? Subagente normal (AGENT.md). Vai colocar agente num produto que outros usam? Agent SDK. Os dois compartilham conceitos (contexto isolado, paralelização) mas vivem em camadas diferentes.
⚖️ Guide vs subagente custom
Quando vale ter um "Guide interno" e quando você só precisa de subagentes customizados normais?
✓ Vale criar Guide interno quando
- • Time tem 5+ pessoas criando subagentes
- • Há padrões internos (naming, escopo, tools) que se repetem
- • Você quer que novato pergunte "como faço X agente" sem ler doc inteira
- • Há decisões de arquitetura específicas do projeto
✗ NÃO vale Guide interno quando
- • Você é o único dev no projeto
- • Vocês têm 2 subagentes simples e estável
- • Padrões internos ainda não existem (criaria fake authority)
- • Doc oficial já cobre tudo que vocês usam
📐 Alternativa leve: CLAUDE.md
Antes de criar um subagente Guide, considere se um bloco em CLAUDE.md resolve.
Convenções de subagentes do projeto cabem perfeitamente em CLAUDE.md raiz — sem precisar de
AGENT.md dedicado.
Suba pra subagente quando o conteúdo cresce e você quer invocação sob demanda (não contexto que entra toda hora).
📐 Padrões oficiais
O que a doc oficial e o webinar "Advanced Patterns" recomendam — sem inventar:
Contexto isolado por subagente
Orchestrator delega e recebe só resumo — não o contexto inteiro do subagente. Preserva contexto do principal.
Paralelização por instrução natural
"Pesquise auth, database e API em paralelo usando subagentes separados". Claude spawna múltiplos simultâneos.
Allowlist mínima de tools
Subagente de pesquisa não precisa de Write/Edit. Listar só o necessário reduz superfície de erro.
Description que dispara delegação
Como skills, o description é o gatilho. "Use quando..." é o padrão da Anthropic.
Handoffs com classifiers
Auto Mode roda classifiers nos dois lados do handoff (delegação e retorno) — detecta prompt injection mid-run. Resultados suspeitos recebem aviso prepended ao invés de descarte.
Background opcional
background: true roda subagente em background. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 desabilita. Em fork mode, todo spawn vai pra background.
✓ Padrões que escalam
- • Subagente "pesquisador" sem permissões de escrita
- • Subagente "executor" com escrita mas escopo apertado
- • Memória
projectpra contexto durável - • Built-ins (
Explore,Plan) pra tarefas comuns
✗ Padrões que não escalam
- • Subagente único "faz tudo" — pior dos dois mundos
- • Allowlist com tudo liberado por preguiça
- • Nomes ambíguos que conflitam entre user e project
- • Descrições genéricas tipo "ajuda com código"
🛠️ Criar um clone interno
Receita pragmática pra montar um "Guide interno" do time. Cabe em um AGENT.md de 30 linhas.
📄 Esqueleto de .claude/agents/guide.md
---
name: guide
description: Consultor interno sobre como criar e operar
subagentes neste projeto. Use quando alguem perguntar
"como faco um subagente para X", "qual padrao usar",
"onde fica o AGENT.md", ou quando estiver decidindo
entre subagente custom vs built-in.
model: sonnet
tools: Read, Grep, Glob
---
# Guide interno — subagentes deste projeto
## Referencias oficiais
- docs.anthropic.com/en/docs/claude-code/sub-agents
- Webinar "Advanced Patterns" (PDF em resources.anthropic.com)
## Convencoes deste projeto
- Subagentes vivem em .claude/agents/
- Nome em kebab-case, sem prefixo
- description sempre comeca com "Use quando..."
- tools: sempre allowlist explicita, nunca em branco
## Built-ins preferidos
- Explore: descoberta de codigo
- Plan: plano antes de implementar
- general-purpose: fallback
## Quando criar custom vs reusar built-in
- Reuse built-in se a tarefa cabe nele
- Custom apenas quando ha padrao repetido do projeto💡 Dica prática
Não tente "absorver toda a doc" no Guide. Faça ele ser portal pra doc oficial + camada fina de convenções do projeto. Quando a doc canônica muda, você só atualiza a parte de convenções — não reescreve nada da Anthropic.
🚀 Próximo passo (em sala)
Termine T4 perguntando: "qual é o primeiro subagente que vocês vão escrever amanhã?" Anote no chat. Esse compromisso público vira métrica de adoção — assunto da Trilha 5.
📋 Resumo do Módulo
Próxima Trilha:
T5 — 🏁 Fechamento e Continuidade (1-2-3, jogo infinito, follow-up, métricas)