Gestiona dependencias con Claude Code: npm, pnpm, Yarn y CI

Gestionar dependencias no es actualizar todo a ciegas

En un proyecto JavaScript o TypeScript, las dependencias cambian mas rapido que muchas partes de la aplicacion. React, Vite, TypeScript, ESLint, librerias de pruebas, SDKs de pagos, paquetes de UI y plugins de build pueden convertir una app pequena en un arbol de cientos de paquetes directos y transitivos.

Claude Code ayuda mucho, pero su mejor papel no es ejecutar npm install paquete@latest sin contexto. Lo util es pedirle que inspeccione el repositorio, detecte el package manager, proteja el lockfile, clasifique cambios patch/minor/major, revise vulnerabilidades, analice PRs de Renovate o Dependabot y exija pruebas claras antes de mezclar.

Un lockfile fija las versiones exactas y los hashes de integridad que se instalaron. npm usa package-lock.json, pnpm usa pnpm-lock.yaml y Yarn usa yarn.lock. package.json indica rangos aceptables; el lockfile indica el resultado real. En CI queremos verificar ese resultado, no reescribirlo.

Para el flujo completo de pipelines, lee tambien Claude Code CI/CD setup. Si trabajas con monorepos, la guia de pnpm workspace con Claude Code conecta directamente con este articulo.

---

El flujo recomendado

Divide el trabajo en cinco pasos: inspeccion, plan, PR de actualizacion, CI y revision humana.

flowchart LR
  scan["Inspeccion\noutdated / audit"] --> plan["Plan\npatch / minor / major"]
  plan --> pr["PR de actualizacion\nRenovate / Dependabot"]
  pr --> ci["CI\ninstall / test / build"]
  ci --> review["Revision con Claude Code\nriesgos y evidencia"]
  review --> merge["Decision humana\nmerge o rechazo"]

La primera peticion a Claude Code debe ser de lectura, no de edicion.

claude -p "
Inspect dependency management in this repository. Do not edit files yet.
Report package manager, lockfile, outdated direct dependencies,
security audit command, scripts that must pass, and risky major updates.
Return file paths and exact commands.
"

Este prompt evita que Claude Code haga cambios grandes antes de entender el repositorio. Primero inventario, despues actualizacion.

---

npm, pnpm y Yarn en una tabla

No mezcles package managers dentro del mismo proyecto. Cada herramienta tiene su lockfile y su comando correcto para CI.

Herramienta	Lockfile	Instalacion en CI	Paquetes antiguos	Auditoria
npm	package-lock.json	npm ci	npm outdated	npm audit --audit-level=high
pnpm	pnpm-lock.yaml	pnpm install --frozen-lockfile	pnpm outdated --format table	pnpm audit --audit-level high
Yarn modern	yarn.lock	yarn install --immutable	yarn up -i o yarn up <pattern>	yarn npm audit --recursive --severity high

La documentacion oficial de npm presenta npm ci como el comando para entornos automatizados y explica que falla si package.json y el lockfile no coinciden. pnpm usa --frozen-lockfile para la misma idea. Yarn usa --immutable para abortar si el lockfile tendria que cambiar. La regla practica: el PR actualiza el lockfile; CI comprueba que el lockfile es reproducible.

---

Script listo para copiar

Guarda esto como scripts/verify-deps.mjs. Detecta npm, pnpm o Yarn, ejecuta instalacion congelada, auditoria de severidad alta y los scripts typecheck, test y build si existen.

#!/usr/bin/env node
import { existsSync, readFileSync } from "node:fs";
import { spawnSync } from "node:child_process";

function readPackageJson() {
  return JSON.parse(readFileSync("package.json", "utf8"));
}

function detectPackageManager(pkg) {
  const declared = pkg.packageManager || "";
  if (declared.startsWith("pnpm@")) return "pnpm";
  if (declared.startsWith("yarn@")) return "yarn";
  if (declared.startsWith("npm@")) return "npm";
  if (existsSync("pnpm-lock.yaml")) return "pnpm";
  if (existsSync("yarn.lock")) return "yarn";
  if (existsSync("package-lock.json")) return "npm";
  throw new Error("No package manager or lockfile detected.");
}

function run(command, args) {
  const label = [command, ...args].join(" ");
  console.log(`\n$ ${label}`);
  const result = spawnSync(command, args, {
    stdio: "inherit",
    shell: process.platform === "win32",
  });
  if (result.status !== 0) throw new Error(`Command failed: ${label}`);
}

const pkg = readPackageJson();
const manager = detectPackageManager(pkg);

const installCommands = {
  npm: ["npm", ["ci"]],
  pnpm: ["pnpm", ["install", "--frozen-lockfile"]],
  yarn: ["yarn", ["install", "--immutable"]],
};

const auditCommands = {
  npm: ["npm", ["audit", "--audit-level=high"]],
  pnpm: ["pnpm", ["audit", "--audit-level", "high"]],
  yarn: ["yarn", ["npm", "audit", "--recursive", "--severity", "high"]],
};

const scriptCommands = {
  npm: (name) => ["npm", ["run", name]],
  pnpm: (name) => ["pnpm", ["run", name]],
  yarn: (name) => ["yarn", ["run", name]],
};

run(...installCommands[manager]);
run(...auditCommands[manager]);

for (const name of ["typecheck", "test", "build"]) {
  if (pkg.scripts?.[name]) run(...scriptCommands[manager](name));
  else console.log(`\n- skip ${name}: script not found`);
}

console.log(`\nDependency verification passed with ${manager}.`);

Anadelo a package.json:

{
  "scripts": {
    "deps:verify": "node scripts/verify-deps.mjs"
  }
}

El detalle importante es que este script verifica, no actualiza. Asi todos los cambios pasan por la misma puerta: los de Claude Code, Renovate, Dependabot y los humanos.

---

Tres casos de uso reales

Caso 1: una app pequena que necesita actualizar herramientas de desarrollo. ESLint, Prettier, Vite, Vitest o TypeScript se pueden agrupar cuando son patch/minor. No metas cambios major en el mismo PR.

claude -p "
Prepare a dependency update plan for devDependencies only.
Group patch and minor updates for lint/test/build tools.
Do not update major versions.
Run the dependency verification script after changes.
"

Caso 2: una alerta de seguridad. No empieces con audit fix --force. Primero lee el informe JSON y pide a Claude Code que distinga dependencias directas, transitivas, version instalada, version corregida y si basta con actualizar el lockfile.

npm audit --json
pnpm audit --json
yarn npm audit --recursive --json

Caso 3: workspace o monorepo. La gestion de dependencias tambien incluye fronteras internas. packages/ui no deberia importar de apps/web, y los paquetes internos deberian usar workspace:*.

claude -p "
Inspect this workspace before dependency updates.
Find packages/* importing from apps/*, internal dependencies not using workspace:*,
duplicated versions of react/typescript/eslint, and scripts that should use filters.
Do not edit files.
"

---

Renovate y Dependabot

Renovate sirve cuando quieres reglas finas. Esta configuracion deja los major para revision humana y permite automerge en herramientas de desarrollo de bajo riesgo cuando CI pasa.

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "dependencyDashboard": true,
  "lockFileMaintenance": {
    "enabled": true,
    "schedule": ["before 5am on monday"],
    "automerge": true
  },
  "packageRules": [
    {
      "matchManagers": ["npm"],
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["patch", "minor"],
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "labels": ["dependency", "major-update"],
      "automerge": false
    }
  ]
}

Dependabot es mas simple y suele bastar para empezar en GitHub.

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    groups:
      dev-tooling:
        dependency-type: "development"
        update-types:
          - "minor"
          - "patch"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "monthly"

Tambien actualiza GitHub Actions. Si actions/setup-node se queda antiguo, tu pipeline de dependencias tambien envejece.

---

CI para bloquear falsas victorias

name: dependency-check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  verify-dependencies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: corepack enable
      - run: node scripts/verify-deps.mjs

Puedes anadir cache despues, pero primero valida que el flujo sea reproducible sin depender de estado viejo.

---

Fallos concretos que debes evitar

El primer fallo es usar npm install en CI. Usa npm ci. El segundo es usar audit fix --force sin clasificar el informe. El tercero es mezclar varios major en un solo PR. El cuarto es revisar solo package.json e ignorar el lockfile. El quinto es tratar igual una actualizacion de ESLint y una de un SDK de autenticacion. El sexto aparece en sitios de contenido: un cambio en MDX, CSS o build puede romper bloques de codigo, anuncios o CTAs. Para eso ayuda el flujo de recibo de verificacion.

---

Prompt de revision de PR

claude -p "
Review this dependency update PR.
Focus on package.json, lockfile, CI config, and test output.
Report updated packages, direct vs transitive changes, major updates,
peer dependency changes, commands that passed or failed, and manual checks.
Do not change files unless there is a blocking issue.
"

Una buena revision deja evidencia: que cambio, que paso en CI, que fallo y que debe mirar una persona antes de hacer merge.

---

Referencias y siguiente paso

Consulta npm ci, npm audit, pnpm install, pnpm audit, yarn install, yarn npm audit, Claude Code CLI, Dependabot options y Renovate automerge.

Para ampliar el flujo en este sitio, sigue con auditoria de seguridad con Claude Code y buenas practicas de CLAUDE.md. Si tu equipo necesita reglas para un repositorio real, la pagina de formacion y consultoria es el camino natural.

Resultado al probar este flujo

El mejor cambio fue separar actualizacion y verificacion. Claude Code puede planear y revisar, pero deps:verify y el diff del lockfile deciden si el PR esta listo. Al dejar los major fuera del automerge, tambien se vuelve mucho mas facil encontrar la causa cuando algo falla.