🎯 Por que "tudo em uma" não escala
Quase todo desastre do tipo "depois de 3 horas o Claude ficou burro" tem a mesma causa: a tarefa era grande demais para uma sessão só. Tentar empilhar tudo ataca 4 frentes ao mesmo tempo.
Context rot
Qualidade cai antes mesmo de você estourar a janela. Instruções do início se diluem, decisões começam a contradizer.
Custo quadrático
Cada turno relê o histórico inteiro. Dobrar a sessão quadruplica o custo. A última hora custa mais que as 3 anteriores.
Sem checkpoints
Algo deu errado no meio? Reverter "até ali" é impossível sem rewind manual. Cada erro vira bola de neve.
Difícil de reverter
Sem estados intermediários salvos, retomar a tarefa dias depois exige recomeçar do zero.
🧠Mudança de mentalidade
Uma tarefa grande não é uma sessão grande. Uma tarefa grande é um encadeamento de sessões pequenas, cada uma com seu objetivo claro, saída clara, e handoff que alimenta a próxima. Pense em pipeline, não em maratona.
📊Números concretos
📐 Fluxo canônico de 3 sessões
Para 80% das tarefas médias, o padrão abaixo resolve: Ler → Planejar → Executar. Três sessões, cada uma com objetivo único, cada uma produzindo um handoff que vira o combustível da próxima.
Pipeline de 3 sessões
Entender o terreno. Mapear o que existe.
map.md — arquitetura, dependências, pontos de atenção
A partir do mapa, decidir como atacar.
plan.md — lista de passos, riscos, ordem
Executar o plano. Sem decidir nada novo.
Código + tests.md + PR pronto
🎯Por que esse fluxo funciona
- →Cada sessão tem um objetivo único — evita mudança de contexto mental
- →Saída é artefato persistente — salva em disco, não na memória do Claude
- →Sessão de executar fica leve — não precisa ler o projeto inteiro de novo, só o plano
- →Erro em uma sessão não contamina as outras — refaz só o passo
💡Regra de ouro
Uma sessão, um objetivo, um arquivo de saída. Se você terminou sem um arquivo .md que sintetize o trabalho, não terminou.
🎬 Exemplo real: migração em 5 sessões
Caso concreto: migrar um backend Express → Fastify em um projeto com ~15k linhas. Em vez de uma maratona de 8 horas, quebramos em 5 sessões curtas e focadas.
As 5 sessões da migração
| # | Objetivo | Entrega | Duração |
|---|---|---|---|
| 1 | Mapa do código atual Lê rotas, middlewares, plugins, deps |
docs/map.md | ~45 min |
| 2 | Plano de migração Ordem, riscos, equivalências de API |
docs/plan.md | ~40 min |
| 3 | Migrar rotas Converte handlers Express → Fastify |
PR #1 — rotas | ~90 min |
| 4 | Migrar middlewares Auth, logger, error handler, CORS |
PR #2 — middlewares | ~60 min |
| 5 | Ajustar testes + smoke Adapta testes, valida em staging |
PR #3 — testes + tests.md | ~50 min |
Fluxo das 5 sessões encadeadas
Cada sessão lê só o handoff da anterior + arquivos relevantes. Nunca o projeto todo de uma vez.
🎯Chave do sucesso
Nenhuma sessão tentou fazer tudo. Cada uma entregou algo testável e commitável. Se a sessão 4 deu ruim, você ainda tem PRs das sessões 1–3 estáveis. Rollback é cirúrgico.
🔗 Handoffs entre sessões
O handoff é a única coisa que viaja entre sessões. Use o mesmo template da Trilha 3. Regra simples: toda sessão termina com handoff, toda sessão nova começa lendo o handoff anterior.
Template de handoff entre sessões
# Handoff — Sessão X → Sessão Y
Data: 2026-04-21
## 1. Objetivo geral da tarefa
Migrar backend Express → Fastify, mantendo compatibilidade de API.
## 2. Onde estamos
- ✅ S1 concluída: docs/map.md criado
- ✅ S2 concluída: docs/plan.md aprovado
- 🔄 S3 em andamento: rotas migradas (12/18)
- ⏳ S4 pendente: middlewares
## 3. Decisões tomadas
- Fastify 4.x (LTS)
- Manter mesmos paths, mudar só framework
- Logger: pino (já compatível)
- Auth: adaptar middleware existente, não reescrever
## 4. Próximos passos (S4)
1. Ler docs/plan.md § Middlewares
2. Migrar auth-middleware.ts
3. Migrar error-handler.ts
4. Rodar suite de testes
5. Abrir PR #2
## 5. Arquivos a ler no início
- docs/plan.md (obrigatório)
- src/middlewares/ (pasta)
- tests/middlewares.test.ts
## 6. Pontos de atenção
- CORS tem config específica no .env — não trocar
- Rate limiter usa Redis — manter🔄Ritual de encerramento + abertura
- 1. "Gere handoff desta sessão"
- 2. Salve em
docs/handoff-NN.md - 3. Commit do handoff
- 4.
/clear
- 1. "Leia docs/handoff-NN.md"
- 2. "Confirme seu entendimento em 3 linhas"
- 3. "Execute os próximos passos"
- 4. Só então prossiga
⚠️Erro comum
"Dividir em sessões" sem handoffs vira "começar do zero 5 vezes". Se a sessão 2 não sabe o que aconteceu na sessão 1, você perdeu todo o ganho. Sem handoff, não há pipeline — só fragmentação.
📁 Artefatos persistentes
Princípio fundamental: não confie no Claude para manter estado. Memória do modelo é volátil. Arquivos em disco são permanentes, versionados, e acessíveis a qualquer agente no futuro.
Artefatos canônicos em docs/
| Arquivo | Conteúdo | Quando criar |
|---|---|---|
| map.md | Arquitetura atual, dependências, entry points | Início do projeto |
| plan.md | Plano de execução, passos, ordem, riscos | Sessão de planejamento |
| decisions.md | Log de decisões técnicas com racional (mini ADRs) | Ao tomar decisão não-óbvia |
| tests.md | Casos de teste, cenários críticos, resultados | Sessão de testes/validação |
| handoff-NN.md | Estado + próximos passos entre sessões | Fim de toda sessão |
| issues.md | Problemas encontrados, pendências, TODOs | À medida que surgirem |
💾Por que arquivos > memória do Claude
- ✓Persistem por dias/semanas, não só durante a sessão
- ✓Versionados no git, rastreáveis
- ✓Acessíveis a humanos, não só ao Claude
- ✓Permitem handoff entre pessoas do time, não só entre sessões
- ✓Carregáveis sob demanda — leia só o que precisa
💡Hábito diário
Ao final de cada sessão, pergunte ao Claude: "atualize docs/decisions.md com o que decidimos hoje". 30 segundos que poupam horas depois.
⚠️ Quando NÃO dividir
Divisão em sessões tem custo de overhead: escrever o handoff, reler no próximo, restabelecer contexto. Para tarefas pequenas, esse overhead supera o ganho.
📏Regra de 30 turnos
Divida se você estimar que a tarefa vai passar de 30 turnos OU envolver múltiplos contextos distintos (ler código + pesquisar docs externos + escrever migrações, por ex).
✅ Uma sessão é suficiente
- →Fix de bug isolado em 1–2 arquivos
- →Refactor pontual de uma função
- →Adicionar um endpoint novo pequeno
- →Escrever testes para código existente
- →Revisar PR pequeno
⚠️ Divida em múltiplas
- →Migração de framework ou biblioteca
- →Refactor de arquitetura inteira
- →Feature que toca >10 arquivos
- →Integração nova com sistema externo
- →Auditoria completa de segurança
🎯Dividir é ferramenta, não religião
Não transforme uma tarefa de 15 turnos em 3 sessões só porque "é o padrão". O overhead de 3 handoffs mata qualquer ganho. O padrão existe para tarefas que ficariam horrendas numa sessão só — não para toda e qualquer coisa.
1. Estime turnos
"Quantas trocas com o Claude isto vai exigir?" Chute >30 → divida.
2. Conte contextos distintos
"Precisa ler código, pesquisar externo, decidir, implementar?" >2 contextos → divida.
3. Avalie rollback
"Se der errado no meio, consigo desfazer fácil?" Se não, divida para ter checkpoints.
📋Resumo do Módulo
Próximo módulo:
4.3 — 📝 Arquivos: Markdown > PDF/HTML/DOCX
Higiene de anexos: o que colar, o que converter, o que nunca tocar.