MODULO 3.8

📦 Workflow: Migracao Multi-arquivo

Domine o workflow de migracoes e refatoracoes que afetam dezenas de arquivos: planejamento em Plan Mode, execucao em batches, testes intermediarios e uso de /compact para manter o contexto gerenciavel.

6
Topicos
35
Minutos
Avancado
Nivel
Teoria + Pratica
Tipo
1

🗺️ Planejando em Plan Mode

Migracoes multi-arquivo sao as tarefas mais arriscadas em desenvolvimento. Antes de mudar uma unica linha de codigo, use o Plan Mode do Claude para mapear o escopo completo: quais arquivos serao afetados, quais dependencias existem e qual a ordem segura de execucao.

🎯 Conceito Principal

O Plan Mode (ativado com Shift+Tab ou configurando o modo para "plan") faz o Claude analisar sem modificar. Ele le os arquivos, mapeia dependencias e propoe um plano de execucao detalhado antes de tocar em qualquer codigo.

  • • Analise de escopo: O Claude lista todos os arquivos que precisam mudar e por que. Nenhuma surpresa no meio da migracao
  • • Mapa de dependencias: Identifica quais arquivos dependem de quais, determinando a ordem segura de modificacao
  • • Estimativa de risco: O Claude avalia quais mudancas sao mecanicas (rename seguro) versus quais envolvem logica (maior risco)
  • • Batches definidos: O plano divide a migracao em batches de 3-5 arquivos, cada batch testavel independentemente

💻 Exemplo no Terminal

# Ativar Plan Mode e pedir analise
> [Plan Mode] Preciso renomear o modelo User para Account em todo o projeto. Analise o escopo completo:
- Quais arquivos serao afetados?
- Quais dependencias existem entre eles?
- Qual a ordem segura de execucao?
- Divida em batches de no maximo 5 arquivos.
NAO modifique nada ainda.

💡 Dica Pratica

Nunca comece uma migracao multi-arquivo sem um plano. O tempo investido no planejamento se paga 10x evitando estados inconsistentes onde metade do codigo usa o nome antigo e metade o novo.

Salve o plano do Claude em um arquivo para referencia: "Salve este plano de migracao em MIGRATION_PLAN.md"

2

📋 Identificando arquivos afetados

O Claude Code pode mapear automaticamente todos os arquivos impactados por uma mudanca, usando grep, analise de imports e arvore de dependencias. Isso garante que nenhum arquivo seja esquecido durante a migracao.

🎯 Conceito Principal

Identificar impacto vai alem de um simples "find and replace". O Claude analisa imports, exports, tipos, interfaces, testes e documentacao para montar a lista completa de arquivos afetados, incluindo os que precisam de mudancas indiretas.

  • • Referencias diretas: Arquivos que importam ou usam diretamente o que esta sendo modificado
  • • Referencias indiretas: Arquivos que usam via re-export, heranca ou composicao
  • • Testes relacionados: Arquivos de teste que verificam o comportamento sendo modificado
  • • Configuracoes: package.json, tsconfig.json, .env, docker-compose.yml que podem precisar de ajuste

💻 Exemplo no Terminal

> Liste TODOS os arquivos que referenciam "UserService" direta ou indiretamente. Inclua imports, tipos, testes e configuracoes. Classifique cada arquivo como: mudanca direta, mudanca indireta ou teste.

💡 Dica Pratica

Peca ao Claude para criar um checklist markdown com todos os arquivos afetados. Marque cada um conforme for modificado. Isso evita o problema mais comum em migracoes: esquecer um arquivo.

Verifique tambem arquivos de configuracao de build (webpack, vite, tsconfig paths) que podem ter aliases ou mapeamentos para o nome antigo.

3

⚡ Executando em batches

Nunca modifique todos os arquivos de uma vez. A execucao em batches de 3-5 arquivos permite detectar problemas cedo, manter o codigo compilavel entre batches e fazer rollback parcial se necessario.

🎯 Conceito Principal

Batch execution e a abordagem mais segura para migracoes grandes. Cada batch e um conjunto coeso de mudancas que pode ser commitado, testado e revertido independentemente. Se algo quebra no batch 3, voce so precisa reverter o batch 3, nao os anteriores.

  • • Tamanho do batch: 3-5 arquivos e o sweet spot. Mais que isso e dificil de revisar. Menos e muito lento
  • • Coesao do batch: Agrupe arquivos que dependem entre si no mesmo batch para evitar estados intermediarios quebrados
  • • Commit por batch: Faca um commit apos cada batch bem-sucedido. Isso cria pontos de restauracao seguros
  • • Instrucao ao Claude: "Execute apenas o batch 1 do plano de migracao. NAO avance para o batch 2 sem minha confirmacao."

💻 Exemplo no Terminal

# Executar batch 1
> Execute o batch 1 do plano: renomeie User para Account em models/user.ts, types/user.ts e interfaces/user.ts. Depois pare e espere minha confirmacao.
# Apos testar batch 1
> Batch 1 OK. Execute o batch 2: atualize os imports em services/auth.ts, services/profile.ts e controllers/user.ts.

💡 Dica Pratica

Comece pelos arquivos mais "internos" (models, types) e avance para os mais "externos" (controllers, routes, views). Isso garante que as dependencias ja estejam atualizadas quando voce chegar nos consumidores.

Se o projeto usa TypeScript, mantenha o build rodando entre batches: erros de tipo apontam imediatamente quais referencias voce esqueceu de atualizar.

4

✅ Testando apos cada batch

Testes entre batches sao a rede de seguranca da migracao. Apos cada batch, rode testes, build e linting para confirmar que o codigo esta num estado consistente antes de prosseguir. Sem isso, voce acumula problemas que se tornam impossíveis de diagnosticar.

🎯 Conceito Principal

O ciclo por batch e: modifica → testa → comita → proximo batch. Se os testes falham, voce para, corrige no batch atual e so entao avanca. Nunca avance para o proximo batch com testes falhando.

  • • Testes unitarios: Rode apos cada batch para pegar erros de referencia, imports quebrados e tipos incorretos
  • • Build/compile: Para TypeScript, Go, Rust - rode o build para pegar erros de tipo que testes podem nao cobrir
  • • Linting: ESLint, Pylint - pegam imports nao utilizados, variaveis mortas e outros problemas pos-rename
  • • Commit de checkpoint: Cada batch testado e commitado cria um ponto seguro de retorno

💻 Exemplo no Terminal

> Batch 1 concluido. Agora:
1. Rode npm run build para verificar erros de tipo
2. Rode npm test para verificar testes
3. Se tudo passar, faca um commit "refactor: rename User to Account - batch 1/4"
4. Se falhar, corrija antes de continuar

💡 Dica Pratica

Use mensagens de commit numeradas para migracoes: "refactor: rename User → Account (batch 1/4 - models)". Isso facilita o rollback seletivo e a revisao do PR.

Se um batch falhar e o fix nao for obvio, faca git stash e analise o problema com calma antes de continuar.

5

🔍 Sweep final (verificacao completa)

Apos todos os batches, faca um sweep final: uma varredura completa para encontrar referencias esquecidas, strings hardcoded, comentarios desatualizados e qualquer resquicio do nome/padrao antigo que tenha escapado dos batches.

🎯 Conceito Principal

O sweep final e a ultima linha de defesa. O Claude faz um grep global pelo nome/padrao antigo em todo o projeto, incluindo arquivos que nao estavam no plano original - configuracoes, scripts, documentacao, seeds e fixtures.

  • • Grep global: Busca pelo nome antigo em TODOS os arquivos, incluindo .env, README, comments, strings, fixtures e seeds
  • • Testes completos: Rode a suite inteira de testes, nao apenas os unitarios. Integracao e e2e podem revelar problemas que unitarios nao pegam
  • • Review final: Peca ao Claude para fazer um /review de todas as mudancas da migracao juntas
  • • Documentacao: Atualize README, API docs e qualquer documentacao que referencia o nome/padrao antigo

💻 Exemplo no Terminal

> Faca um sweep final da migracao User → Account:
1. Grep por "User" (case-insensitive) em todo o projeto
2. Identifique referencias que deveriam ter sido renomeadas
3. Ignore falsos positivos (ex: "username" nao precisa mudar)
4. Corrija as que faltaram
5. Rode todos os testes novamente

💡 Dica Pratica

O sweep final frequentemente encontra 5-10% de referencias esquecidas, especialmente em strings de log, mensagens de erro, nomes de tabelas de banco e fixtures de teste. Nunca pule essa etapa.

Faca o sweep em um commit separado: "refactor: rename User → Account - final sweep". Isso deixa claro na historia do git o que foi planejado vs o que foi pego no sweep.

6

📦 /compact em migracoes longas

Migracoes multi-arquivo geram conversas muito longas com o Claude. O contexto cresce a cada batch e o Claude pode perder o foco. O /compact e essencial para manter o contexto gerenciavel sem perder o progresso da migracao.

🎯 Conceito Principal

Em migracoes longas, o /compact resume a conversa mantendo o plano de migracao, batches ja concluidos e o estado atual. Isso reduz o consumo de tokens e melhora a qualidade das respostas nos batches seguintes.

  • • Quando compactar: Apos cada 2-3 batches completos, ou quando sentir que as respostas estao ficando lentas ou imprecisas
  • • Compact direcionado: Use /compact mantenha o plano de migracao e o status de cada batch para preservar o essencial
  • • Plano externo: Mantenha o plano de migracao em um arquivo .md separado para que o Claude possa rele-lo apos o compact
  • • Economia real: Uma migracao de 20 arquivos pode consumir 200k+ tokens sem compact. Com compact a cada 3 batches, cai para 50-80k tokens

💻 Exemplo no Terminal

# Apos completar batch 3 de 6
> /compact mantenha: 1) plano de migracao completo, 2) batches 1-3 ja concluidos e commitados, 3) batches 4-6 pendentes com lista de arquivos
# Retomar apos compact
> Continuando a migracao. Leia MIGRATION_PLAN.md para relembrar o plano. Execute o batch 4.

💡 Dica Pratica

A estrategia ideal e: plano no arquivo + compact na conversa. O plano fica persistido em MIGRATION_PLAN.md, e o Claude pode rele-lo a qualquer momento. A conversa fica leve com compact regular.

Para migracoes muito grandes (50+ arquivos), considere usar sessoes separadas para cada grupo de batches, em vez de uma unica sessao com compact.

🏋️ Exercicio Pratico

Executar rename/refactor em 10+ arquivos com o workflow completo

1

Planejar a migracao

Escolha um rename real no seu projeto e peca o plano:

> [Plan Mode] Preciso renomear X para Y. Mapeie todos os arquivos afetados e divida em batches.
2

Executar batches com testes

Execute cada batch, teste e comite:

> Execute batch 1. Rode testes. Comite se passar.
3

Compact e continuar

Apos batch 3, compacte e continue:

> /compact mantenha o plano de migracao e status dos batches
4

Sweep final

Faca a varredura final e confirme que nada foi esquecido:

> Sweep final: grep global pelo nome antigo, corrija o que faltou, rode todos os testes.

✅ Criterios de Sucesso

☐ Planejou em Plan Mode antes de executar
☐ Identificou todos os arquivos afetados
☐ Executou em batches de 3-5 arquivos
☐ Testou apos cada batch
☐ Usou /compact durante a migracao
☐ Fez sweep final e tudo passa

📋 Resumo do Modulo

✓
Plan Mode antes de tudo - Mapeie escopo, dependencias e ordem antes de mudar uma unica linha.
✓
Identifique TODOS os arquivos afetados - Diretos, indiretos, testes, configs e documentacao.
✓
Execute em batches de 3-5 arquivos - Cada batch testavel e commitavel independentemente.
✓
Teste apos cada batch - Build, testes e linting entre batches. Nunca avance com falhas.
✓
Sweep final pega o que escapou - Grep global, testes completos e review das mudancas totais.
✓
/compact mantem o contexto gerenciavel - Compacte a cada 2-3 batches. Mantenha o plano em arquivo externo.

Proximo Modulo:

3.9 - Agent Teams e Loop Agentico (2026)

← Modulo Anterior Voltar para Trilha Proximo Modulo →