Atualizar dependências com IA sem quebrar o build

Para atualizar dependências com IA, deixe o agente fazer a leitura e as edições repetitivas, e guarde as regras de segurança para você: um upgrade major por branch, o guia de migração lido antes de qualquer mudança no código e a suíte de testes como única prova de que funcionou. Agentes de código como Claude Code, Codex e Gemini CLI são bons na parte chata dos upgrades: renomear uma API em oitenta arquivos, adaptar o setup de testes a um novo runner, explicar um erro obscuro de peer dependency. Eles são ruins em uma coisa que importa muito aqui: lembram da versão antiga da biblioteca.

Este guia mostra um fluxo de trabalho que funciona tanto para um app pequeno quanto para um monorepo grande: inventário, triagem, agrupar as atualizações fáceis, isolar as difíceis, codemods, lockfiles, verificação, PRs de bots e alertas de segurança. Os exemplos usam npm e pnpm, com os equivalentes em Python onde eles diferem.

Por que upgrades de dependências dão errado com agentes

Upgrades parecem simples, e é exatamente por isso que dão errado. Os modos de falha mais comuns:

• Conhecimento desatualizado. Os dados de treinamento de um modelo param em algum ponto. Peça para ele ir para uma versão lançada depois disso e ele vai escrever com toda a confiança código para a versão que conhece.
• Escopo que cresce. “Atualize o React” vira React, o router, a biblioteca de testes, o ESLint e três plugins, tudo em um diff só.
• Mudar a régua. Um teste falha depois do upgrade, então o agente atualiza o snapshot, afrouxa a asserção ou pula o teste.
• Calar o instalador. Um conflito de peer dependency é “resolvido” com --force ou --legacy-peer-deps em vez de encontrar versões que realmente se encaixam.
• Caos no lockfile. O agente apaga o lockfile para fazer um erro de instalação sumir, e centenas de pacotes transitivos mudam de uma vez.

Cada passo abaixo existe para bloquear um desses.

Passo 1: faça um inventário

Comece com fatos, não com um prompt do tipo “atualize tudo”. Cada ecossistema tem um comando nativo que lista o que está defasado:

npm outdated            # Current, Wanted (highest in your range) and Latest
pnpm outdated           # add -r in a workspace
pip list --outdated     # for the active Python environment

Acrescente a visão de segurança:

npm audit
pip-audit               # PyPA tool: pip install pip-audit

Depois entregue a saída ao agente e peça uma triagem, não mudanças:

Here is the output of npm outdated and npm audit. Don't change anything yet.
Make a table with: package, current, wanted, latest, update type
(patch/minor/major), whether it's a direct or dev dependency, and a link to
its changelog or releases page. Flag anything with a security advisory.
Then propose an order: what can be batched, what needs its own branch.

É uma tarefa só de leitura, então é seguro rodá-la em modo de planejamento ou com uma configuração de permissão somente leitura. A tabela vira o seu plano e mostra logo cedo quais upgrades são realmente grandes.

Passo 2: agrupe as atualizações fáceis

Versões patch e minor deveriam ser retrocompatíveis. Na prática, geralmente são, e a suíte de testes pega o resto. Faça todas juntas, em uma branch:

git switch -c deps/minor-patch
npm update              # stays inside the ranges in package.json

Com pnpm, pnpm update faz o mesmo, pnpm update --interactive deixa você escolher, e pnpm update --latest atravessa versões major, então guarde esse para o Passo 3. Depois:

Run the full test suite, the type check and the build. If something fails,
find which package caused it and fix the code, not the tests. If a fix
needs more than a few lines, revert that one package to its previous
version and list it for a separate upgrade.

Essa última frase importa. Ela mantém o lote pequeno e sem graça, e manda qualquer surpresa para uma branch própria.

Passo 3: um upgrade major por branch

Uma versão major significa, por definição, breaking changes. Dê a cada uma sua própria branch e, se quiser rodar várias ao mesmo tempo, sua própria pasta com um git worktree:

git worktree add ../app-vite -b deps/vite-major
git worktree add ../app-eslint -b deps/eslint-major

Agora um agente atualiza a ferramenta de build, outro o linter, e sua pasta principal fica intocada. Se um upgrade virar um pântano, você apaga aquele worktree e a branch e não perde mais nada. Git worktrees para agentes em paralelo cobre o setup em mais detalhes.

Duas regras para majors:

• Um passo major de cada vez. Ir da versão 3 para a 6 de um salto empilha três conjuntos de breaking changes em um diff. Vá de 3 → 4, deixe verde, faça commit, depois 4 → 5.
• Atualize os pacotes relacionados juntos, e nada mais. Um framework e seus plugins oficiais muitas vezes precisam andar juntos. Tudo bem. Pacotes sem relação esperam.

Passo 4: leia o guia de migração antes de mexer no código

Este é o passo que resolve o problema do conhecimento desatualizado. Antes de o agente editar qualquer coisa, ele deve ler a documentação real da versão exata para a qual você está indo:

We're upgrading eslint from 8 to 9. Before editing any file:
1. Read the official migration guide and the changelog for 9.0.0.
2. List each breaking change that applies to this repo, with the files
   it affects (search the code to confirm).
3. Say what you will do for each one.
Use the installed package's docs and type definitions as the source of
truth, not what you remember about older versions. Wait for my OK.

Se o seu agente consegue navegar na web, ele busca o guia sozinho; se não, cole as partes relevantes ou aponte para as release notes em node_modules/<package>/CHANGELOG.md quando o pacote incluir uma. Um servidor MCP de documentação também ajuda aqui; veja os melhores servidores MCP para programar.

A lista que ele produz também é seu checklist de revisão depois: cada item deve corresponder a uma mudança no diff.

Passo 5: deixe o codemod ir primeiro

Muitos frameworks oferecem codemods: scripts que reescrevem código mecanicamente para uma nova versão. Um codemod é determinístico e o agente não é, então deixe o codemod fazer tudo o que conseguir e dê ao agente o que sobrar.

Dois exemplos conhecidos:

# Next.js: upgrades Next.js, React and React DOM and runs the codemods
npx @next/codemod upgrade major

# Angular: updates packages and runs their migrations
ng update @angular/core @angular/cli

Em outubro de 2026, a documentação do Next.js observa que @next/codemod upgrade roda de forma não interativa e aceita todos os padrões quando o stdin não é um terminal, que é o caso quando um agente o executa. Se você quiser escolher quais codemods aplicar, rode-o você mesmo primeiro e entregue o resultado ao agente.

Depois do codemod, faça commit e então peça ao agente para tratar os itens restantes do Passo 4: os casos que o codemod marcou ou pulou, wrappers próprios em volta da API antiga, setup de testes e arquivos de configuração. Manter a saída do codemod e as edições do agente em commits separados facilita muito a revisão. A mesma ideia vale para migrações maiores; refatorar código legado com IA e migrar JavaScript para TypeScript com IA se aprofundam em migrações passo a passo.

Passo 6: trate o lockfile como parte da mudança

O lockfile é o que faz “funciona na minha máquina” significar alguma coisa. Algumas regras que vale colocar no AGENTS.md ou CLAUDE.md:

## Dependencies
- Never delete package-lock.json / pnpm-lock.yaml to fix an install error.
- Don't use --force or --legacy-peer-deps without asking.
- Install with npm ci in CI; commit the lockfile with the package.json change.
- Don't add new dependencies during an upgrade task.

Quando uma instalação falhar por peer dependencies, peça ao agente para explicar o conflito em vez de forçá-lo. npm explain <package> (alias npm why) mostra por que um pacote está na árvore e quem exige qual versão; npm ls <package> mostra todas as cópias. Muitas vezes a correção real é atualizar o plugin que fixa o peer antigo, e isso pertence à mesma branch.

Na revisão, olhe também o diff do lockfile. Um bump minor de uma dependência direta que muda trezentas entradas transitivas merece uma pergunta.

Passo 7: verifique com suas próprias checagens

“Instala” não é estar pronto. Defina o que é pronto no prompt, em termos que o agente possa checar:

Done means: npm ci succeeds, npm test passes, tsc --noEmit passes,
npm run build passes, and no existing test file was changed except
where the migration guide requires it (explain each one).

Se sua suíte de testes é fraca em torno da biblioteca que você está atualizando, adicione alguns testes antes, na versão antiga, e mantenha-os verdes durante o upgrade. Para bibliotecas de UI, uma checagem rápida em um navegador real pega o que os testes unitários deixam passar: um agente com navegador pode abrir as páginas principais e relatar erros no console. Para ferramentas de build, compare o tamanho da saída do build antes e depois; um bundle com o dobro do tamanho é um bug mesmo que todos os testes passem.

Revise o diff com três perguntas: algum teste mudou, algum comportamento público mudou, e cada edição corresponde a um item da lista de breaking changes?

PRs de bots: Dependabot e Renovate mais um agente

Dependabot e Renovate são bons em abrir PRs de upgrade em um cronograma. O que eles não conseguem é corrigir o código quando o upgrade quebra algo. Essa é a parte que um agente pode assumir.

Uma configuração mínima do Dependabot que agrupa as atualizações fáceis em um PR:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      minor-and-patch:
        update-types:
          - "minor"
          - "patch"

O equivalente no Renovate parte do preset recomendado:

{
  "extends": ["config:recommended"],
  "packageRules": [
    { "matchUpdateTypes": ["minor", "patch"], "groupName": "minor and patch" }
  ]
}

Quando um PR de bot fica vermelho, o ciclo é assim:

gh pr checkout 123
gh pr checks 123              # find the failing run
gh run view <run-id> --log-failed   # the log of its failed jobs

This is a Dependabot PR that bumps zod to the next major. CI fails with the
log below. Find the root cause, read the release notes for the new version,
and fix our code so it works with the new version. Don't pin the old version
and don't change tests to hide the failure. Run the tests locally, then
summarize the change before you push.

Um detalhe: depois que você faz push dos seus próprios commits em uma branch do Dependabot, o Dependabot para de fazer rebase desse PR automaticamente, e @dependabot recreate jogaria sua correção fora. Faça o merge logo ou o rebase você mesmo. Para a versão geral desse ciclo, veja corrigir falhas de CI automaticamente com IA.

Alertas de segurança

npm audit lista vulnerabilidades conhecidas na sua árvore. Algumas coisas que o mantêm útil:

• Foque no que vai para produção. npm audit --omit=dev deixa de fora as dependências de desenvolvimento, e --audit-level=high faz o comando falhar só em severidade alta ou crítica, o que é um bom portão de CI.
• npm audit fix vs --force. O audit fix simples fica dentro dos ranges declarados. Com --force ele pode instalar versões semver-major; trate isso como um upgrade do Passo 3, não como uma correção rápida.
• Pacotes transitivos. Quando o pacote vulnerável está fundo na árvore e o pacote pai ainda não lançou uma correção, o campo overrides do npm no package.json (ou o pnpm.overrides do pnpm) pode forçar uma versão corrigida. Peça ao agente para adicionar um comentário ou uma issue explicando o motivo, para que o override seja removido depois.
• Pergunte se é alcançável. Peça ao agente para checar se o seu código realmente usa a função vulnerável. Isso não quer dizer que você pule a correção, mas mostra se ela é urgente hoje ou pode entrar no lote semanal.

Para Python, o pip-audit reporta o mesmo tipo de achado para um ambiente ou um requirements.txt, e pip-audit --fix tenta atualizar os pacotes afetados. O tema mais amplo de o que os próprios agentes podem instalar é tratado em segurança de agentes de código com IA.

Erros comuns

• “Atualize todas as dependências para a última versão” em um prompt. Você recebe um diff gigante e nenhuma forma de fazer bisect.
• Pular o guia de migração. O agente escreve código para a versão de que se lembra.
• Deixar testes mudarem em silêncio. Um snapshot atualizado tudo bem quando o guia explica a mudança; caso contrário, está escondendo uma regressão.
• Forçar o instalador. --force hoje é uma instalação quebrada para a próxima pessoa.
• Fazer merge de branches de upgrade paralelas sem testá-las juntas. Duas branches verdes podem ficar vermelhas quando combinadas; uma merge queue testa cada uma em cima da main mais recente.

Fazendo isso no AgentVera

AgentVera é um app desktop que roda CLIs de agentes de código como Claude Code, Codex e Gemini CLI lado a lado, com git integrado. Alguns de seus recursos se encaixam diretamente nesse fluxo:

• Um worktree por upgrade major. Crie um worktree pelo painel Git e inicie um agente nele com um clique; rode o upgrade do Vite em um painel e o do ESLint em outro.
• Uma regra semanal de dependências. Automações (Pro) podem iniciar um agente em um cronograma cron em seu próprio worktree. Um dos playbooks nativos é “update dependencies (minor and patch only)” (atualizar dependências, só minor e patch), e o resultado pode chegar como PR ou entrar na merge queue.
• CI vermelho para um agente. O centro de CI/CD lista execuções de GitHub Actions, GitLab CI e Jenkins; em uma execução com falha, “Fix with an agent” abre um agente Claude com os detalhes da execução e o final do log de até três jobs com falha. Uma automação também pode iniciar um agente quando o CI fica vermelho nas branches que você escolher.
• Verifique contra a sua definição de pronto. Escreva “testes, checagem de tipos e build passam; nenhum arquivo de teste mudou” na sua mensagem. O Verify transforma isso em critérios e, quando o turno termina, um verificador separado que não pode editar arquivos checa cada um com evidências.
• Revisão e merge queue. O code review lê o que o agente mudou com um segundo modelo, e a merge queue integra as branches de upgrade uma de cada vez em cima do alvo mais recente, com o seu comando de checagem rodando no resultado do merge.

Conclusão

Atualizar dependências com IA funciona quando você mantém o trabalho em pedaços pequenos: inventário primeiro, atualizações fáceis em um lote, cada major em sua própria branch, o guia de migração lido antes da primeira edição, o codemod antes do agente e os testes como juiz. O agente economiza a leitura e as cem pequenas edições; o processo mantém essas edições honestas. Quando o upgrade estiver pronto e você quiser deixar o app mais rápido também, leia como otimizar a performance do código com IA.

Para testar no seu próprio repositório, baixe o AgentVera.