Actualizar dependencias con IA sin romper el build

Para actualizar dependencias con IA, deja que el agente haga la lectura y las ediciones repetitivas, y quédate tú con las reglas de seguridad: un major por rama, la guía de migración leída antes de cambiar código y la suite de tests como única prueba de que ha funcionado. Los agentes de programación como Claude Code, Codex y Gemini CLI son buenos en la parte tediosa de las actualizaciones: renombrar una API en ochenta archivos, adaptar la configuración de tests a un runner nuevo, explicar un error críptico de peer dependencies. Son malos en una cosa que aquí importa mucho: recuerdan la versión antigua de la librería.

Esta guía recorre un flujo de trabajo que sirve tanto para una app pequeña como para un monorepo grande: inventario, clasificación, agrupar las actualizaciones fáciles, aislar las difíciles, codemods, lockfiles, verificación, PRs de bots y avisos de seguridad. Los ejemplos usan npm y pnpm, con equivalentes de Python donde difieren.

Por qué las actualizaciones de dependencias salen mal con agentes

Las actualizaciones parecen sencillas, y por eso salen mal. Los fallos habituales:

• Conocimiento desfasado. Los datos de entrenamiento de un modelo terminan en algún momento. Pídele que se mueva a una versión publicada después y escribirá con total seguridad código para la versión que conoce.
• Alcance que se desborda. «Actualiza React» se convierte en React, el router, la librería de tests, ESLint y tres plugins, todo en un solo diff.
• Mover la portería. Un test falla tras la actualización, así que el agente actualiza el snapshot, relaja la aserción o salta el test.
• Silenciar al instalador. Un conflicto de peer dependencies se «arregla» con --force o --legacy-peer-deps en lugar de buscar versiones que de verdad encajen entre sí.
• Caos en el lockfile. El agente borra el lockfile para que desaparezca un error de instalación, y cientos de paquetes transitivos cambian a la vez.

Cada paso de abajo está ahí para bloquear uno de estos fallos.

Paso 1: haz un inventario

Empieza con hechos, no con un prompt como «actualízalo todo». Cada ecosistema tiene un comando integrado que lista lo que está desactualizado:

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

Añade la vista de seguridad:

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

Después pásale la salida al agente y pídele una clasificación, no cambios:

Aquí tienes la salida de npm outdated y npm audit. No cambies nada todavía.
Haz una tabla con: paquete, versión actual, wanted, latest, tipo de
actualización (patch/minor/major), si es dependencia directa o de desarrollo,
y un enlace a su changelog o página de releases. Marca todo lo que tenga un
aviso de seguridad. Luego propón un orden: qué se puede agrupar y qué
necesita su propia rama.

Es un trabajo de solo lectura, así que es seguro ejecutarlo en un modo de planificación o con permisos de solo lectura. La tabla se convierte en tu plan y te muestra pronto qué actualizaciones son realmente grandes.

Paso 2: agrupa las actualizaciones fáciles

Se supone que las versiones patch y minor son retrocompatibles. En la práctica suelen serlo, y la suite de tests detecta el resto. Hazlas juntas, en una sola rama:

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

Con pnpm, pnpm update hace lo mismo, pnpm update --interactive te deja elegir y pnpm update --latest cruza versiones major, así que guarda ese para el Paso 3. Después:

Ejecuta la suite de tests completa, la comprobación de tipos y el build. Si
algo falla, averigua qué paquete lo causó y arregla el código, no los tests.
Si un arreglo necesita más de unas pocas líneas, devuelve ese paquete a su
versión anterior y apúntalo para una actualización por separado.

Esa última frase importa. Mantiene el lote pequeño y aburrido, y saca cualquier sorpresa a su propia rama.

Paso 3: un major por rama

Una versión major implica, por definición, cambios incompatibles. Dale a cada una su propia rama y, si quieres ejecutar varias a la vez, su propia carpeta con un git worktree:

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

Ahora un agente actualiza la herramienta de build, otro el linter, y tu carpeta principal queda intacta. Si una actualización se convierte en un pantano, borras ese worktree y esa rama y no pierdes nada más. Git worktrees para agentes en paralelo explica la configuración con más detalle.

Dos reglas para los majors:

• Un salto major cada vez. Pasar de la versión 3 a la 6 de golpe apila tres conjuntos de cambios incompatibles en un solo diff. Ve de 3 a 4, deja todo en verde, haz commit, y luego de 4 a 5.
• Actualiza juntos los paquetes relacionados, y nada más. Un framework y sus plugins oficiales a menudo tienen que avanzar a la par. Eso está bien. Los paquetes que no tienen relación esperan.

Paso 4: lee la guía de migración antes de tocar código

Este es el paso que resuelve el problema del conocimiento desfasado. Antes de que el agente edite nada, debe leer la documentación real de la versión exacta a la que te mueves:

Vamos a actualizar eslint de la 8 a la 9. Antes de editar ningún archivo:
1. Lee la guía de migración oficial y el changelog de la 9.0.0.
2. Enumera cada cambio incompatible que afecte a este repositorio, con los
   archivos afectados (busca en el código para confirmarlo).
3. Di qué vas a hacer con cada uno.
Usa la documentación y las definiciones de tipos del paquete instalado como
fuente de verdad, no lo que recuerdes de versiones anteriores. Espera mi OK.

Si tu agente puede navegar, descargará la guía por su cuenta; si no, pega las partes relevantes o indícale las notas de versión en node_modules/<package>/CHANGELOG.md cuando el paquete incluya una. Un servidor MCP de documentación también ayuda aquí; consulta los mejores servidores MCP para programar.

La lista que produce es también tu checklist de revisión para después: cada punto debe corresponder a un cambio en el diff.

Paso 5: deja que el codemod vaya primero

Muchos frameworks incluyen codemods: scripts que reescriben código de forma mecánica para una versión nueva. Un codemod es determinista y el agente no, así que deja que el codemod haga todo lo que pueda y dale al agente lo que quede.

Dos ejemplos conocidos:

# 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

A octubre de 2026, la documentación de Next.js indica que @next/codemod upgrade se ejecuta de forma no interactiva y acepta todos los valores por defecto cuando stdin no es una terminal, que es lo que ocurre cuando lo ejecuta un agente. Si quieres elegir qué codemods se aplican, ejecútalo tú primero y pásale el resultado al agente.

Después del codemod, haz commit y pide al agente que se ocupe de los puntos restantes del Paso 4: los casos que el codemod marcó u omitió, los wrappers propios sobre la API antigua, la configuración de tests y los archivos de configuración. Mantener la salida del codemod y las ediciones del agente en commits separados facilita mucho la revisión. La misma idea vale para migraciones más grandes; refactorizar código legacy con IA y migrar JavaScript a TypeScript con IA profundizan en las migraciones paso a paso.

Paso 6: trata el lockfile como parte del cambio

El lockfile es lo que hace que «en mi máquina funciona» signifique algo. Algunas reglas que vale la pena poner en AGENTS.md o CLAUDE.md:

## Dependencias
- Nunca borres package-lock.json / pnpm-lock.yaml para arreglar un error de instalación.
- No uses --force ni --legacy-peer-deps sin preguntar.
- Instala con npm ci en CI; haz commit del lockfile junto con el cambio de package.json.
- No añadas dependencias nuevas durante una tarea de actualización.

Cuando una instalación falla por peer dependencies, pide al agente que explique el conflicto en lugar de forzarlo. npm explain <package> (alias npm why) muestra por qué un paquete está en el árbol y quién requiere qué versión; npm ls <package> muestra todas las copias. A menudo el arreglo real es actualizar el plugin que fija el peer antiguo, y eso pertenece a la misma rama.

Cuando revises, mira también el diff del lockfile. Un bump minor de una dependencia directa que cambia trescientas entradas transitivas merece una pregunta.

Paso 7: verifica con tus propias comprobaciones

«Se instala» no significa terminado. Define qué es terminado en el prompt, en términos que el agente pueda comprobar:

Terminado significa: npm ci funciona, npm test pasa, tsc --noEmit pasa,
npm run build pasa, y no se ha cambiado ningún archivo de test existente
salvo donde lo exija la guía de migración (explica cada caso).

Si tu suite de tests es escasa alrededor de la librería que actualizas, añade primero algunos tests, sobre la versión antigua, y mantenlos en verde durante toda la actualización. Para librerías de UI, una comprobación rápida en un navegador real detecta lo que los tests unitarios no ven: un agente con navegador puede abrir las páginas principales e informar de los errores de consola. Para herramientas de build, compara el tamaño del resultado antes y después; un bundle que dobla su tamaño es un bug aunque pasen todos los tests.

Revisa el diff con tres preguntas: ¿ha cambiado algún test?, ¿ha cambiado algún comportamiento público? y ¿cada edición corresponde a un punto de la lista de cambios incompatibles?

PRs de bots: Dependabot y Renovate más un agente

Dependabot y Renovate son buenos abriendo PRs de actualización de forma periódica. Lo que no pueden hacer es arreglar el código cuando la actualización rompe algo. Esa es la parte que puede asumir un agente.

Una configuración mínima de Dependabot que agrupa las actualizaciones fáciles en un solo PR:

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

El equivalente en Renovate parte de su preset recomendado:

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

Cuando un PR de un bot se pone en rojo, el ciclo es así:

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

Este es un PR de Dependabot que sube zod al siguiente major. CI falla con el
log de abajo. Encuentra la causa raíz, lee las notas de versión de la nueva
versión y arregla nuestro código para que funcione con ella. No fijes la
versión antigua ni cambies tests para ocultar el fallo. Ejecuta los tests en
local y resume el cambio antes de hacer push.

Un detalle: en cuanto subes tus propios commits a una rama de Dependabot, Dependabot deja de hacer rebase de ese PR automáticamente, y @dependabot recreate tiraría tu arreglo. Haz merge pronto o haz el rebase tú mismo. Para la versión general de este ciclo, consulta arreglar fallos de CI automáticamente con IA.

Avisos de seguridad

npm audit lista las vulnerabilidades conocidas de tu árbol. Algunas cosas que lo mantienen útil:

• Céntrate en lo que se despliega. npm audit --omit=dev deja fuera las dependencias de desarrollo, y --audit-level=high hace que el comando solo falle con severidad alta o crítica, lo que es un filtro sensato para CI.
• npm audit fix frente a --force. El audit fix normal se queda dentro de tus rangos declarados. Con --force puede instalar versiones semver-major; trátalo como una actualización del Paso 3, no como un arreglo rápido.
• Paquetes transitivos. Cuando el paquete vulnerable está en lo profundo del árbol y su padre no ha publicado un arreglo, el campo overrides de npm en package.json (o pnpm.overrides en pnpm) puede forzar una versión parcheada. Pide al agente que añada un comentario o un issue explicando el motivo, para que el override se elimine más adelante.
• Pregunta si es alcanzable. Haz que el agente compruebe si tu código usa de verdad la función vulnerable. Eso no significa que te saltes el arreglo, pero te dice si es urgente hoy o puede ir en el lote semanal.

En Python, pip-audit informa del mismo tipo de hallazgos para un entorno o un requirements.txt, y pip-audit --fix intenta actualizar los paquetes afectados. El tema más amplio de qué deberían poder instalar los propios agentes se trata en seguridad de los agentes de programación con IA.

Errores comunes

• «Actualiza todas las dependencias a la última versión» en un solo prompt. Obtienes un diff gigante y ninguna forma de bisecarlo.
• Saltarse la guía de migración. El agente escribe código para la versión que recuerda.
• Dejar que los tests cambien en silencio. Un snapshot actualizado está bien cuando la guía explica el cambio; si no, está ocultando una regresión.
• Forzar al instalador. El --force de hoy es la instalación rota de la próxima persona.
• Hacer merge de ramas de actualización paralelas sin probarlas juntas. Dos ramas en verde pueden ponerse en rojo al combinarse; una cola de merge prueba cada una sobre el último main.

Cómo hacerlo en AgentVera

AgentVera es una app de escritorio que ejecuta CLIs de agentes de programación como Claude Code, Codex y Gemini CLI uno al lado de otro, con git integrado. Varias de sus funciones encajan directamente con este flujo:

• Un worktree por cada major. Crea un worktree desde el panel de Git e inicia un agente en él con un clic; ejecuta la actualización de Vite en un panel y la de ESLint en otro.
• Una regla semanal de dependencias. Las automatizaciones (Pro) pueden iniciar un agente según un calendario cron en su propio worktree. Uno de los playbooks integrados es «actualizar dependencias (solo minor y patch)», y el resultado puede llegar como PR o entrar en la cola de merge.
• CI en rojo, directo a un agente. El centro de CI/CD lista las ejecuciones de GitHub Actions, GitLab CI y Jenkins; en una ejecución fallida, «Arreglar con un agente» abre un agente de Claude con los detalles de la ejecución y el final del log de hasta tres jobs fallidos. Una automatización también puede iniciar un agente cuando CI se pone en rojo en las ramas que elijas.
• Verifica según tu definición de terminado. Escribe «tests, comprobación de tipos y build pasan; ningún archivo de test cambiado» en tu mensaje. Verify lo convierte en criterios y, al terminar el turno, un verificador independiente que no puede editar archivos comprueba cada uno con pruebas.
• Revisión y cola de merge. La revisión de código lee lo que cambió el agente con un segundo modelo, y la cola de merge integra las ramas de actualización una a una sobre el destino más reciente, ejecutando tu comando de comprobación sobre el resultado combinado.

Para terminar

Actualizar dependencias con IA funciona cuando mantienes pequeña la forma del trabajo: primero el inventario, las actualizaciones fáciles en un lote, cada major en su propia rama, la guía de migración leída antes de la primera edición, el codemod antes que el agente y los tests como juez. El agente te ahorra la lectura y las cien ediciones pequeñas; el proceso mantiene esas ediciones honestas. Cuando termines la actualización y quieras además que la app vaya más rápida, lee cómo optimizar el rendimiento del código con IA.

Para probarlo en tu propio repositorio, descarga AgentVera.