changelog-composer

変更履歴の作成

生の Git 履歴と PR の説明を、対象読者に適した洗練された変更履歴に変換します。Conventional Commits を解析し、影響カテゴリごとに変更を分類し、内部向けの変更を除外して、PR リンク付きの構造化されたリリースノートを作成します。Keep a Changelog の規約に準拠します。

参照ファイル

ファイル	内容	読み込むタイミング
references/conventional-commits.md	コミット種別の解析、スコープの抽出、破壊的変更の指標	リポジトリが Conventional Commits を使用している場合
references/categorization-rules.md	変更の分類ロジック、対象読者のフィルタリング、重大度の順序付け	常に
references/audience-filter.md	ユーザー向け変更と内部向け変更の検出、除外パターン	常に
references/changelog-formats.md	Keep a Changelog、GitHub Releases、告知文のテンプレート	形式の選択が必要な場合

前提条件

• git — リポジトリの履歴へのアクセス
• gh（任意）— PR の説明を抽出するための GitHub CLI
• リリース境界の特定に使用するタグ付け戦略（semver タグ）

ワークフロー

フェーズ 1：変更の収集

前回のリリースから現在の状態までの変更をすべて収集します。

1. 境界を特定する — 最後のリリースタグを検索します：git describe --tags --abbrev=0。 タグが存在しない場合は、初回のコミットまたはユーザー指定の開始地点を使用します。
2. コミットを抽出する — git log <last-tag>..HEAD --oneline --no-merges
3. PR タイトルを抽出する — gh pr list --state merged --base main --search "merged:>YYYY-MM-DD" またはマージコミットのメッセージを解析します。
4. Conventional Commits を解析する — リポジトリが Conventional Commits（feat:、fix:、docs: など）に従っている場合は、 種別、スコープ、説明を抽出します。references/conventional-commits.md を参照してください。
5. 破壊的変更の指標を収集する — コミット本文の BREAKING CHANGE:、種別の後の !（feat!:）、または PR の説明にある明示的な注記を確認します。

フェーズ 2：変更の分類

各変更を影響に応じて分類します。

カテゴリ	Conventional Commit の種別	指標
破壊的変更	feat!:, BREAKING CHANGE:	API の削除、シグネチャの変更、動作の変更
機能	feat:	新しい機能、新しいエンドポイント、新しいコマンド
修正	fix:	バグの修正、エラー処理の改善
パフォーマンス	perf:	速度の改善、メモリ使用量の削減
ドキュメント	docs:	README、API ドキュメント、ガイド
内部向け	chore:, ci:, refactor:, test:, build:	ユーザー向けの影響なし

Conventional Commits を使用していないリポジトリでは、コミットメッセージと変更されたファイルを読んで分類します。公開 API に関するコードの変更は機能または修正、テストのみの変更は内部向けに分類します。

フェーズ 3：対象読者に合わせて絞り込む

1. デフォルトでは内部向けの変更を除外します：

   • CI/CD 設定の変更
   • テストの追加・変更
   • 依存関係の更新（セキュリティに関わる場合を除く）
   • 動作に変更のないコードのリファクタリング
   • ビルドシステムの変更

2. 内部向けの変更を含めるのは、次の場合に限ります：

   • ユーザーが把握しておくべき重要なアーキテクチャの変更である
   • 開発ワークフローに影響する（コントリビューションガイドの変更など）
   • 変更履歴の対象がエンドユーザーではなく開発者である

3. 破壊的変更は目立つように強調します — 必ず先頭に記載し、必ず移行方法を示してください。

フェーズ 4：項目を作成する

含める変更ごとに、読みやすい説明を記述します。

1. 影響から書き始めます — 「ユーザーは〜できるようになりました」または「〜という問題を修正しました」
2. 具体的に記述します — 「パフォーマンスを改善しました」ではなく、「大きなファイルの処理時にメモリ使用量を 40% 削減しました」
3. 破壊的変更には移行方法を含めます — ユーザーが何を変更する必要があるかを記載します
4. 変更元へのリンクを記載します — PR 番号、Issue 番号、またはコミットハッシュ

フェーズ 5：出力する

変更履歴を指定された形式でまとめ、重要度順に並べます。

1. 破壊的変更（必ず最初）
2. 機能
3. 修正
4. パフォーマンス
5. ドキュメント

出力形式

## [{version}] - {YYYY-MM-DD}

### Breaking Changes
- **`function_name` parameter renamed** — `old_param` is now `new_param`.
  Migration: find/replace `old_param=` with `new_param=` in all call sites. ([#{pr}]({url}))

### Features
- **{Feature name}** — {What it enables and why it matters}. ([#{pr}]({url}))

### Fixes
- Fixed {symptom} when {condition}. ([#{pr}]({url}))

### Performance
- {Operation} is now {X}x faster / uses {X}% less memory. ([#{pr}]({url}))

### Documentation
- Added {guide/reference} for {topic}. ([#{pr}]({url}))

対象範囲の設定

モード	入力	出力	使用する場面
release	タグから HEAD まで	完全な変更履歴の項目	バージョン付きリリースの準備
sprint	日付範囲またはコミット範囲	変更の概要	スプリントレビュー、状況報告
pr	単一の PR	1 行の変更履歴の項目	PR の説明テンプレート

調整ルール

1. まずユーザーへの影響を考えます。 各項目は「ユーザーにとってどのような意味があるのか？」に答える必要があります。「開発者が何をしたのか？」ではありません。
2. 破壊的変更は必ず記載します。 破壊的変更を省略したり、目立たない場所に記載したりしてはいけません。移行方法とともに先頭に記載します。
3. 曖昧な表現より具体的な表現を使います。 「バグを修正しました」より「接続が遅い場合に発生するログインのタイムアウトを修正しました」が適切です。「新機能を追加しました」より「レポートを CSV 形式でエクスポートする機能を追加しました」が適切です。
4. すべてにリンクを付けます。 各項目から元となる PR または Issue にリンクします。詳細を知りたいユーザーはリンク先を確認できます。
5. 不要な情報を除外します。 内部向けのリファクタリング、依存関係の更新、CI の変更は、ユーザーから見える影響がない限り、ユーザー向けの変更履歴には含めません。

エラー処理

問題	解決方法
リポジトリにタグが存在しない	開始コミットまたは日付を確認します。リポジトリが小さい場合は、最初のコミットをデフォルトにします。
リポジトリで Conventional Commits を使用していない	コミットメッセージと変更されたファイルを読んで分類します。分類精度が低下することを明記します。
PR の説明が空、または品質が低い	コミットメッセージを代わりに使用します。手動レビューが必要な可能性のある項目には印を付けます。
変更の分類が曖昧	追加は「機能」、変更は「修正」に分類します。判断が確かでない項目にはレビューが必要であることを示します。
1 回のリリースに変更が多すぎる	コンポーネントまたはモジュールごとにまとめます。リリースを分割すべきか検討します。
マージコミットによって個々の変更が分かりにくい	--no-merges を使ってマージコミットをスキップします。マージされた PR 内の個々のコミットを解析します。

Compose を使用しない場合

次の場合は、再検討を促してください。

• ユーザーがレビューなしでリリースノートを自動公開したい場合 — 変更履歴には人間による判断が必要です
• リポジトリに意味のあるコミット履歴がない場合（すべてが含まれた単一の「initial commit」）
• 技術的なリリースノートではなく、マーケティング用の文章を依頼されている場合 — 別のスキルが必要です
• 変更がまだマージされていない場合 — 変更履歴は進行中の作業ではなく、リリース済みの変更を対象とします