5.1 Refatorando Arquivo Grande | Mestre em Contexto e Tokens

🎬O cenário

Você tem um arquivo de 2000 linhas — por exemplo, um service.ts bagunçado que foi crescendo sem freio. Precisa refatorar. Se abrir tudo no Claude e começar a pedir mudanças, em 30 minutos a janela estoura, a qualidade cai, e você fica brigando com context rot. A saída não é "refatorar mais rápido" — é fatiar. O que vem a seguir são os 6 passos que funcionam na prática.

📋 Plan mode — entender arquitetura

Objetivo: mapear o arquivo sem alterar nada. Plan mode força o Claude a ler e raciocinar, não executar. O output é um diagnóstico estruturado que vira base de todos os próximos passos.

Prompt pronto para copiar

passo 1

Estou em plan mode. Abra o arquivo service.ts.
Não altere nada. Me responda:
1. Qual a responsabilidade principal?
2. Quais são os blocos lógicos (regiões)?
3. Quais dependências externas ele tem?
Formato: lista, não prose.

📥O que esperar da resposta

•1 frase curta para a responsabilidade principal (ex: "orquestra criação e cobrança de pedidos")
•Lista com 4–8 blocos lógicos (ex: validação, persistência, notificações, cobrança, logs)
•Dependências externas nomeadas: APIs, serviços, libs de terceiros, banco
•Output total ~1–2k tokens. Se vier longo demais, peça "mais conciso"

💡Por que "formato: lista, não prose"

Prose dobra os tokens e mistura análise com narrativa. Lista entrega só o essencial, cabe no contexto de turnos seguintes e é fácil de citar ("volte à região 3 da sua lista"). Essa instrução sozinha corta ~30% do output.

→

Próximo passo: com o mapa na mão, pedir a divisão em regiões ordenadas por risco.

🗺️ Dividir em regiões

Objetivo: transformar o mapa do passo 1 em um plano de execução com 4–6 regiões independentes, ordenadas do menor risco ao maior. Cada região vira um checkpoint — um commit reversível.

Prompt pronto para copiar

passo 2

Com base no que leu, proponha 4–6 regiões de refactor,
em ordem de menor risco → maior risco.
Para cada: objetivo, tamanho estimado (linhas), dependências.

📥O que esperar da resposta

Região 1: Extrair validadores (baixo risco)
  Objetivo: mover funções de validação para validators.ts
  Tamanho: ~200 linhas
  Dependências: nenhuma

Região 2: Isolar logger (baixo risco)
  Objetivo: centralizar logs em logger.ts
  Tamanho: ~80 linhas
  Dependências: nenhuma

Região 3: Separar repositório (médio risco)
  Objetivo: mover queries de DB para repository.ts
  Tamanho: ~400 linhas
  Dependências: prisma

Região 4: Extrair cobrança (alto risco)
  Objetivo: service de billing isolado
  Tamanho: ~500 linhas
  Dependências: Stripe API, DB

Se as dependências forem "intra-arquivo", sinalize como risco alto — refactor vai quebrar o que está ao redor.

💡Regra de ouro da ordem

Comece pelo que não quebra nada: extração de funções puras, constantes, utilitários. Deixa para o final o que toca I/O, efeitos colaterais ou controle de fluxo principal. Em 90% dos casos isso casa naturalmente com "menor → maior risco".

→

Próximo passo: executar a região 1, e só a região 1.

🔨 Refatorar uma região por vez

Objetivo: executar exatamente uma região, sem transbordar. O "pare" explícito no final é o que cria o checkpoint — sem ele, o Claude tende a "continuar ajudando" e mexer em código que você ainda não revisou.

Prompt pronto para copiar

passo 3

Execute a região 1. Não toque em nada fora dela.
Ao terminar, pare.

📥O que esperar da resposta

•Arquivos criados/editados com o escopo exato da região (nenhuma linha fora dela)
•Resumo curto do que foi feito (3–5 linhas)
•Parada limpa — sem "quer que eu continue com a região 2?"
•Se sugerir algo fora do escopo, ignore e siga para o passo 4

⚠️Por que "pare" é crítico

Sem o "pare", o Claude frequentemente continua para a próxima região "de brinde". Isso pula o passo de teste, acumula mudanças não verificadas no contexto e se algo quebrar você não sabe qual região foi culpada. Checkpoint entre regiões evita context rot e dá reversibilidade.

→

Próximo passo: rodar testes antes de tocar na próxima região.

✅ Testes entre regiões

Objetivo: verde antes de avançar. Se os testes falharem, você quer saber antes do Claude "consertar" algo — porque às vezes o fix é piorar um teste (comentar, relaxar assert). Você decide.

Prompt pronto para copiar

passo 4

Rode os testes. Se passarem, commit.
Se falharem, me diga antes de consertar.

📥O que esperar da resposta

•Caso verde: "Testes passaram (X ok). Commit feito: refactor(service): região 1 — extrair validadores"
•Caso vermelho: nome do teste que falhou + output do erro + hipótese de causa. Sem patch aplicado.
•Se Claude aplicar patch mesmo assim, peça rollback e repita o prompt acima

Template de commit message

refactor(service): região X — [descrição curta]

Exemplos reais:

refactor(service): região 1 — extrair validadores
refactor(service): região 2 — centralizar logger
refactor(service): região 3 — isolar repository

git bisect entre commits assim resolve qualquer regressão em segundos.

→

Próximo passo: após 2–3 regiões, aliviar o contexto com /compact.

🗜️ /compact entre regiões grandes

Objetivo: se após 2–3 regiões o contexto já está em 40%+ da janela (confira com /context), comprima o histórico antes de atacar a próxima região. Qualidade das próximas saídas depende disso.

Prompt pronto para copiar

passo 5

/compact mantenha foco em arquitetura e decisões,
pode resumir tentativas

Quando rodar /compact

< 30%

Contexto OK. Continue refatorando normalmente.

30–50%

Zona de atenção. /compact se faltarem >3 regiões.

> 50%

/compact obrigatório antes de seguir.

📥O que esperar da resposta

•Resumo preservando o plano, decisões e regiões já feitas
•Descarte de iterações (tentativas, revisões de código, outputs de teste antigos)
•Contexto volta para ~10–15% da janela
•Próximas regiões saem com qualidade igual às primeiras

→

Próximo passo: ao terminar todas as regiões, commit final + handoff.

📦 Commit + handoff final

Objetivo: fechar a sessão com dignidade. Handoff estruturado (mesmo template da Trilha 3) garante que amanhã qualquer pessoa (você ou um colega) possa continuar sem reconstruir contexto do zero.

Prompt pronto para copiar

passo 6

Todas as regiões foram refatoradas.
Produza um handoff estruturado com:
- Objetivo original
- O que foi feito (por região)
- Decisões arquiteturais tomadas
- O que ficou pendente (se houver)
- Próximos passos sugeridos
Depois posso limpar a sessão.

📥O que esperar da resposta

# Handoff — Refactor service.ts

## Objetivo
Dividir service.ts (2000 linhas) em módulos
coesos, preservando comportamento.

## Feito
- Região 1: validadores → validators.ts
- Região 2: logs → logger.ts
- Região 3: queries → repository.ts
- Região 4: billing → billing.service.ts

## Decisões
- Mantido nome original de service.ts
  como fachada pública
- Injeção via construtor em todas as
  novas classes

## Pendente
- Nenhum

## Próximos passos
- Rodar cobertura de testes
- Revisar logs em staging antes de prod

🏁Checklist antes de /clear

☐Todos os commits estão verdes (git log --oneline)
☐Handoff salvo como docs/handoff-refactor-service.md
☐Push para remoto (se PR aberto, link anexado)
☐/clear agora, não depois

📋Resumo do Módulo

✓

Plan mode primeiro — entenda antes de mexer; output em lista, não prose

✓

4–6 regiões ordenadas por risco — começar pelo fácil, deixar I/O para o fim

✓

"Ao terminar, pare" — checkpoint obrigatório entre regiões

✓

Testes + commit entre regiões — reversibilidade garantida

✓

/compact aos 40%+ — mantenha atenção do modelo em pico

✓

Handoff estruturado no fim — continuidade sem custo de reconstrução

Próximo módulo:

5.2 — 🐛 Debug em Projeto Que Nunca Vi

Como investigar um bug num repo desconhecido usando subagentes e hipóteses ordenadas.

← Voltar para Trilha Próximo: Debug →