make-changelog

変更履歴ジェネレーター

Git の履歴から Keep a Changelog 形式で CHANGELOG.md を作成または更新します。 バージョン範囲ごとに俳句サブエージェントを 1 つ起動し、並列処理でトークンを効率的に使用します。

ステップ 1 — プロジェクトの状態を確認する

範囲計画スクリプトを実行して、リポジトリの検証とすべてのバージョン範囲の取得を行います。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py --output json

• 終了コード 2 = Git リポジトリではない、またはリポジトリにコミットがありません。停止し、stderr のエラーメッセージをユーザーに報告します。
• 終了コード 0 = 続行します。JSON 出力には、このスキルが対象とするすべての範囲が含まれます。

既存の変更履歴ファイルも確認します。

ls CHANGELOG.md CHANGELOG 2>/dev/null

CHANGELOG.md が存在する場合は、最後に記録されたバージョン（最新の ## [x.y.z] 見出し）を特定するために内容を読みます。

ステップ 2 — 対象範囲を決定する

タグが存在しない場合： スクリプトは単一の Unreleased 範囲を返します。新規モードで続行します。

タグが存在し、CHANGELOG.md がない場合： 新規モード — スクリプトが返したすべての範囲を処理します。

タグと CHANGELOG.md が存在する場合： 追加モード — --since-tag を指定してスクリプトを再実行し、未記載の範囲のみを取得します。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py \
  --since-tag <last_documented_tag> --output json

意図が曖昧な場合（ユーザーが「変更履歴を更新して」と言っているが、ファイルに既存の内容が大量にある場合）は、ユーザーに選択肢を確認します。

• 「未記載分のみ追加」 — 最後の項目以降の新しいバージョン／Unreleased を追加
• 「最初から再構築」 — Git の履歴からファイル全体を再生成
• 「Unreleased のみ」 — [Unreleased] セクションのみを更新

ステップ 3 — サブエージェントを計画する

ステップ 1 または 2 の JSON 出力を確認します。各範囲オブジェクトには以下が含まれます。

• label — バージョン文字列（1.2.0 または Unreleased）
• from_ref — 下限の Git ref（空文字列 = 最初のコミットから）
• to_ref — 上限の Git ref
• date — タグの日付または今日の日付
• commit_count — 範囲内のコミット数

commit_count == 0 の範囲はスキップします — サブエージェントは不要です。

サブエージェントは最大 12 個です。 空でない範囲のリストが 12 を超える場合は、直近の 12 件に限定するか、すべて処理するかをユーザーに確認します（すべて処理する場合は時間がかかることを伝えます）。

ステップ 4 — 俳句サブエージェントを起動する

空でない範囲ごとに Task を 1 つ、単一のメッセージで（並列に）起動します。すべてのサブエージェントで model: "haiku" を使用します。各サブエージェントには、次の自己完結型プロンプトを渡します（範囲オブジェクトの値を代入します）。

You are generating one section of a CHANGELOG.md.

Version: [label]
Date: [date]
Git command: git log [from_ref]..[to_ref] --format="%s"
(If from_ref is empty, use: git log [to_ref] --format="%s")

Categorize by user-observable impact, not by commit prefix. The conventional
commit prefix (feat:, fix:, etc.) is a hint only — a commit labelled "feat:"
that clearly corrects a bug belongs in Fixed, not Added. Use the prefix as a
starting signal and override it when the commit subject contradicts it.

Sections and classification signals:
- Added: new capabilities users can invoke (add, introduce, implement, support)
- Changed: modified behavior of existing features (update, change, refactor, improve)
- Deprecated: features explicitly flagged for future removal
- Removed: capabilities or endpoints deleted (remove, drop, delete)
- Fixed: bugs corrected, regardless of prefix (fix, resolve, patch, correct, hotfix)
- Security: vulnerability patches (security, CVE, sanitize, escape)

Skip: merge commits, CI/CD configuration changes, version-bump commits,
formatting-only changes.

Use present tense, imperative mood: "Add X", not "Added X" or "adds X".
Omit empty sections. Omit internal variable names and implementation details.

Output ONLY the markdown block, no preamble:

## [VERSION] - DATE

### Added
- ...

### Fixed
- ...

ステップ 5 に進む前に、すべての Task の結果を収集します。

ステップ 5 — 変更履歴を組み立てる

バージョンブロックを新しいものから順に並べます。ドキュメント全体の構成は次のとおりです。

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

[content from unreleased subagent, or omit section if empty]

## [1.2.0] - 2024-03-15

[content from subagent]

追加モード： 新しいバージョンセクションを # Changelog のヘッダーブロックの直後、最初の既存の ## [ 項目より前に挿入します。既存の内容はすべてそのまま保持します。

新規／再構築モード： ファイル全体を書き込みます。

ステップ 6 — 書き込みと報告

新規モード： CHANGELOG.md に書き込みます。ファイルがすでに存在する場合は、AskUserQuestion で上書きの確認を取ります。

追加モード： Edit を使用して、新しいセクションを正しい位置に挿入します。

書き込み後、次の内容を報告します。

• 使用したモード（新規／追加／Unreleased のみ）
• 対象バージョン（ラベル、日付、コミット数 — スクリプトの出力から）
• 使用したサブエージェントの数
• 空だったためスキップした範囲
• 自信を持って分類できなかったコミット（ユーザーによる確認が必要なもの）

スクリプト

scripts/list_ranges.py — Git タグを照会し、バージョン範囲を計算します。ステップ 1 と 2 で実行します。終了コード 2 = リポジトリが無効または空、終了コード 0 = 成功。

# All ranges (text preview)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py

# All ranges (JSON for skill use)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py --output json

# Fill mode: only ranges newer than a specific tag
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py \
  --since-tag v1.2.0 --output json