arc-conventional-commits

Conventional Commits + Semantic Release

このスキルでは、Conventional Commits v1.0.0 仕様とsemantic-releaseを使用して、 CI による自動バージョン管理を設定します。

ワークフローは対話形式で進めます。既存のツールの削除など、破壊的な変更を行う前には必ずユーザーに確認してください。

以下の 5 つのフェーズを順番に進めてください。

---

フェーズ 1 — 既存のバージョン管理ツールを検出する

何かをインストールする前に、リポジトリに既存のバージョン管理基盤がないかスキャンしてください。 これにより競合を防ぎ、ユーザーがスムーズに移行できるようになります。

Glob と Read を使って、以下のツールを確認してください。

ツール	ファイル／パターン
semantic-release	.releaserc、.releaserc.json、.releaserc.yml、.releaserc.yaml、release.config.js、release.config.cjs
standard-version	.versionrc、.versionrc.json、.versionrc.js
changesets	.changeset/ ディレクトリ
lerna	lerna.json
release-please	release-please-config.json、.release-please-manifest.json

また、package.json を読み、以下を確認してください。

• devDependencies：semantic-release、standard-version、@changesets/cli、@changesets/changelog-github、lerna、release-please、conventional-changelog-cli、np、publish-please
• scripts：version、release、publish を含むキーまたは値（dev、start、build は除外）

確認結果を以下の例のように、要約リストとしてユーザーに提示してください。

このリポジトリで以下のバージョン管理ツールが見つかりました。

• standard-version — .versionrc.json、devDependencies の standard-version
• リリーススクリプト — package.json の scripts に "release": "standard-version"

semantic-release のセットアップ前に、これらを削除しますか？

何も見つからない場合は、リポジトリに既存のツールがないことをユーザーに伝え、フェーズ 3 に進んでください。

---

フェーズ 2 — 既存ツールを削除する（条件付き）

フェーズ 1 で既存のツールが見つかり、ユーザーが削除を確認した場合にのみ、このフェーズを実行してください。

検出されたツールごとに、以下を行います。

1. 設定ファイルを削除する — フェーズ 1 で特定した設定ファイルをすべて削除します
2. パッケージをアンインストールする — devDependencies にある検出済みパッケージごとに npm uninstall <package> を実行します
3. スクリプトを整理する — package.json からバージョン／リリース関連のスクリプトを削除します
4. ディレクトリを削除する — changesets が検出された場合は .changeset/ を削除します

削除後、以下のように何を整理したかを確認します。

削除しました。

• .versionrc.json を削除
• standard-version をアンインストール
• package.json から "release" スクリプトを削除

---

フェーズ 3 — semantic-release をインストールする

ステップ 1：コアパッケージをインストールする

npm install --save-dev semantic-release \
  @semantic-release/commit-analyzer \
  @semantic-release/release-notes-generator \
  @semantic-release/changelog \
  @semantic-release/npm \
  @semantic-release/github \
  @semantic-release/git \
  conventional-changelog-conventionalcommits

ステップ 2：リリースブランチを決定する

リポジトリのデフォルトブランチを確認してください。

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || git branch --show-current

結果（通常は main または master）をリリースブランチとして使用します。確信が持てない場合は、ユーザーに確認してください。

ステップ 3：.releaserc.json を作成する

プラグインの順序は重要です。各プラグインは順番に実行され、後続のプラグインは先行するプラグインに依存します。

{
  "branches": ["main"],
  "plugins": [
    ["@semantic-release/commit-analyzer", {
      "preset": "conventionalcommits"
    }],
    ["@semantic-release/release-notes-generator", {
      "preset": "conventionalcommits"
    }],
    ["@semantic-release/changelog", {
      "changelogFile": "CHANGELOG.md"
    }],
    ["@semantic-release/npm", {
      "npmPublish": false
    }],
    "@semantic-release/github",
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md", "package.json", "package-lock.json"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }]
  ]
}

設定を調整してください。

• package.json に "private": true がある場合は、npmPublish: false のままにします（上記ではすでにデフォルト設定です）
• パッケージを npm に公開する場合は、npmPublish: true に設定します
• branches の "main" を、実際のデフォルトブランチ名に置き換えます

ステップ 4：リリーススクリプトを追加する

package.json の scripts に追加します。

"release": "semantic-release"

ステップ 5：コミットの形式チェックについて尋ねる

ユーザーに尋ねてください。

すべてのコミットで Conventional Commits 形式を強制するため、commitlint と husky をインストールしますか？ これにより、形式が正しくないコミットメッセージがプッシュされるのを防げます。

「はい」の場合：

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
npx husky init

commitlint.config.js を作成します。

export default { extends: ['@commitlint/config-conventional'] };

husky フックを作成します。

echo 'npx --no -- commitlint --edit $1' > .husky/commit-msg

.husky/ が（以前の husky セットアップによって）すでに存在する場合は、npx husky init を実行しないでください。 既存のフックと並べて commit-msg フックファイルを追加するだけにしてください。

ステップ 6：CI 統合について確認する

ユーザーに尋ねます：

PR チェック、マージゲート、自動リリース用の GitHub Actions ワークフローを作成しますか？

はいの場合、3 つのワークフローファイルを作成します。3 つすべてで main を実際のデフォルトブランチ名に置き換えてください。

.github/workflows/release.yml — main へのマージ後に semantic-release を実行

name: Release
on:
  push:
    branches: [main]

permissions:
  contents: write
  issues: write
  pull-requests: write

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'

      - name: Install dependencies
        run: npm ci

      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

.github/workflows/pr.yml — PR の作成時または更新時にチェックを実行

name: PR Checks
on:
  pull_request:
    branches: [main]

jobs:
  commitlint:
    name: Validate Commits
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'
      - run: npm ci
      - name: Validate commit messages
        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose

  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'
      - run: npm ci
      - run: npm run lint --if-present

  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'
      - run: npm ci
      - run: npm test --if-present

.github/workflows/merge.yml — マージゲート（ブランチ保護用の単一ステータスチェック）

これは pr.yml と同じチェックを単一のジョブとして実行し、GitHub のブランチ保護設定で必須にできる 1 つのステータスチェック名（Merge Gate）を生成します。

name: Merge Gate
on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

jobs:
  merge-gate:
    name: Merge Gate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'

      - run: npm ci

      - name: Validate commits
        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose

      - name: Lint
        run: npm run lint --if-present

      - name: Test
        run: npm test --if-present

ユーザーに次の点を伝えます：

• GITHUB_TOKEN は GitHub Actions によって自動的に提供されます
• npm に公開する場合のみ NPM_TOKEN が必要です。リポジトリの Settings > Secrets で設定できます
• Merge Gate ジョブ名を、ブランチ保護で必須のステータスチェックとして設定します

ステップ 7：モノレポを確認する

package.json に workspaces フィールドが含まれている場合、または lerna.json が存在する場合は、ユーザーに次のように警告します：

このリポジトリはモノレポのようです。semantic-release は、標準ではモノレポのサポートが限定的です。 パッケージごとのバージョン管理には、semantic-release-monorepo または multi-semantic-release の利用を検討してください。

---

フェーズ 4 — 検証

インストール後：

1. ドライラン（リポジトリにコミットがある場合）：

   npx semantic-release --dry-run --no-ci
   

   これにより、何も公開せずに設定を検証できます。出力をユーザーに共有します。

2. 概要 — 設定した内容をユーザーに伝えます：

   • Conventional Commits プリセットを使用した semantic-release
   • 有効なプラグイン
   • commitlint/husky による強制を追加したかどうか
   • CI ワークフローを作成したかどうか

3. コミット例 — すぐにシステムを使い始められるよう、ユーザーに例を示します：

   fix: resolve null pointer in user lookup
   → triggers PATCH bump (e.g., 1.0.0 → 1.0.1)
   
   feat(auth): add OAuth2 support
   → triggers MINOR bump (e.g., 1.0.1 → 1.1.0)
   
   feat!: redesign the public API
   → triggers MAJOR bump (e.g., 1.1.0 → 2.0.0)
   
   chore: update dev dependencies
   → no version bump, appears in changelog
   

---

フェーズ 5 — ブランチ保護

Conventional Commits は、すべての変更をブランチと PR 経由で行うと、最も効果を発揮します。 このフェーズでは、main への直接コミットを防ぐために、3 層の保護を設定します。

ステップ 1：husky の pre-commit フックをインストールする

これにより、ターミナルから main で git commit を実行できないようにします。

npm install --save-dev husky
npx husky init

.husky/pre-commit の内容を次のように置き換えます：

#!/bin/sh
branch=$(git rev-parse --abbrev-ref HEAD)
if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
  echo ""
  echo "  Direct commits to $branch are not allowed."
  echo "  Create a feature branch and open a PR instead:"
  echo ""
  echo "    git checkout -b feat/your-feature"
  echo ""
  exit 1
fi

.husky/ がすでに存在する場合は、npx husky init を実行せず、pre-commit ファイルだけを置き換えます。 .husky/commit-msg フック（フェーズ 3、ステップ 5 で作成）がある場合は、そのまま残します。

ステップ 2：Claude Code の PreToolUse フックをインストールする

これにより、Claude が main でステージングまたはコミットできないようにします。本当に必要な場合にユーザーが上書きできるよう、承認を求めます。

対象リポジトリに .claude/hooks/protect-main.sh を作成します：

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if ! echo "$COMMAND" | grep -qE "^git (add|commit)"; then
  exit 0
fi

CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)

if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
  if echo "$COMMAND" | grep -qE "^git add"; then
    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "ask",
        permissionDecisionReason: "You are about to stage files on main. Create a feature branch instead."
      }
    }'
  else
    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "ask",
        permissionDecisionReason: "You are about to commit directly to main. Create a feature branch instead."
      }
    }'
  fi
  exit 0
fi

exit 0

実行可能にします：

chmod +x .claude/hooks/protect-main.sh

次に、フックを登録するため .claude/settings.json を作成するか更新します。ファイルがすでに存在する場合は、既存の設定を上書きせず、hooks キーを統合します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/protect-main.sh"
          }
        ]
      }
    ]
  }
}

ステップ 3：GitHub のブランチ保護を設定する

ユーザーに尋ねます：

main に GitHub のブランチ保護ルールを設定しますか？ 管理者アクセスが必要で、サーバー側で PR を必須にします。

はいの場合、GitHub CLI を使用します：

gh api repos/{owner}/{repo}/branches/main/protection \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -f "required_pull_request_reviews[dismiss_stale_reviews]=false" \
  -f "required_pull_request_reviews[require_code_owner_reviews]=false" \
  -F "required_pull_request_reviews[required_approving_review_count]=1" \
  -F "enforce_admins=true" \
  -f "restrictions=null" \
  -f "required_status_checks=null"

{owner}/{repo} を gh repo view --json owner,name で取得した実際の値に置き換えます。

リポジトリに CI ワークフロー（フェーズ 3、ステップ 6 で作成）がある場合、すべてのチェックに合格しないと PR をマージできないように、Merge Gate ジョブを必須ステータスチェックとして有効にします：

gh api repos/{owner}/{repo}/branches/main/protection \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -f "required_pull_request_reviews[dismiss_stale_reviews]=false" \
  -F "required_pull_request_reviews[required_approving_review_count]=1" \
  -F "enforce_admins=true" \
  -f "restrictions=null" \
  -f "required_status_checks[strict]=true" \
  -f "required_status_checks[contexts][]=Merge Gate"

ユーザーに次の点を伝えます：

• enforce_admins: true にすると、リポジトリ管理者もルールを回避できません
• Merge Gate は merge.yml のジョブ名です。コミットを検証し、lint とテストを実行します
• これらの設定は、後から GitHub リポジトリの Settings > Branches で変更できます

---

クイックリファレンス — コミット形式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

プレフィックス	バージョンの更新	例
fix:	PATCH (0.0.x)	fix: prevent race condition in auth flow
feat:	MINOR (0.x.0)	feat(api): add pagination to /users endpoint
feat!:	MAJOR (x.0.0)	feat!: drop support for Node 14
BREAKING CHANGE: フッター	MAJOR (x.0.0)	フッターに BREAKING CHANGE: <desc> を含む、任意のタイプ

有効なタイプ： feat、fix、build、chore、ci、docs、style、refactor、perf、test

デフォルトでは、feat と fix のみがバージョン更新を発生させます。その他のタイプは変更履歴に表示されますが、バージョンは更新されません。

---

仕様に関する質問への回答

Conventional Commits 仕様に関する詳細な質問（スコープのルール、複数行の本文、フッターの構文、例外的なケース）については、このスキルのディレクトリにある references/conventional-commits-spec.md を参照してください。16 個すべてのルールと例を含む、v1.0.0 仕様の全文が記載されています。