Sichere Changesets-Versionierung mit Claude Code

Claude Code kann Release-Arbeit stark beschleunigen, aber Versionsnummern dürfen nicht nebenbei entschieden werden. Ein Breaking Change als patch kann Nutzer-Builds zerstören. Ein internes Paket, das versehentlich auf npm landet, lässt sich nur schwer bereinigen. Changesets hilft, weil die Release-Absicht direkt im PR dokumentiert wird: welches Paket, welcher Bump, welcher Grund.

Dieser Leitfaden zeigt einen praktischen Ablauf mit Claude Code und Changesets: SemVer-Grundlagen, Release Notes, Monorepo-Packages, private und interne Packages, GitHub Actions, Risiken bei npm publish, CHANGELOG-Qualität und Review-Prompts gegen falsche KI-Bumps. Offizielle Referenzen sind SemVer, Changesets, die npm-Publishing-Dokumentation und GitHub Actions. Passend dazu: CLAUDE.md Best Practices, CI/CD Setup und Monorepo Management.

SemVer zuerst klären

SemVer bedeutet semantic versioning. 1.4.2 steht für major.minor.patch. patch behebt Fehler ohne Änderung des öffentlichen Vertrags. minor ergänzt rückwärtskompatible Funktionen. major kann Codeänderungen bei Nutzern erforderlich machen.

Der öffentliche Vertrag umfasst nicht nur Funktionsnamen. Auch React-Props, CSS-Tokens, CLI-Flags, Exit Codes, Default-Verhalten und exportierte TypeScript-Typen zählen dazu. Claude Code sollte diese Regel im Prompt sehen, sonst wird der Bump leicht aus Diff-Größe oder Commit-Text abgeleitet.

Typische Use Cases:

Use Case	Risiko	Prüfung durch Claude Code
UI-Package	Props, Varianten, CSS-Tokens, Peer Dependencies	passt der Bump zur öffentlichen API
CLI-Package	Flags, Befehle, Exit Codes	stimmen README, Tests und Code überein
Monorepo	interne Dependency Ranges	braucht ein abhängiges Package ebenfalls Release
Internes Package	versehentliches npm-Publishing	private, ignore, Registry, Token

Setup

Changesets installieren und initialisieren:

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

Startkonfiguration für .changeset/config.json:

{
  "$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 hält Package-Gruppen immer auf derselben Version. linked bump related Packages gemeinsam, behält aber eigene Versionsnummern. updateInternalDependencies steuert interne Workspace-Ranges. Das ist wichtig, weil ein Monorepo lokal mit workspace:* funktionieren kann, aber veröffentlichte Nutzer andere Ranges auflösen.

Gemeinsame Scripts:

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

Changeset schreiben

Für jeden PR mit Auswirkung auf ein öffentliches Package:

npx changeset

Beispiel:

---
"@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 ist minor, weil eine kompatible Option ergänzt wird. @myapp/utils ist patch, weil bestehendes Verhalten korrigiert wird. Entfernte Props, umbenannte CLI-Flags oder geänderte Defaults sind Kandidaten für major.

Prompt für Claude Code:

Lies den aktuellen PR-Diff und entwirf ein Changesets-Changeset.

Regeln:
- SemVer beachten: breaking change = major, kompatibles Feature = minor, Fix = patch
- package.json-Versionen nicht direkt bearbeiten
- npm publish nicht ausführen
- Packages mit private: true nicht in den Publish-Plan aufnehmen

Ausgabe:
- geänderte Packages
- empfohlener Bump je Package
- Begründung
- vorgeschlagener Inhalt für .changeset/*.md
- unsichere Punkte für menschliche Prüfung

Monorepos und interne Packages

In echten Repositories liegen publishbare Packages und Apps oft nebeneinander. @myapp/ui kann auf npm gehen, während @myapp/app nur deployed wird.

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

Changesets kann diese Packages ignorieren:

{
  "$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"]
}

Für interne Registries:

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

Token für interne Registry und öffentliches npm sollten getrennt sein.

GitHub Actions Release

changesets/action erstellt eine Version-PR und veröffentlicht nach dem Merge.

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 }}

PR-Check:

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

Dokumentations-PRs brauchen nicht immer ein Changeset. Skip-Regeln gehören aber ins Team-Policy-Dokument und nicht in spontane KI-Fixes.

CHANGELOG-Qualität

Schwach:

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

Update Button.

Besser:

---
"@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.

Review-Prompt:

Prüfe dieses Changeset als öffentliche CHANGELOG-Notiz.

Prüfe:
- verstehen Nutzer die Auswirkung
- passt der Text zum major/minor/patch-Bump
- gibt es Migration-Schritte, falls nötig
- ersetzen vage Wörter wie "updated" oder "improved" konkrete Details
- existieren Package-, Funktions- und Prop-Namen

Liste verdächtige Punkte als Fragen. Nicht stillschweigend umschreiben.

Häufige Fehler

Erstens: “Version erhöhen” fragen. Claude Code kann package.json direkt ändern und kein Changeset hinterlassen.

Zweitens: Breaking Change als minor veröffentlichen. Auch TypeScript-Typänderungen können Consumer-Builds brechen.

Drittens: internes Package veröffentlichen. Prüfen Sie private: true, ignore, publishConfig.registry, Token-Rechte und npm pack --dry-run.

Viertens: internen Dependency-Bump vergessen. Wenn @myapp/core geändert wird, braucht @myapp/cli eventuell ebenfalls ein Release.

Lokale Prüfung

Vor dem Release:

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

Der Snapshot prüft Versionen und CHANGELOG ohne Veröffentlichung. npm pack --dry-run zeigt den Tarball und hilft bei .env, großen Fixtures, internen Docs oder fehlenden Build-Artefakten.

Monetarisierung und Rollout

Ein sauberer Release-Prozess unterstützt Umsatz. UI Kit, CLI, SDK oder Template-Package können kostenpflichtige Produkte, Teamtraining oder Beratung tragen. Falsche Versionen beschädigen dagegen schnell Vertrauen.

Für reale Repositories hilft Claude Code Training und Beratung bei Changesets, CLAUDE.md, GitHub Actions, npm-Token-Grenzen, Review-Prompts und Monorepo-Regeln.

Praktisches Ergebnis

Ich habe den Ablauf mit einem kleinen npm-Workspace geprüft: Initialisierung, Changeset, changeset status, Release-PR und Publish-Guardrails. Claude Code erstellt gute Release-Note-Entwürfe aus Diffs, entscheidet SemVer aber nicht immer zuverlässig. Die Frage “Warum ist das kein Breaking Change?” macht fragwürdige minor- und patch-Bumps früher sichtbar.