🎬O cenário
Projeto grande, 5 módulos principais, zero documentação. O time novo está sofrendo para entrar. Você foi encarregado de documentar. Tentar numa sessão só é receita para context rot: Claude entra com atenção afiada no módulo 1 e termina produzindo texto vago no módulo 5. A saída é dividir em 3 sessões encadeadas, com handoff estruturado entre elas. No fim você terá ARCHITECTURE.md, 5 docs por módulo, CONTRIBUTING.md e CLAUDE.md — e terá gastado ~5× menos que no fluxo ingênuo.
Mapa das 3 sessões
🗺️ Sessão 1, Passo A: Inventário e arquitetura
Objetivo: abrir uma sessão dedicada só a entender o todo. Output único e curto: ARCHITECTURE.md < 80 linhas. Esse arquivo orienta todas as sessões seguintes e vira parte do handoff permanente do projeto.
Prompt pronto para copiar
sessão 1ASessão de inventário. Explore o repo e produza ARCHITECTURE.md com: árvore de pastas (principais), responsabilidade de cada módulo raiz, fluxo principal (uma linha), tecnologias. Máximo 80 linhas.
📥O que esperar da resposta
# ARCHITECTURE.md ## Árvore src/ ├── api/ (HTTP, rotas) ├── auth/ (login, JWT, sessions) ├── billing/ (Stripe, faturas) ├── catalog/ (produtos, busca) └── orders/ (checkout, fulfillment) ## Módulos - api: entrada HTTP, validação, middlewares - auth: autenticação e autorização - billing: integração Stripe e ciclo de faturas - catalog: produtos, categorias, busca full-text - orders: carrinho, checkout, processamento ## Fluxo principal Usuário → api → orders.checkout → billing → db ## Stack Node 20, TypeScript, Fastify, Prisma, PostgreSQL, Stripe, Redis.
💡Por que 80 linhas é o teto
ARCHITECTURE.md precisa caber na memória de quem abrir o projeto pela primeira vez — e no contexto das sessões 2 e 3. Mais que 80 linhas vira ruído. Menos que 40 não entrega informação suficiente. O sweet spot é 60–80 linhas densas.
🗺️ Sessão 1, Passo B: Handoff e /clear
Objetivo: fim limpo da sessão 1. ARCHITECTURE.md é o handoff principal; o prompt de fechamento só confirma que ele está suficiente. Depois, /clear agora, não depois.
Prompt pronto para copiar
sessão 1BProduza handoff estruturado. Vou limpar sessão e abrir nova.
📥O que esperar da resposta
- •Confirmação de que ARCHITECTURE.md foi salvo
- •Lista de 5 módulos identificados (a base da sessão 2)
- •Sugestão explícita: "abra nova sessão lendo apenas ARCHITECTURE.md + lista dos módulos"
- •Nada para ser continuado dentro da mesma sessão
⚠️Faça /clear agora
A tentação é continuar "só mais um passinho" na mesma sessão. Resista. Cada turno adicional depois desse ponto carrega toda a exploração do repo (dezenas de arquivos lidos) para uma tarefa que só precisa de 80 linhas de ARCHITECTURE.md. Sessão 2 começa zero, abre apenas ARCHITECTURE.md, e o contexto fica mínimo do início ao fim.
📖 Sessão 2, Passo A: Docs por módulo (subagentes paralelos)
Objetivo: produzir 5 arquivos docs/[modulo].md em paralelo. Você é orquestrador, não redator. Cada subagente tem sua própria sessão e só devolve o arquivo pronto.
Prompt pronto para copiar
sessão 2ACom base no ARCHITECTURE.md, dispare 5 subagentes em paralelo — um por módulo principal. Cada um produz docs/[modulo].md com: o que faz, como usar, exemplos. Você só orquestra, não escreve.
📥O que esperar da resposta
- •Confirmação de 5 subagentes disparados, um por módulo (api, auth, billing, catalog, orders)
- •À medida que cada um termina: caminho do arquivo criado e tamanho em linhas
- •Resumo final: 5 arquivos em docs/, X linhas totais
- •Você não deve ver a exploração completa de cada módulo no contexto principal — só o resumo
💡Economia real de paralelismo
Em série: cada módulo carrega contexto novo sobre o anterior → 5× o tempo e qualidade caindo. Em paralelo com subagentes: 5 contextos isolados, cada um fresh, tempo de execução ≈ do módulo mais longo. Contexto principal recebe apenas ~5k tokens (os 5 resumos) em vez dos ~50k que viria da série.
📖 Sessão 2, Passo B: Revisão e handoff
Objetivo: 5 subagentes não se falam, então os arquivos podem ter estilos e lacunas diferentes. Uma revisão curta harmoniza. Depois, handoff para sessão 3.
Prompt pronto para copiar
sessão 2BLeia os 5 arquivos e me diga: está consistente? Falta algo? Depois me dê handoff.
📥O que esperar da resposta
Consistência: OK em 4/5. docs/billing.md usa "fatura" enquanto os outros usam "invoice" — padronizo? Lacunas identificadas: - docs/auth.md não tem exemplo de refresh token - docs/catalog.md não cobre busca full-text Handoff: - 5 arquivos em docs/ prontos para sessão 3 - Ajustes menores aplicados inline - Próxima sessão: CONTRIBUTING.md + CLAUDE.md
📘 Sessão 3, Passo A: CONTRIBUTING.md + CLAUDE.md
Objetivo: fechar o onboarding. CONTRIBUTING.md para humanos (setup, testes, PR); CLAUDE.md curto (< 100 linhas) para agentes. Ambos herdam vocabulário dos arquivos já prontos.
Prompt pronto para copiar
sessão 3ACrie CONTRIBUTING.md (como rodar testes, convenções, onde achar o quê) e CLAUDE.md curto (< 100 linhas) com as convenções e comandos.
📥O que esperar da resposta
- • Pré-requisitos (Node 20, Docker)
- • Setup em 5 comandos
- • Como rodar testes (unit, e2e)
- • Convenções de commit e branch
- • Onde achar docs por módulo
- • Como abrir um PR
- • Contexto do projeto (3–5 linhas)
- • Comandos mais usados
- • Convenções de código
- • Onde ler (ARCHITECTURE.md, docs/)
- • Restrições importantes
- • Estilo de commit
💡CLAUDE.md enxuto é lei
CLAUDE.md é carregado em toda sessão futura e re-injetado após compaction. Cada linha é paga muitas vezes. Se tiver 300 linhas, você vai gastar ~300 tokens em toda chamada, para sempre. Mantê-lo < 100 linhas é decisão econômica, não só estética.
💰 Estimativa de tokens e custo real
Objetivo: mostrar o ganho em números concretos. Split de sessão não é capricho — é economia mensurável e qualidade preservada. Usamos preços de Sonnet 4.6 como referência.
📊Comparação lado a lado
💡Por que a economia é > 3× mesmo sendo "3 sessões"
Crescimento de contexto numa sessão única é quadrático (releitura a cada turno). Em 3 sessões independentes, cada uma cresce linearmente e parte do zero. Isso é o que transforma 3× mais sessões em 5× menos tokens. Bônus: qualidade da última sessão é igual à da primeira, enquanto no fluxo único você entrega um CLAUDE.md pior produzido com contexto poluído.
⚠️Números são ilustrativos
Os valores acima são estimativas baseadas em um projeto médio (5 módulos, ~30 arquivos por módulo). O seu caso pode variar — mas a forma da curva não muda: fluxo em múltiplas sessões sempre economiza em repos grandes. Meça sua sessão real com /context para números concretos.
📋Resumo do Módulo
Próxima trilha:
Trilha 6 — 🚀 Expert
Nível de maturidade avançada: automações, Claude Code como parte do fluxo, time inteiro produtivo.