Claude CodeでChangesets版管理を安全に回す実践ガイド

Claude Codeにリリース作業を任せると速くなります。ただし、versionは雑に扱うと事故になります。破壊的変更のpatch公開や社内packageのnpm誤公開は、あとから戻すのが大変です。

Changesetsは、.changeset/*.mdからversion、CHANGELOG、release PR、publishを組み立てるツールです。「どのpackageを、どのSemVer種別で、なぜ上げるか」をPRの時点で残せます。公式情報はSemVer、Changesets、npm package publishing、GitHub Actionsを基準にします。関連する土台はCLAUDE.mdベストプラクティス、CI/CDセットアップ、モノレポ管理です。

SemVerを先に固定する

SemVerは「意味のあるバージョン番号」の約束です。1.4.2ならmajor.minor.patchです。patchは公開APIを壊さない修正、minorは後方互換のある機能追加、majorは利用者のコード変更が必要になる可能性のある変更です。

公開APIは関数名だけではありません。React props、CSS token、CLI flag、exit code、default behavior、exportされたTypeScript型も含みます。Claude Codeにはこの判断基準を毎回渡します。

ユースケースは、UIライブラリのprops追加、CLIのflag変更、monorepoの内部依存更新、社内packageのnpm誤公開防止です。Claude Codeには公開API、READMEとテスト、依存packageのbump、privateやregistry設定を確認させます。

初期設定

まずChangesetsを入れます。

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

.changeset/config.jsonは次の形から始めると、public packageとmonorepoの両方に対応しやすいです。

{
  "$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は同じversionへそろえるpackage群です。linkedは関連packageを一緒にbumpします。updateInternalDependenciesはworkspace内の依存range設定です。曖昧だと、公開後の利用者環境でinstallできない落とし穴があります。

package 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ファイルを書く

公開packageに影響するPRでは、npx changesetを実行します。

npx changeset

---
"@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はvariant追加なのでminor、@myapp/utilsは既存関数の修正なのでpatchです。props削除、CLI flag改名、default behavior変更はmajor候補です。

Claude Codeには「versionを上げて」ではなく、レビューとして依頼します。

このPRのdiffを読み、Changesets用のchangeset案を作ってください。

ルール:
- SemVerに従う。破壊的変更はmajor、後方互換の機能追加はminor、修正はpatch
- package.jsonのversionを直接編集しない
- npm publishを実行しない
- private: trueのpackageを公開計画に入れない

出力:
- 変更されたpackage
- packageごとの推奨bump
- 判断理由
- .changeset/*.mdの本文案
- 人間が確認すべき不確実な点

monorepoと社内package

monorepoでは公開packageとdeploy専用appが混ざります。公開しないpackageはprivate: trueにし、社内registryへ出すpackageはpublishConfig.registryを明示します。公開npm用tokenと社内registry用tokenも分けます。Changesets側でも不要なrelease対象を除外します。

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

GitHub Actionsでreleaseを分ける

標準のchangesets/actionを使うと、未処理changesetがあるとversion PRを作り、そのPRがmergeされた後にpublishできます。

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側ではnpx changeset status --since=origin/mainをCIで実行し、changeset漏れを落とします。docsだけのPRはchangeset不要な場合もありますが、skip条件はチームルールとして明文化し、Claude Codeに広い例外を追加させないでください。

CHANGELOG品質と失敗例

悪いrelease noteはUpdate Button.のように、利用者に何も伝えません。よいrelease noteは、追加されたAPI、既存利用者への影響、必要なら移行手順を書きます。たとえばvariant="outline"を追加したなら、既存のsolidやghostは互換なのか、theme側で新しいCSS tokenを追加すべきなのかまで書きます。

よくある失敗は、package.jsonのversionを直接編集する、破壊的変更をminorにする、private packageをpublish対象にする、内部依存のbumpを忘れる、CHANGELOGが「改善しました」だけになる、の5つです。Masaの検証でも、実装者向けメモをそのままchangesetに入れると公開CHANGELOGとして読みにくくなりました。

確認promptは固定しておくと安定します。

このchangesetを公開CHANGELOGとしてレビューしてください。

観点:
- 利用者が影響範囲を理解できるか
- major/minor/patchの判断と本文が一致するか
- migrationが必要なら手順があるか
- 「改善」「更新」だけの曖昧な表現がないか
- package名、関数名、props名が実在するか

疑わしい点は質問として列挙してください。黙って修正しないでください。

手元での確認

release前にはnpm run changeset:status、npm test、npm run build、npm run version -- --snapshot canary、npm pack --dry-runを実行します。snapshotはversion計算とCHANGELOG確認に使います。npm pack --dry-runではtarballに入るファイルを確認し、.env、巨大fixture、社内docs、欠けているbuild成果物を見つけます。

Claude Codeに任せる範囲を決める

Changesets運用で大事なのは、AIに任せる作業と人間が決める作業を分けることです。Claude Codeに向いているのは、diffから変更候補を拾う、package名を確認する、CHANGELOG文を読みやすくする、CI設定の漏れを探す、といった補助作業です。一方で、majorにするかminorにするか、公開APIとして何を約束するか、社内だけのpackageを外部公開してよいか、という判断は責任者が決めるべきです。

実務では、PR本文に「このreleaseで利用者がする必要のある作業」を1行で書かせると判断が安定します。何も書けない変更はpatchの可能性が高く、移行手順が必要な変更はmajorを疑います。Claude Codeには、その説明とchangeset本文が矛盾していないかを見てもらいます。

また、npm tokenを扱うworkflowは特に慎重にします。pull requestから直接publishできる設計にせず、mainへのmerge後にだけrelease jobが走るようにします。private package、example app、docs siteはignoreに入れ、npm pack --dry-runで公開物を確認します。この手順を省くと、AIが正しいrelease noteを書いていても、公開対象の設定ミスで事故になります。

収益化と実測結果

安定したrelease flowは、UI kit、CLI、SDK、テンプレート販売、社内研修、導入コンサルの信頼に直結します。repositoryでChangesets、CLAUDE.md、GitHub Actions、npm token、reviewを整えるならClaude Code研修・導入相談を活用してください。

この記事は、npm workspaceでChangesets初期化、changeset作成、changeset status、release PR、publish guardrailを確認して整理しました。Claude Codeはdiffからrelease noteを起草できますが、SemVer判断を単独で任せると不安定です。「なぜこれは破壊的変更ではないのか」を説明させると、誤ったminorやpatchを見つけやすくなりました。