Como pedir uma atualização de dependência ao Claude Code sem quebrar o projeto

Fala aí, beleza? Upgrade de dependência é aquele pedido que parece inofensivo e volta com meio projeto editado de uma vez

Um "atualiza as dependências aí" solto vira exatamente isso: import trocado em vários arquivos, configuração mexida, teste vermelho, e ninguém mais sabe qual das mudanças foi a que quebrou

Aí o dev culpa o agente

Mas o problema quase nunca é o Claude Code

O problema é o pedido: sem escopo, sem leitura antes da edição e sem critério de conclusão, qualquer agente vai fazer o MÁXIMO que ele acha que você quis dizer

Neste post eu te passo a estrutura do pedido que segura o estrago, e o caminho de volta pra quando der ruim mesmo assim (vai dar, uma hora)

Se o que você quer é o panorama maior de delegar upgrade de dependências, tem um post aqui do blog só sobre isso

O que precisa estar pronto antes de pedir o upgrade

Antes de digitar qualquer prompt, três coisas precisam estar no lugar

Não é burocracia, é o que define se você consegue voltar atrás depois

1. Árvore de trabalho limpa e commit feito

A documentação oficial de boas práticas recomenda commitar após cada unidade significativa de trabalho, justamente pra ter um histórico recuperável se algo sair errado

Então começa o upgrade do zero: nada pendente, nada meio feito misturado com o que o agente vai mexer

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Se o git status vier sujo, você não vai conseguir separar o que foi seu do que foi dele

2. Um comando de verificação que VOCÊ sabe rodar

Pode ser a suíte de testes, o build, um script de smoke

O que não pode é você descobrir na hora que não sabe como provar que o projeto ainda funciona

A régua oficial é bem direta: se você não consegue verificar, não faz o ship

3. O CLAUDE.md com os padrões do projeto

O CLAUDE.md é um arquivo markdown na raiz do projeto que o Claude Code lê no começo de cada sessão

Ele serve pra fixar padrões de código, decisões de arquitetura, bibliotecas preferidas e checklists de revisão

Ou seja: é ali que mora o "neste projeto a gente não troca de biblioteca no meio de um upgrade"

E um limite importante antes de seguir: o checkpointing do Claude Code NÃO é substituto de controle de versão

Isso não é opinião minha, a própria documentação diz e recomenda usar os dois juntos

O checkpoint é o desfazer rápido

O git é o seguro

Como pedir a atualização de dependência ao Claude Code passo a passo

A sequência abaixo é sempre a mesma, seja um patch bobo ou um major assustador

Muda só o quanto você aperta em cada etapa

1. Feche o escopo em UMA dependência, com nome e versão

Nada de "atualiza as dependências"

O pedido precisa nomear a coisa e o destino:

Quero atualizar SOMENTE a dependência <nome> da versão <atual> para a <destino>.
Não altere nenhuma outra dependência, nem versão de runtime.
Se descobrir que essa atualização exige mexer em outra dependência, PARE e me avise antes.

O erro comum deste passo: pedir várias de uma vez porque "já que tá aberto"

Aí quando o teste quebra você tem N suspeitos e zero certeza

2. Leitura antes da edição, sempre

Esse é o passo que separa upgrade tranquilo de bagunça

Antes de qualquer linha ser editada, ele precisa saber ONDE aquela dependência é usada

O plan mode existe pra isso: no modo plan, o Claude lê arquivos, roda comandos shell pra explorar e escreve um plano, sem editar o código

As edições ficam bloqueadas até você aprovar o plano (com exceção de sessões rodando com bypass de permissões)

Pra entrar: pressione Shift+Tab, ou prefixe um único prompt com /plan

O Shift+Tab cicla entre os modos default, acceptEdits e plan

Uma alternativa (ou complemento) pro mapeamento é o subagente Explore

Ele tem ferramentas somente leitura (Write e Edit são negados) e serve pra descoberta de arquivos, busca de código e exploração da base

E tem um detalhe muito massa: cada subagente roda na própria janela de contexto, então todo o entulho da exploração não fica acumulado na conversa principal

O erro comum deste passo: apertar Shift+Tab de novo achando que está aprovando o plano

Não está

Pressionar Shift+Tab de novo SAI do plan mode sem aprovar nada

3. Leia o plano e edite o plano, não só aprove

Plano bom, num upgrade, responde três coisas: quais arquivos serão tocados, o que muda em cada um e como o resultado será verificado

Se faltar qualquer uma, o plano ainda não está pronto

E dá pra corrigir sem refazer o prompt: Ctrl+G abre o plano proposto no seu editor de texto padrão pra edição direta antes do Claude prosseguir

Use isso pra cortar o que você não quer que ele encoste

O erro comum deste passo: aprovar um plano que fala em "ajustar os usos afetados" sem listar quais são

"Usos afetados" é onde o escopo vaza 😀

4. Execute com o modo de permissão consciente

Os modos disponíveis são default, acceptEdits, plan, auto, dontAsk e bypassPermissions

O default aparece como "Manual" na CLI, nas extensões do VS Code e JetBrains e no app desktop

O acceptEdits auto-aprova operações de arquivo

Mas se liga nisso: outras ferramentas, como comandos Bash que não são operações de sistema de arquivos, continuam passando pelas permissões normais

O erro comum deste passo: achar que acceptEdits libera tudo e sair clicando em "sim" no automático quando o Bash pedir

Esse pedido de Bash é justamente o que merece sua atenção, pelo motivo que eu explico na próxima seção

5. Defina o critério de pronto, e ele tem que ser verificável

"Terminei" não é o agente dizer que terminou

Coloque a régua dentro do próprio pedido:

O trabalho só está concluído quando:
1. <seu comando de verificação> passar inteiro
2. nenhuma outra dependência tiver sido alterada
3. você me listar os arquivos tocados e o motivo de cada mudança
Se algum item falhar, relate a falha, não tente contornar mudando o teste.

Aquele item 3 parece firula e não é: é ele que te dá o resumo pra revisar antes de commitar

O erro comum deste passo: deixar o critério implícito na sua cabeça

O que não está escrito não é cobrado

6. Commite a unidade antes de ir pra próxima dependência

Upgrade verificado, commit feito, aí sim você abre o próximo

É o que transforma "uma dependência por vez" numa fila de pontos de retorno em vez de um bolo só

O erro comum deste passo: emendar a segunda dependência na mesma sessão sem commitar a primeira

Quando a segunda quebra, você perde as duas

Quebrou depois do upgrade: como voltar atrás sem perder o trabalho

Os sintomas são sempre parecidos

O build falha do nada, um teste que passava fica vermelho, ou você olha o diff e ele está espalhado por muito mais arquivo do que o combinado

A primeira reação errada é pedir pro agente "consertar"

Porque aí ele empilha correção em cima de mudança quebrada e o buraco fica mais fundo

A reação certa é voltar

Como usar o rewind:

Pra abrir o menu de rewind, rode /rewind ou pressione Esc duas vezes com o campo de prompt vazio

Detalhe que pega muita gente: se o campo tiver texto, o Esc duplo limpa o texto em vez de abrir o menu

O checkpointing captura automaticamente o estado do código antes de cada prompt enviado

E os checkpoints são salvos junto com a conversa, então dá pra fechar o terminal, retomar a sessão depois e ainda rebobinar

Na hora de restaurar você escolhe entre três caminhos:

• restaurar só a conversa, mantendo as mudanças de código
• restaurar só o código, mantendo a conversa
• restaurar os dois

As opções de código só aparecem quando o checkpoint selecionado tem mudanças de arquivo rastreadas pra reverter

Num upgrade que deu errado, "só a conversa" costuma ser o mais útil quando o código está bom e o rumo do papo é que azedou

A armadilha que ninguém avisa:

O checkpointing só rastreia mudanças feitas pelas ferramentas Write, Edit e NotebookEdit

Alterações feitas via comandos Bash (rm, mv, cp, echo > arquivo, sed -i) não são capturadas e NÃO podem ser desfeitas pelo rewind

Leia essa frase de novo pensando num upgrade de dependência

Boa parte do que acontece num upgrade acontece por comando de terminal

É por isso que aquele passo 4 pede atenção quando o Bash pede permissão: aquilo ali está fora da rede de segurança do rewind

E tem mais coisa que a doc é explícita em dizer que normalmente não é capturada: edições manuais feitas fora do Claude Code e edições de outras sessões concorrentes

Os limites da janela de segurança:

Dois números pra você não confiar demais:

• o Claude Code guarda snapshots de arquivo dos 100 checkpoints mais recentes de uma sessão
• os checkpoints são apagados junto com as sessões após 30 dias

Ou seja: o rewind é ótimo pro "opa, não era isso" de agora

Ele não é o seu histórico do projeto

A prevenção real continua sendo a mesma dupla: git por cima do checkpoint, e commit a cada unidade concluída

Quando vale planejar, quando dá pra pular e quando isolar em worktree

Nem todo upgrade merece o ritual completo

A documentação oficial dá a régua: planejar é mais útil quando você está incerto sobre a abordagem, quando a mudança altera múltiplos arquivos ou quando o código mexido não é familiar

E se der pra descrever o diff em uma frase, pule o plano

Simples assim

O caso do código não familiar é o mais traiçoeiro

É o mesmo terreno de quando você precisa mexer em código legado sem quebrar tudo: você não tem o mapa na cabeça, então a leitura prévia deixa de ser luxo

E quando eu quero testar sem sujar a branch?

Aí entra o git worktree

Que worktree? É um diretório de trabalho separado, com arquivos e branch próprios, compartilhando o histórico e o remote do repositório

Rodando cada sessão do Claude Code no seu próprio worktree, as edições de uma sessão nunca tocam os arquivos de outra

Pra abrir:

claude --worktree <nome>

Rodar o mesmo comando com outro nome em um segundo terminal abre outra sessão paralela isolada

E a documentação recomenda adicionar .claude/worktrees/ ao .gitignore

Pra upgrade isso é topzera: o major arriscado vive num worktree só dele, e se virar terra arrasada você simplesmente abandona aquilo sem ter contaminado nada

Dá pra automatizar a verificação?

Dá, com hook

O evento Stop dispara sempre que o Claude termina de responder, e a documentação traz exemplo de hook que verifica se todos os testes unitários passam

Tem também os hooks do tipo agent, que sobem um subagente pra ler arquivos e rodar comandos antes de devolver a decisão

Um aviso pra não criar expectativa errada: hooks PostToolUse disparam DEPOIS que a ferramenta já executou, e não desfazem a ação

Eles te avisam, não te salvam

Conclusão

No fim, upgrade seguro com agente se resume a quatro exigências

Escopo de uma dependência por vez, com nome e versão

Leitura antes da edição, via plan mode ou subagente read-only

Critério de pronto que é verificável, não uma opinião do agente

E caminho de volta garantido: commit por unidade, com o rewind como conforto extra e não como plano principal

O próximo passo prático é curtinho: escreve essas quatro exigências no CLAUDE.md do projeto, já que ele é lido no começo de toda sessão, e testa o fluxo no upgrade MENOS arriscado da sua lista

Quando o ritual já estiver no automático, aí sim você encara o major que está te olhando torto desde o mês passado 🙂

até o próximo post!