Atualizei a dependência e o projeto quebrou: como conduzir a migração com o Claude Code passo a passo

Tu roda o update, a versão nova entra bonitinha, e a aplicação simplesmente não sobe mais

Se liga no que acontece numa major version: a API mudou, e a quebra não fica num arquivo só, ela aparece em cinco, oito, quinze lugares ao mesmo tempo. Import que não existe mais, função renomeada, opção que virou objeto de config, aquele adapter que agora exige outra assinatura

E aí vem o erro que a maioria comete, e não é usar IA pra isso. O erro é abrir o terminal, colar um "migra o projeto pra versão nova e conserta tudo" e apertar enter. O agente sai editando arquivo em série, cada correção mexe no que a anterior arrumou, e no fim tu não sabe mais o que está quebrado por causa da lib e o que está quebrado por causa da migração 😅

O caminho que funciona é o chato: levantar o estrago, planejar antes de editar, corrigir arquivo a arquivo e validar cada etapa antes de seguir pra próxima. É isso que a gente vai montar aqui

O que ter pronto antes de pedir qualquer alteração

Antes de pedir uma linha de código, deixa o terreno preparado. Migração é operação de risco, e o preparo é o que te dá o botão de voltar

• Projeto versionado com árvore limpa: commita ou guarda o que estiver solto, porque tu vai precisar comparar o antes e o depois, e o git é o teu chão firme
• Um comando que falhe de forma reprodutível: a suíte de testes, ou pelo menos o build, ou o comando que sobe a aplicação. Se a quebra não é reprodutível, não tem como validar etapa nenhuma
• O changelog e o guia de migração da dependência abertos: quem escreveu a lib já documentou o que mudou, usa isso
• Um CLAUDE.md na raiz do projeto: arquivo markdown que o Claude Code lê no início de toda sessão, feito pra padrões de código, decisões de arquitetura, bibliotecas preferidas e checklist de revisão

Esse último item parece burocracia e é o que mais te economiza digitação depois. O CLAUDE.md da raiz sobrevive à compactação: depois de um /compact, o Claude relê o arquivo do disco e reinjeta na sessão. Traduzindo: a regra que tu escreveu lá não se perde no meio de uma migração longa, e tu não precisa repetir "usa a nova assinatura, não a antiga" a cada prompt

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Escolhe o modo de permissão certo pra isso:

Migração usa dois modos de permissão, em momentos diferentes, e é bom combinar isso antes de começar

Na fase de levantar o estrago e montar o plano, o plan mode: o Claude pesquisa e propõe mudanças, sem editar os arquivos-fonte até tu aprovar

Na fase de executar o plano, o modo Manual: nele o Claude Code para e pergunta antes da maioria das ações que editam arquivos, rodam comandos de shell ou acessam a rede

Parece lento? É. E é lentidão boa, porque cada confirmação é uma chance de tu ver a besteira antes dela acontecer, não depois

Shift+Tab alterna os modos de permissão na CLI, então tu vai e volta entre os dois sem drama. Vale conferir a documentação dos modos de permissão pra entender como eles se alternam

E se eu quiser isolar a migração?

Um git worktree é um diretório de trabalho separado, com arquivos e branch próprios, compartilhando o mesmo histórico e remote do teu checkout principal. Rodando cada sessão do Claude Code no seu worktree, as edições de uma sessão não tocam os arquivos da outra

Dois detalhes de convivência: a documentação recomenda colocar .claude/worktrees/ no .gitignore, pra o conteúdo dos worktrees não aparecer como arquivo não rastreado no checkout principal, e usar um arquivo .worktreeinclude pra levar arquivos ignorados pelo git, tipo o .env, pra cada worktree novo

# .gitignore
.claude/worktrees/

Sem isso tu vai subir o worktree e descobrir que a aplicação não conecta em nada, porque o .env ficou pra trás. Tome cuidado! 😀

Passo a passo da migração com o Claude Code

Agora o núcleo. Cada passo tem o comando ou o prompt, e o erro comum que ele evita

1. Levanta o terreno com npm outdated

Antes de falar de correção, tu precisa saber em que versão está e pra onde pode ir

npm outdated

A saída traz as colunas wanted, latest e location, mas duas delas fazem o trabalho pesado aqui:

A diferença entre wanted e latest é quase sempre o tamanho do problema: se as duas batem, tu está dentro do range e o salto é pequeno. Se latest está bem à frente, tu está olhando pra uma troca de major, e é aí que a migração aparece

O erro comum deste passo: achar que essa lista cobre tudo. O npm outdated usa profundidade 0 por padrão, ou seja, sem sobrescrever esse valor só as dependências de primeiro nível desatualizadas aparecem. Dependência transitiva, aquela que veio junto com outra, não está nessa foto. Se quiser o detalhe das colunas e flags, a documentação do npm é a referência

2. Reúne os sintomas reais, não a memória deles

Roda o build, roda os testes, e coleta a saída de fato. Stack trace inteiro, nome do arquivo, número da linha, mensagem exata

npm run build
npm test

Essa saída é o teu material de trabalho. É o que separa "a lib quebrou meu projeto" de "o módulo X não exporta mais Y nestes quatro arquivos"

O erro comum deste passo: descrever o erro de cabeça. "Acho que é alguma coisa com o import do client" gera correção baseada em chute. Cola a saída, sempre

3. Entra em plan mode antes de deixar ele editar nada

Plan mode é um permission mode: o Claude pesquisa e propõe mudanças sem editar os arquivos-fonte. Ele lê, busca, roda comandos de exploração, e apresenta um plano pra tua aprovação antes de tocar em qualquer coisa

Pra entrar, Shift+Tab alterna os modos de permissão na CLI, ou tu prefixa um único prompt com /plan

/plan leia os arquivos que aparecem nesta saída de erro, confira o guia de migração da versão nova e proponha um plano de migração com ordem de execução, sem alterar código

A razão de existir esse passo está na própria documentação de boas práticas: separar pesquisa e planejamento da implementação, porque deixar o Claude ir direto pro código pode produzir código que resolve o problema errado. E código que resolve o problema errado é pior que erro de build, porque ele passa

O erro comum deste passo: pular pra implementação porque "é rapidinho". Migração nunca é rapidinho

4. Revisa e CORTA o plano

O plano vai voltar com um monte de item. Tua tarefa agora é ser chato com ele: quebrar em etapas pequenas, uma por vez, um arquivo ou um grupo coeso de arquivos por etapa

É como contratar um cara muito bom e não largar um projeto inteiro na mão dele de uma vez: tu entrega o primeiro pedaço, confere, e entrega o segundo

Plano cortado, tu sai do plan mode e volta pro modo Manual com Shift+Tab. Daqui pra frente (passos 5 e 6) é ele que segura o freio, pedindo confirmação antes das ações que editam arquivo, rodam shell ou acessam a rede

O erro comum deste passo: aprovar o plano inteiro e mandar executar tudo. Aí a quebra volta multiplicada, e tu perdeu a referência de qual mudança causou o quê. Essa é a mesma lógica de pedir a atualização em pedaços pequenos: escopo menor, resultado conferível

5. Executa a primeira etapa e pede evidência no MESMO prompt

Aqui tem um detalhe que muda tudo. Não basta pedir a correção, pede rodar, testar e mostrar

aplique só a etapa 1 do plano (apenas o arquivo src/api/client.js), depois rode npm test e me mostre o comando executado e a saída completa

Como tu está no modo Manual, cada edição e cada comando vai parar e te perguntar antes de acontecer. Aproveita essa parada pra ler o que ele vai fazer, não é só apertar sim no automático

A documentação de boas práticas é direta nisso: pedir rodar, testar, comparar ou verificar no mesmo prompt faz o Claude iterar em vez de parar na primeira tentativa. E pedir evidência (a saída do teste, o comando e o retorno) em vez de aceitar a afirmação de sucesso

O erro comum deste passo: aceitar o "pronto, corrigido" e seguir. Sem a saída na tela, tu está confiando na narrativa, não no resultado

6. Valida antes de seguir, e saiba voltar

Etapa validada é etapa fechada. Se a etapa piorou o estado, tu volta

O comando /rewind (ou pressionar Esc duas vezes com o campo de prompt vazio) abre o menu de rewind, que permite restaurar código, conversa ou os dois até um checkpoint anterior

Agora o aviso importante, e é aqui que gente se ferra: os checkpoints só registram mudanças feitas pelas ferramentas de edição de arquivo do Claude. Alteração feita por comando Bash, tipo echo > file.txt ou sed -i, ou por processo externo, não é capturada. E quando o checkpoint selecionado não tem mudanças de arquivo rastreadas, o menu oferece apenas restaurar a conversa, resumir ou cancelar

O erro comum deste passo: tratar o /rewind como undo universal. Ele não é. Por isso o git continua sendo teu seguro de verdade: commit entre etapas, sempre

7. Repete por etapa, cuidando do contexto no caminho

Migração é conversa longa, e conversa longa satura o contexto. Três comandos resolvem a vida:

• /context mostra uma divisão ao vivo do uso do contexto por categoria, com sugestões de otimização e quais arquivos CLAUDE.md foram carregados
• /compact substitui a conversa por um resumo estruturado, e aceita um foco
• /clear começa do zero numa tarefa nova mantendo a memória do projeto, recomendado quando tu troca pra um trabalho não relacionado

/compact focus on the API changes

O foco no /compact é o pulo do gato numa migração: tu preserva o que interessa (o que mudou na API, o que já foi corrigido) e joga fora a discussão que não serve mais

O erro comum deste passo: arrastar a sessão inteira até o contexto estourar exatamente no meio da migração, quando tu já está na etapa 6 de 9

8. Fecha com verificação independente

A documentação de boas práticas sugere uma segunda opinião: um subagente de verificação, ou um workflow em que um modelo novo tenta refutar o resultado, pra que o agente que fez o trabalho não seja o mesmo que o avalia

Subagentes podem ser definidos como arquivos markdown nas pastas .claude/agents/ (no projeto) e ~/.claude/agents/ (global), e name e description são os únicos campos obrigatórios do frontmatter YAML. Eles servem justamente pra isolar contexto e limitar quais ferramentas o subagente usa

---
name: verificador-migracao
description: Revisa o resultado das etapas da migracao e tenta refutar o "passou"
---

Confira se o build e os testes realmente passam, rode os comandos e
mostre a saida. Aponte qualquer uso remanescente da API antiga.

O erro comum deste passo: deixar quem fez o trabalho ser o juiz do próprio trabalho. Ninguém acha muito defeito no que acabou de escrever, nem gente nem modelo 🙂

Quando a migração trava: sintomas comuns e o que fazer

A correção de um arquivo reintroduz o erro em outro:

Causa provável: escopo grande demais por prompt. O agente tocou em coisa que não era da etapa e desfez o que já estava certo

Solução: volta com /rewind até o checkpoint anterior e refaz em etapas menores, uma de cada vez

Como prevenir: fila de etapas definida no plan mode, com o recorte de arquivos explícito em cada prompt

O Claude diz que passou, mas o build continua falhando:

Causa provável: tu aceitou uma afirmação de sucesso sem evidência

Solução: pede o comando executado e a saída, no mesmo prompt da correção

Como prevenir: nunca separa tarefa de verificação. "Corrija e rode o teste mostrando a saída" é um pedido só, não dois

O menu de rewind não oferece restaurar o código:

Causa provável: o checkpoint selecionado não tem mudanças de arquivo rastreadas, o que acontece quando a alteração veio de comando Bash ou de processo externo

Solução: recorre ao git, é pra isso que ele está lá

Como prevenir: mantém as alterações nas ferramentas de edição de arquivo e commita entre etapas. Escolher entre atualizar por script no terminal ou pela ferramenta de edição muda o que tu consegue desfazer depois, e vale entender onde parar ao atualizar dependências antes de automatizar demais

A sessão fica lenta e confusa no meio do caminho:

Causa provável: contexto saturado, com log de erro antigo, arquivo inteiro lido três vezes e discussão que já morreu

Solução: /context pra diagnosticar o consumo por categoria e /compact com foco pra enxugar

Como prevenir: CLAUDE.md na raiz com as regras da migração, já que ele é relido do disco depois da compactação. Assim o resumo pode ser agressivo sem tu perder o combinado

Variações do método para cenários diferentes

Migração que toca muitos arquivos repetitivos:

Quando a mudança é a mesma regra aplicada em trinta lugares, escrever a regra no prompt de cada etapa é desperdício e é fonte de inconsistência

Padroniza no CLAUDE.md antes de começar: a assinatura nova, o import correto, o que NÃO usar mais. Ele é lido no início de cada sessão, então a regra já entra junto

Projeto com lint rígido:

Dá pra configurar um hook PostToolUse no .claude/settings.json, com um matcher do tipo Edit|Write, pra rodar o lint no arquivo logo depois da edição. Assim tu descobre o problema de estilo na hora, não no CI

Só não confunda com guardrail: hooks PostToolUse não conseguem desfazer ações, porque a ferramenta já foi executada. Eles servem pra efeito colateral, tipo formatação e log, não pra impedir operação

Duas frentes ao mesmo tempo:

Cenário clássico: tu quer migrar a dependência e ao mesmo tempo outra sessão segue tocando uma feature

Cada sessão no seu git worktree, diretório de trabalho separado com arquivos e branch próprios, compartilhando histórico e remote. As edições de uma sessão não tocam os arquivos da outra, e tu não descobre no commit que as duas mexeram no mesmo import

Resumo e o próximo passo

Migração quebrada não se resolve com pedido gigante, se resolve com etapas verificáveis

O ciclo é esse, e ele repete até acabar a fila:

1. mapear o que está desatualizado e o tamanho do salto
2. coletar a saída real do erro, não a lembrança dela
3. planejar em plan mode, sem editar código
4. cortar o plano em etapas pequenas e voltar pro modo Manual
5. executar UMA etapa e exigir evidência no mesmo prompt
6. validar, commitar, e só então seguir

O próximo passo prático é curto: escreve o CLAUDE.md do teu projeto hoje, com padrões de código e as decisões de arquitetura que tu não quer ver violadas. Aí na próxima atualização de dependência, começa pelo plan mode com Shift+Tab e manda uma etapa por prompt

É menos emocionante que colar tudo de uma vez, e é muito mais rápido no total, porque tu não gasta a tarde desenrolando o novelo que o agente fez 😀

até o próximo post!