changelog-writer

変更履歴ライター

Git の履歴から、変更履歴、リリースノート、破壊的変更の概要、移行ガイド、バージョン更新の推奨事項を生成します。

対象範囲： 変更履歴とリリースドキュメントのみです。Git 操作（git-workflow）、ドキュメントサイト（docs-steward）、コードレビュー（review）は対象外です。

ディスパッチ

$ARGUMENTS	モード
空 / generate	最近のコミットから変更履歴を生成
release <version>	指定バージョンのユーザー向けリリースノート
breaking	破壊的変更の検出と概要
migration <from> <to>	2つのバージョン間の移行ガイド
bump	変更に基づくセマンティックバージョンの推奨
認識できない入力	確認を求め、モードメニューを表示

標準用語

用語	定義
conventional commit	type(scope): description 形式に従ったコミット
change type	分類：feat、fix、refactor、perf、docs、chore、test、ci、build、style
breaking change	! または BREAKING CHANGE: フッターで示される、後方互換性のない変更
scope	影響を受けるコンポーネント。type の後ろの括弧内に記載
changelog entry	変更履歴セクション内の書式化された項目
release notes	特定バージョンの変更をユーザー向けにまとめたもの
migration guide	バージョン間をアップグレードするための手順
semver bump	major（破壊的変更）、minor（feat）、patch（fix）の推奨
unreleased	最後にタグ付けされたバージョン以降の変更

モード 1：変更履歴の生成

デフォルトモードです。Keep a Changelog 形式のドキュメントを生成します。

ステップ 1：コミットの分類

コミット分類スクリプトを実行します。

uv run python skills/changelog-writer/scripts/commit-classifier.py [--since <tag-or-date>] [--until <ref>] [--path <dir>]

JSON 出力を解析します。このスクリプトは各コミットを conventional type で分類し、破壊的変更を検出します。

ステップ 2：変更履歴の書式化

変更履歴の書式化スクリプトを実行します。

uv run python skills/changelog-writer/scripts/changelog-formatter.py --input <classified-json> [--format keepachangelog|github|simple]

このスクリプトは、分類されたコミットを書式化済みの Markdown に変換します。デフォルト形式は Keep a Changelog です。

ステップ 3：確認と調整

• 項目をセクション（追加、変更、非推奨、削除、修正、セキュリティ）ごとにまとめます
• 簡潔すぎるコミットメッセージを、ユーザーにわかりやすい説明に書き換えます
• 適切な場合は、関連するコミットを1つの項目にまとめます
• 破壊的変更が目立つようにします

形式のリファレンス：references/changelog-conventions.md を読みます

モード 2：リリースノート

release <version> は、洗練されたユーザー向けリリースノートを生成します。

ステップ 1：対象範囲の特定

範囲を決定します。最後のタグから HEAD まで（または、すでにバージョンにタグが付いている場合は2つのタグ間）です。

git log --oneline <previous-tag>..<version-or-HEAD>

ステップ 2：分類とグループ化

適切な --since フラグと --until フラグを指定して commit-classifier.py を実行します。コミットの種類ではなく、ユーザーへの影響に基づいてグループ化します。

• 主な変更点 — 目玉となる機能（上位3～5件）
• 改善点 — 機能強化、パフォーマンス向上
• バグ修正 — 解決された問題
• 破壊的変更 — 移行が必要な項目（移行モードへのリンク）
• コントリビューター — git log から貢献者を記載

ステップ 3：リリースノートの作成

技術的なコミットメッセージを、ユーザー向けの表現に書き換えます。リファレンス：references/changelog-conventions.md の「リリースノートのスタイル」を読みます。

モード 3：破壊的変更

breaking は、後方互換性のない変更をスキャンします。

ステップ 1：検出

破壊的変更に焦点を当ててコミット分類スクリプトを実行します。

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only [--since <tag>]

ステップ 2：詳細化

破壊的変更ごとに、以下を行います。

1. 影響を受ける API／インターフェースを特定します
2. 何が、なぜ変更されたのかを説明します
3. 変更前後のコードパターンを示します
4. 影響範囲（影響を受ける利用者の数）を評価します

言語固有の検出には、data/breaking-change-patterns.json のパターンを使用します。

ステップ 3：要約

影響範囲と移行作業量に基づいて重大度（高／中／低）をランク付けした、破壊的変更レポートを出力します。

モード 4：移行ガイド

migration <from> <to> は、アップグレード手順を段階的に生成します。

ステップ 1：破壊的変更の収集

2つのバージョン間でコミット分類スクリプトを実行します。

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only --since <from> --until <to>

ステップ 2：移行手順を作成する

破壊的変更ごとに、以下を作成します。

1. 変更内容 — 以前の動作と新しい動作
2. 必要な対応 — 移行のための具体的な手順
3. コード例 — 変更前／変更後のスニペット
4. 検証 — 移行が成功したことを確認する方法

依存関係の順に手順を並べます（先に行う必要がある変更を最初にします）。

ステップ 3：ガイドをまとめる

番号付きチェックリストとして構成します。移行前のチェックリスト（バックアップ、テストスイートがすべて成功していること）と、移行後の検証手順を含めます。

参照：references/changelog-conventions.md の「Migration Guide Structure」セクションを読みます。

モード 5：バージョン更新

bump は次のセマンティックバージョンを推奨します。

ステップ 1：分析する

コミット分類器を実行します。

uv run python skills/changelog-writer/scripts/commit-classifier.py --since <last-tag>

JSON 出力の suggested_bump フィールドを読みます。

ステップ 2：報告する

根拠とともに推奨内容を示します。

更新	理由
major	検出された破壊的変更：一覧
minor	破壊的変更を伴わない新機能
patch	バグ修正と非機能的な変更のみ

推奨を裏付けるコミットの根拠を示します。コミットの形式が慣例に沿っておらず判断が曖昧な場合は、不確実性を明記して確認を求めます。

参照ファイル

一度に読み込む参照ファイルは 1 つだけです。

ファイル	内容	読み込むタイミング
references/changelog-conventions.md	Keep a Changelog の形式、リリースノートのスタイル、移行ガイドの構成、セマンティックバージョンの判断ツリー	いずれかのモードで出力を整形するとき
references/commit-parsing.md	Conventional Commits の解析規則、破壊的変更の検出ヒューリスティック	分類器の出力や特殊なケースを理解するとき

データファイル	内容	使用箇所
data/changelog-formats.json	形式テンプレート（Keep a Changelog、GitHub Releases、シンプル形式）	changelog-formatter.py
data/breaking-change-patterns.json	言語ごとの破壊的変更検出パターン	commit-classifier.py、モード 3 の情報追加

スクリプト	目的
scripts/commit-classifier.py	git log を解析し、Conventional Commits のタイプで分類し、破壊的変更を検出する
scripts/changelog-formatter.py	分類済みのコミット JSON を書式付きの変更履歴 Markdown に変換する

重要なルール

1. git の履歴を変更したり、git log と git tag 以外の git 操作を実行したりしないでください。このスキルは読み取り専用です。
2. 整形する前に必ず commit-classifier.py を実行してください。git log を手動で解析してはいけません。
3. すべての出力形式で、破壊的変更を目立つように明記してください。
4. コミットメッセージはユーザーにわかりやすい表現に書き換えてください。コミットの生テキストは変更履歴になりません。
5. 移行ガイドには、すべての破壊的変更について変更前／変更後のコード例を含めてください。
6. バージョン更新の推奨では、根拠として具体的なコミットを挙げてください。
7. コミットが慣例に沿っていない場合は、可能な限りのヒューリスティックで分類し、不確実性を明記してください。
8. コミットされていない変更について変更履歴を生成しないでください。コミット済みの履歴のみを対象とします。
9. ユーザーから別途指定がない限り、直前のタグを基準として必ず特定してください。
10. リリースノートでは貢献者を記載してください。git log の author フィールドから情報を抽出します。