ai-changelog

AI 駆動の変更履歴

開発中に AI エージェントが管理する変更履歴システムをセットアップします。プロジェクトの種類に応じて、次の 2 つの形式があります。

• ソフトウェアプロジェクト：エージェントは ## [Unreleased] の下にエントリーを追加し、自動化によってリリース時にバージョン番号が付与されます（CalVer または SemVer）。エージェントがバージョン番号を記述することはありません。ビルドプロセスが処理します。
• コードを含まないプロジェクト（ビルドシステムなし）：エージェントは日付見出し（## YYYY-MM-DD）の下に簡潔な箇条書きを手動で追加します。スクリプトもバージョン番号もありません。references/dated.md を参照してください。

セットアップのワークフロー

1. ビルドシステムを検出します：Makefile、Justfile、package.json、Cargo.toml、pyproject.toml、go.mod を確認します。どの設定ファイルに "version" フィールドが含まれているかを記録します。

2. そもそもソフトウェアプロジェクトかどうかを確認します。 ステップ 1 のビルドシステムがなく、バージョン規約もない場合（ドキュメントリポジトリ、執筆用またはメモ用の保管庫、コンテンツサイト、研究資料や設定のコレクションなど）は、Dated モードを使用します。日付ベースの変更履歴見出しを使い、バージョンスクリプトもビルドとの統合も行いません。そのまま references/dated.md に進み、以下のスクリプト／ビルド手順は無視してください。それ以外の場合は、次の方法でバージョン管理方式を検出します（確度の高い順）。

   • CHANGELOG.md の見出し形式：## [YYYY.M.N] の見出し → CalVer、## [X.Y.Z] の見出し、または「SemVer」に言及する説明文 → SemVer
   • Git タグ（git tag --list | head）：vX.Y.Z → SemVer、YYYY.M.N → CalVer
   • VERSION ファイルの内容が ^[0-9]+\.[0-9]+\.[0-9]+ に一致 → SemVer
   • マニフェストのバージョンフィールド（package.json、Cargo.toml、pyproject.toml）が X.Y.Z に一致 → SemVer

   判断材料がない場合、または矛盾している場合は、ユーザーに確認してください。既存のタグ、マニフェストのバージョン、過去の変更履歴など、確立されたバージョン履歴があるプロジェクトには SemVer を提案し、自動バージョン管理を優先する新規プロジェクトには CalVer を提案します。それぞれの方式のトレードオフは、対応するリファレンスファイルに記載されています。

3. 選択した方式に対応するリファレンスを読みます。ビルド統合の手順、CLAUDE.md のスニペット、GitHub Actions のパターン、および方式固有の注意事項が記載されています。

   • CalVer → references/calver.md
   • SemVer → references/semver.md
   • Dated（コードを含まないプロジェクト） → references/dated.md

4. オプション機能についてユーザーに確認します（CalVer／SemVer のみ。Dated モードでは省略します）。

   • ## [Unreleased] の上に固定の ## Known Bugs セクションを設けますか？（デフォルト：はい）
   • GitHub Actions のリリースワークフローと統合しますか？（デフォルト：依頼がない限り省略）

5. CHANGELOG.md を生成または更新します。CalVer／SemVer では references/changelog-template.md を、Dated では references/dated.md のテンプレートを使用します。CHANGELOG.md がすでに存在する場合は、上書きしないでください。HTML コメントと適切な構成（CalVer／SemVer では ## [Unreleased]、Dated では今日の日付の見出し）を既存のエントリーより上に挿入します。

6. このスキルの scripts/version.py を、対象プロジェクトの scripts/ ディレクトリにコピーします。実行可能にします（chmod +x）。Dated モードではスクリプトがないため省略します。

7. 方式に対応するリファレンスを適用します：選択したリファレンスファイルのビルド統合手順に従います。既存のビルドシステムにターゲットを追加するか、存在しない場合は最小限の Makefile を作成します。Dated モードではビルド統合がないため省略します。

8. CLAUDE.md を更新します。選択した方式のリファレンスにあるスニペットを使用します。プロジェクトの開発ワークフローのセクションに挿入するか、そのセクションを作成します。Dated モードでは、これが変更履歴を最新に保つ唯一の仕組みなので、必ずスニペットを追加してください。

9. 検証します：

   • CalVer：uv run scripts/version.py version で今日の CalVer が表示されることを確認し、次に uv run scripts/version.py stamp --dry-run でスタンプ内容をプレビューします。
   • SemVer：uv run scripts/version.py stamp --version <current-version> --dry-run --changelog-only で、正規のバージョンソースに触れずにスタンプ内容をプレビューします。
   • Dated：CHANGELOG.md に今日の日付の見出しがあり、CLAUDE.md のスニペットが配置されていることを確認します。実行するものはありません。

プロジェクトの検出

指標	バージョンを記録する設定ファイル	ビルドとの統合
Makefile	プロジェクトによる	make ターゲットを追加
Justfile	プロジェクトによる	just レシピを追加
package.json	package.json	npm スクリプトまたは Makefile を追加
Cargo.toml	Cargo.toml	Makefile ラッパー
pyproject.toml	pyproject.toml	Makefile ラッパー
go.mod	VERSION（存在する場合）、またはなし	Makefile ラッパー
VERSION ファイル	VERSION	Makefile ラッパー
なし（コードプロジェクト）	なし	最小限の Makefile を作成
なし（非コードプロジェクト）	なし	日付モード — スクリプトも Makefile もなし

スクリプトの仕組み

scripts/version.py のサブコマンド：

• version：本日の CalVer を標準出力に表示します（CalVer プロジェクトのみ）
• stamp：## [Unreleased] を ## [VERSION] - DATE に置き換え、新しい ## [Unreleased] を再挿入し、自動検出した設定ファイル（package.json、Cargo.toml、pyproject.toml、tauri.conf.json、VERSION）にバージョンを記録します

フラグ：--version X.Y.Z（SemVer では必須、CalVer では任意の上書き値）、--dry-run、--changelog-only、--no-changelog。

このスクリプトはバージョン方式に依存しません。--version を指定しない場合は CalVer を自動計算し、--version を指定した場合は指定された文字列をそのまま記録します。検証はビルドシステム側で行うため、SemVer のレシピでは必ず --version を指定し、スクリプトを呼び出す前に不正な入力を拒否します。この分担が重要な理由については、references/semver.md を参照してください。

uv run scripts/version.py stamp または python3 scripts/version.py stamp で実行します（外部依存関係はありません）。

注意点

• 既存の変更履歴を上書きしないでください。 CHANGELOG.md に内容がある場合は、ファイルを置き換えるのではなく、[Unreleased] の構成を統合してください。
• 空の Unreleased セクション：[Unreleased] に内容がない場合、スタンプ処理は何も行いません。これにより、空のバージョンエントリーを防ぎます。
• CI での fetch-depth: 0（CalVer）：CalVer では git rev-list --count HEAD を使用します。浅いクローンではコミット数が正しく取得されません。
• HTML コメントはエージェントへの指示の情報源です。 CHANGELOG.md の `` コメントは、後続のエージェントにエントリーの書き方を伝えます。省略しないでください。
• Known Bugs は固定位置に置きます。 スタンプスクリプトは ## Known Bugs を ## [Unreleased] より上に保持します。これを追加した場合は、エージェントがその位置を維持する必要があります。
• SemVer と自動 CalVer の組み合わせは、気づきにくい落とし穴です。 SemVer プロジェクトの Makefile が --version を指定せずに python3 scripts/version.py stamp を呼び出すと、スクリプトは CalVer を自動計算し、変更履歴に書き込みます。references/semver.md のレシピでは常に --version を指定します。独自の統合でも、この取り決めを維持してください。
• TOML の設定ファイルへのバージョン記録は、最初に一致した箇所のみが対象です。 正規表現は最初の version = "..." 行だけを置き換えます。これはパッケージのバージョンであり、依存関係のバージョンには影響しません。
• VERSION ファイルへの記録には、既存の SemVer 形式の内容が必要です。 スクリプトの VERSION ハンドラーは、現在の内容が ^\d+\.\d+\.\d+ に一致する場合にのみファイルを書き換えます。ビルド番号、タグが前置されたバージョン、その他の形式はそのまま残ります。