Implementing Changeset Version Management: Claude Code 활용 가이드

Changesetで体系的なバージョン관리を実現する

Changesetは、패키지のバージョン관리とCHANGELOG생성を자동화するツールです。특히モノレポ環境で威力を発揮し、패키지間の依存関係を考慮した一貫性のある릴리스フローを구축할 수 있습니다。Claude Code는 설정からCI연동まで的確にサポートします。

初期セットアップ

Claude Code에セットアップを依頼합시다。

> Changesetをモノレポ프로젝트に도입して。
> GitHub Actionsでの自動릴리스、CHANGELOG생성を含めて。

# インストール
npm install -D @changesets/cli @changesets/changelog-github

# 初期化
npx changeset init

// .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": [],
  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
    "onlyUpdatePeerDependentsWhenOutOfRange": true
  }
}

Changesetの생성

변경内容を記述するChangeset파일の생성方法です。

# インタラクティブにChangesetを作成
npx changeset

<!-- .changeset/happy-dogs-fly.md -->
---
"@myapp/ui": minor
"@myapp/utils": patch
---

ボタンコンポーネントにバリアント「outline」を追加しました。
ユーティリティ関数の型定義を改善しました。

Claude Code에Changeset생성を依頼するプロンプト例です。

> 今回の변경に対するChangeset를 생성해줘。
> @myapp/uiにminorバージョンの변경、説明文も書いて。

npm scriptsの설정

// package.json
{
  "scripts": {
    "changeset": "changeset",
    "changeset:status": "changeset status",
    "version": "changeset version",
    "release": "changeset publish",
    "prerelease": "npm run build"
  }
}

GitHub Actionsでの自動릴리스

PRマージ時に自動でバージョンアップPRを생성し、マージ後にnpmへ公開する워크플로우です。

# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

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

permissions:
  contents: write
  pull-requests: write
  packages: write

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"

      - run: npm ci
      - run: npm run build

      - name: Create Release Pull Request or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          version: npm run version
          publish: npm run release
          title: "chore: バージョンアップ"
          commit: "chore: バージョンアップ"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

モノレポでの高度な설정

패키지間の연동を관리する설정パターンです。

// .changeset/config.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"
}

• fixed - 常に同じバージョンになる패키지グループ
• linked - バージョンが連動して上がる패키지グループ

プレ릴리스の관리

ベータ版やRC版の릴리스フローです。

# プレリリースモードに入る
npx changeset pre enter beta

# Changesetを追加
npx changeset

# プレリリースバージョンを適用
npx changeset version
# => 1.0.0 -> 1.1.0-beta.0

# 公開
npx changeset publish

# プレリリースモードを終了
npx changeset pre exit

Changesetの유효성 검사

PRにChangesetが含まれているかをCIでチェックする워크플로우です。

# .github/workflows/changeset-check.yml
name: Changeset Check

on:
  pull_request:
    branches: [main]

jobs:
  changeset-check:
    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
      - name: Check for changeset
        run: npx changeset status --since=origin/main

カスタムCHANGELOGフォーマット

CHANGELOG の출력を커스터마이징するパターンです。

// .changeset/changelog-config.ts
import type { ChangelogFunctions } from "@changesets/types";

const changelogFunctions: ChangelogFunctions = {
  getDependencyReleaseLine: async () => "",
  getReleaseLine: async (changeset, type) => {
    const [firstLine, ...rest] = changeset.summary
      .split("\n")
      .map((l) => l.trimEnd());

    const date = new Date().toISOString().slice(0, 10);

    let returnVal = `- ${firstLine}`;

    if (rest.length > 0) {
      returnVal += `\n${rest.map((l) => `  ${l}`).join("\n")}`;
    }

    return returnVal;
  },
};

export default changelogFunctions;

정리

Changesetは体系的なバージョン관리と릴리스フローを자동화するための強力なツールです。Claude Codeを활용すれば、初期설정からCI연동、モノレポ대응まで효율적으로구축가능합니다。

モノレポの관리手法はモノレポ관리가이드を、CI/CD파이프라인の설계はCI/CDセットアップ가이드를 참고하세요.Changesets공식 문서도 확인해 두세요.