Versionado seguro con Changesets y Claude Code

Claude Code acelera mucho el trabajo de release, pero no conviene dejar que decida versiones sin reglas. Un cambio incompatible publicado como patch rompe builds de usuarios. Un paquete interno publicado por error en npm puede quedar expuesto durante mucho tiempo. Changesets ayuda porque obliga a escribir, dentro del PR, qué package cambia, qué bump necesita y por qué.

Esta guía explica un flujo práctico para combinar Claude Code con Changesets: SemVer, notas de release, packages en monorepo, packages privados o internos, GitHub Actions, riesgos de npm publish, calidad del CHANGELOG y prompts para evitar bumps inventados por IA. Usa como base la especificación SemVer, la documentación de Changesets, la guía de publicación de npm y la documentación de GitHub Actions. Para contexto de ClaudeCodeLab, revisa también buenas prácticas de CLAUDE.md, CI/CD con Claude Code y gestión de monorepos.

SemVer antes que automatización

SemVer significa versionado semántico. En 1.4.2, el formato es major.minor.patch. patch corrige errores sin cambiar el contrato público. minor añade funcionalidad compatible hacia atrás. major indica que el usuario puede tener que cambiar su código.

El contrato público no es solo el nombre de una función. También incluye props de React, tokens CSS, flags de CLI, códigos de salida, comportamiento por defecto y tipos TypeScript exportados. Claude Code necesita esa definición en el prompt; si no, puede juzgar por el tamaño del diff o por el mensaje del commit.

Casos reales donde Changesets aporta valor:

Caso	Riesgo	Qué puede revisar Claude Code
UI package	props, variants, CSS tokens, peer dependencies	Si el bump coincide con el cambio de API
CLI package	flags, comandos, exit codes	Si README, tests y código siguen alineados
Monorepo	rangos de dependencias internas	Si un package dependiente también debe subir
Package interno	publicación accidental	private, ignore, registry y token

Configuración inicial

Instala Changesets e inicializa la carpeta.

npm install -D @changesets/cli @changesets/changelog-github
npx changeset init

Un buen punto de partida para .changeset/config.json es:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

fixed agrupa packages que siempre comparten versión. linked sube packages relacionados juntos, pero mantiene sus números propios. updateInternalDependencies define cómo se actualizan los rangos internos del workspace. En un monorepo esto evita que algo compile localmente con workspace:* pero falle para usuarios externos.

Define scripts compartidos:

{
  "scripts": {
    "changeset": "changeset",
    "changeset:status": "changeset status --since=origin/main",
    "version": "changeset version",
    "release": "changeset publish",
    "build": "tsc -p tsconfig.json",
    "test": "vitest run"
  }
}

Crear el changeset

Para cada PR que afecte un package público:

npx changeset

Ejemplo:

---
"@myapp/ui": minor
"@myapp/utils": patch
---

Add the `outline` variant to Button and keep the existing `solid` and `ghost` variants compatible.

Fix `formatCurrency` so it handles zero-decimal currencies without rounding errors.

@myapp/ui recibe minor porque añade una opción compatible. @myapp/utils recibe patch porque corrige una función existente. Si eliminas un prop, renombras un flag de CLI o cambias un valor por defecto, debes tratarlo como candidato a major.

Prompt recomendado para Claude Code:

Lee el diff del PR actual y redacta un changeset para Changesets.

Reglas:
- Sigue SemVer: breaking change es major, feature compatible es minor, fix es patch
- No edites directamente la version de package.json
- No ejecutes npm publish
- No incluyas packages con private: true en el plan de publicación

Devuelve:
- packages modificados
- bump recomendado para cada package
- razonamiento
- contenido propuesto para .changeset/*.md
- puntos inciertos para revisión humana

Monorepos y packages internos

En un repositorio real suele haber packages publicables y apps que nunca deben publicarse. Por ejemplo, @myapp/ui puede ir a npm, mientras @myapp/app solo se despliega como web app.

{
  "name": "@myapp/app",
  "private": true,
  "version": "0.0.0",
  "scripts": {
    "build": "next build"
  },
  "dependencies": {
    "@myapp/ui": "workspace:*"
  }
}

También puedes excluirlos en Changesets:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [
    ["@myapp/core", "@myapp/cli"]
  ],
  "linked": [
    ["@myapp/ui", "@myapp/theme"]
  ],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@myapp/app", "@myapp/docs"]
}

Para un registry interno, declara el destino y separa el token del token de npm público.

{
  "name": "@my-company/internal-kit",
  "version": "1.8.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com",
    "access": "restricted"
  }
}

Release con GitHub Actions

changesets/action puede crear el PR de versionado y publicar después de mergearlo.

name: Release

on:
  push:
    branches:
      - main

concurrency: release-${{ github.ref }}

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"

      - run: npm ci
      - run: npm test
      - run: npm run build

      - name: Create release PR or publish to npm
        uses: changesets/action@v1
        with:
          version: npm run version
          publish: npm run release
          title: "chore: version packages"
          commit: "chore: version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Añade una comprobación en PR:

name: Changeset Check

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  changeset:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx changeset status --since=origin/main

Un PR solo de documentación puede no necesitar changeset. Si usas una label para omitir el check, debe estar definida por el equipo; Claude Code no debería inventar excepciones durante una corrección de CI.

Calidad del CHANGELOG

Una nota pobre dice:

---
"@myapp/ui": minor
---

Update Button.

Una nota útil explica impacto y migración:

---
"@myapp/ui": minor
---

Add `variant="outline"` to `Button`.

Existing `solid` and `ghost` variants keep the same props and class names. Teams using a custom theme should add `--button-outline-border` only if they want to override the default border color.

Prompt de revisión:

Revisa este changeset como texto público de CHANGELOG.

Comprueba:
- si el usuario entiende el impacto
- si el texto coincide con el bump major/minor/patch
- si hay pasos de migración cuando hacen falta
- si usa palabras vagas como "updated" o "improved"
- si existen los nombres de packages, funciones y props

Lista los puntos sospechosos como preguntas. No los reescribas en silencio.

Errores frecuentes

El primer error es pedir “sube la versión”. Claude Code puede editar package.json directamente y no dejar changeset.

El segundo es publicar un breaking change como minor. Cambios de tipos también pueden romper builds.

El tercero es publicar un package interno. Revisa private: true, ignore, publishConfig.registry, permisos del token y npm pack --dry-run.

El cuarto es olvidar un dependency bump interno. Si cambia @myapp/core, quizá @myapp/cli también necesita release.

Verificación local

Antes de publicar:

npm run changeset:status
npm test
npm run build
npm run version -- --snapshot canary
git diff -- package.json package-lock.json pnpm-lock.yaml yarn.lock CHANGELOG.md
npm pack --dry-run

El snapshot comprueba cálculo de versión y CHANGELOG sin publicar. npm pack --dry-run muestra el tarball: úsalo para detectar .env, fixtures enormes, docs internas o artefactos de build faltantes.

Monetización y adopción

Un flujo de release fiable sostiene ingresos. UI kits, CLIs, SDKs y templates pueden convertirse en productos de pago, formación interna y consultoría. Pero un versionado erróneo destruye confianza.

Para aplicarlo en un repositorio real, formación y consultoría Claude Code puede ayudar a definir Changesets, CLAUDE.md, GitHub Actions, tokens npm, prompts de review y reglas de monorepo.

Resultado práctico

Probé este flujo con un workspace npm pequeño: inicialización, changeset, changeset status, release PR y revisión de publish. Claude Code redacta buenas notas desde un diff, pero no siempre acierta SemVer. Pedirle que explique por qué un cambio no es breaking ayuda a detectar bumps minor o patch dudosos antes de llegar a npm.