Como usar o Claude Code para atualizar dependências do projeto (e onde parar)

Fala aí, beleza? Subir versão de biblioteca é aquele trabalho que ninguém acorda animado pra fazer

Abrir changelog de 12 pacotes, entender o que quebrou em cada salto, sair caçando chamada renomeada no projeto inteiro, e no fim descobrir que o build morreu por causa de um pacote que você nem lembrava que existia

É chato, é repetitivo, é leitura de documentação em massa

Ou seja: é exatamente o tipo de tarefa que um agente faz bem, DESDE QUE ele tenha limite claro

A ideia deste post é essa: o Claude Code mapeia, resume e aplica, mas quem decide o que entra no projeto é você

O que você precisa antes de começar

Não é setup complicado, mas pular isso aqui é pedir pra se ferrar depois

Projeto versionado em git

Você vai revisar diff o tempo todo, e vai querer isolar trabalho arriscado em outro diretório mais pra frente

Sem git, você não tem como comparar antes e depois de cada leva

Um comando de verificação que o próprio Claude consiga rodar

A documentação de boas práticas é direta nisso: a verificação pode ser suíte de testes, exit code de build, linter, script que compara saída com fixture ou screenshot

O ponto é que o agente faz o trabalho, roda a checagem, lê o resultado e itera até passar

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 não existe nada disso no projeto, o agente vira um cara chutando no escuro e te dizendo que deu certo

O CLAUDE.md do projeto

Ele guarda as instruções persistentes do projeto e o Claude lê no começo de cada sessão

É ali que mora coisa do tipo "nunca mexa nessas pastas" ou "o comando de teste é esse"

Ele faz parte do que o Claude Code lê como configuração e extensão, junto com settings.json, hooks, skills, comandos, subagentes, workflows, rules e a memória automática

Se você ainda não montou isso, vale antes dar uma olhada no fluxo completo no Claude Code e voltar aqui depois

Saber em qual modo de permissão você está

Esse é o mais importante da lista, porque é a trava que decide se o agente pode ou não tocar no seu código

Atualização de dependência começa em modo de leitura e só depois sobe pra edição

Nunca o contrário

Como atualizar dependências com o Claude Code passo a passo

A sequência abaixo vale pra projeto npm, que é o caso com comando documentado

Se você usa outro gerenciador, o raciocínio das etapas continua o mesmo, só os comandos mudam

1. Levante o que está velho. Antes de conversar com o agente, tenha o retrato do estado atual na mão. O npm outdated checa no registry quais pacotes instalados estão desatualizados, e o npm audit pede um relatório de vulnerabilidades conhecidas das dependências

npm outdated
npm audit

O erro comum deste passo: achar que essa saída é a lista completa

O npm outdated usa profundidade padrão 0, então mostra apenas dependências de primeiro nível desatualizadas, a menos que você mude a profundidade

E o npm audit checa dependencies, devDependencies, bundledDependencies e optionalDependencies, mas NÃO checa peerDependencies

Ou seja: é um bom ponto de partida, não é o mapa inteiro do território

2. Abra o plan mode e peça só o mapa. O plan mode faz o Claude pesquisar e propor mudanças sem aplicá-las: ele lê arquivos, roda comandos de exploração e escreve um plano, mas não edita o código-fonte até você aprovar. Dá pra entrar de duas formas: pressionando Shift+Tab até a barra de status mostrar o plan mode ativo, ou já iniciando a sessão assim

claude --permission-mode plan

O erro comum deste passo: mandar "atualiza tudo aí" num modo que já aceita edição

As próprias boas práticas oficiais avisam que deixar o Claude ir direto para o código produz código que resolve o problema errado, e recomendam o plan mode justamente pra separar exploração de execução

Aqui você quer leitura, não ação

3. Peça a separação por tipo de salto. Nem toda atualização tem o mesmo risco, e a régua pra isso já existe: o SemVer. A regra é que a versão MAJOR X (X.y.z, com X maior que 0) DEVE ser incrementada se qualquer mudança incompatível com versões anteriores for introduzida na API pública, e que MINOR e PATCH são zerados quando a MAJOR sobe

Leia o package.json e a saída do npm outdated que colei acima

Monte um plano separando as atualizações em levas:
1. patch e minor sem mudança incompatível
2. major, uma por vez, com o resumo do changelog e os pontos do nosso
   código que chamam a API que mudou

Não edite nenhum arquivo agora, só me mostre o plano

O erro comum deste passo: aceitar o resumo de changelog sem pedir onde exatamente o nosso projeto usa aquilo

Um "essa função foi removida" só é útil quando vem junto com os arquivos que chamam a função

4. Aprove o plano e aplique em levas pequenas. Uma leva por vez, revisável no diff. Comece pelas patch e minor, que é onde o risco é menor, e só depois encare os saltos MAJOR isolados. É aqui que faz sentido subir pro acceptEdits, que libera leituras, edições de arquivo e comandos comuns de sistema de arquivos

O erro comum deste passo: liberar a edição e sair da frente enquanto ele atravessa 20 pacotes de uma vez

Quando quebra, você não sabe qual dos 20 quebrou

5. Rode a verificação e exija evidência. Depois de cada leva, a checagem definida lá no começo tem que rodar. E a recomendação oficial é pedir a saída dos testes, o comando rodado e o que ele retornou, ou um screenshot do resultado, em vez de aceitar a afirmação de que funcionou

Rode a suíte de testes e me mostre o comando exato que você rodou
e a saída completa, incluindo o exit code

O erro comum deste passo: se contentar com "tudo certo, os testes passaram!"

Afirmação não é prova

Saída de terminal é

6. Se quebrar, volte pelo checkpoint. O Claude Code captura automaticamente o estado do código antes de cada prompt do usuário. Pra abrir o menu de rewind, é só pressionar Esc duas vezes com o campo de prompt vazio, ou rodar /rewind

Tem três detalhes que valem ouro aqui, e o terceiro já derrubou muita gente:

• o Claude Code guarda snapshots dos 100 checkpoints mais recentes da sessão
• os checkpoints são apagados junto com as sessões após 30 dias, e esse período muda pela configuração cleanupPeriodDays
• ao escolher Restore code ou Restore code and conversation, ele pula caminhos rastreados que sejam symlink ou hard link, e mostra um aviso

Ou seja: checkpoint é rede de segurança da sessão, não substituto de commit

Se o seu projeto tem link simbólico no meio do caminho, o rewind não vai desfazer aquilo pra você

Tome cuidado!

O que delegar ao agente e o que revisar você mesmo

A linha divisória é simples: leitura em massa e mudança mecânica são dele, decisão de risco é sua

Repare no padrão: tudo que dá pra provar com exit code ou saída de teste é delegável

Tudo que só se prova rodando a coisa de verdade continua sendo trabalho humano

Esse mesmo raciocínio de leva pequena e verificável é o que salva quando você vai refatorar um projeto legado, então se você já pegou esse jeito lá, aqui é o mesmo músculo

Quando isolar a atualização e quando deixar a automação abrir os PRs

Nem toda atualização merece o mesmo cuidado, e nem toda atualização precisa de você sentado na cadeira

Atualização arriscada que não pode tocar o código do dia a dia:

Use git worktree

Os git worktrees isolam sessões paralelas do Claude Code em diretórios de trabalho separados, pra que as edições de uma sessão não toquem os arquivos da outra

E o que é um worktree, afinal? É um diretório de trabalho separado, com seus próprios arquivos e sua própria branch, compartilhando o mesmo histórico e o mesmo remote do repositório

Na prática: o salto MAJOR daquela lib que você não confia acontece num diretório à parte, e o seu projeto do dia a dia segue intacto enquanto isso

Se você quer empurrar o isolamento pra dentro de um agente específico, dá pra dar a um subagente o seu próprio worktree, definindo isolation: worktree no frontmatter dele ou passando isolation: "worktree" na hora de invocar

Os subagentes personalizados do Claude Code moram em arquivos Markdown no diretório .claude/agents/

Massa, né? 😀

Fluxo contínuo, sem sessão manual:

Aí a conversa muda de figura

Se o que você quer é que alguém fique de olho o tempo todo e vá abrindo PR conforme sai versão nova, isso não é trabalho de sessão interativa

O Dependabot version updates abre pull requests automáticos pra manter as dependências atualizadas mesmo sem vulnerabilidade envolvida

Ele é habilitado ao commitar um arquivo dependabot.yml no diretório .github do repositório, na branch padrão, e a partir daí abre os PRs contra essa branch padrão

Dois números que você precisa saber antes de ligar isso: o limite padrão é de 5 pull requests abertos para version updates (dá pra configurar), e a frequência de checagem sai do schedule.interval dentro de cada entrada package-ecosystem, com os valores daily, weekly ou monthly

Como alternativa, tem o Renovate, ferramenta open source de atualização de dependências mantida pela Mend.io, com documentação em docs.renovatebot.com

E olha que combinação boa: a automação abre o PR dizendo o que subiu, e o Claude Code entra em cima daquele PR pra ler o changelog, mapear o impacto no seu código e rodar a verificação

Um faz o monitoramento, o outro faz a leitura pesada

Próximo passo

A régua deste post cabe em três linhas:

Separe pesquisa de execução, e o plan mode existe exatamente pra isso

Exija evidência (comando rodado e saída) em vez de afirmação de sucesso

E nunca aceite salto incompatível sem uma verificação que o próprio agente consiga rodar e você consiga conferir

O próximo passo é bem concreto e leva uns minutinhos: roda npm outdated e npm audit no seu projeto, abre o plan mode e pede SÓ o mapa das levas

Nenhuma edição, nenhum arquivo tocado, só o plano na tela

Se o plano já te mostrar um MAJOR que você não fazia ideia que estava te esperando, o post já valeu 🙂

até o próximo post!