commit-message-storyteller

コミットメッセージのストーリーテラー

生の git diff や変更内容の説明を、Conventional Commits の仕様に準拠した、明確でストーリー性のあるコミットメッセージに変換します。「update file.js」ではなく、意図、背景、影響が伝わるメッセージを作成できます。

このスキルを使うタイミング

• ユーザーが「コミットメッセージを書いて」と言った場合
• ユーザーが git diff を貼り付ける、またはコードの変更内容を説明した場合
• ユーザーが「これを何としてコミットすればいい？」や「diff を要約して」と言った場合
• ユーザーがチームやオープンソースプロジェクトのコミット履歴を改善したい場合
• ユーザーがプルリクエストを準備しており、意味のあるコミットメッセージを作りたい場合

前提条件

以下のいずれかを少なくとも 1 つ用意してください。

• git diff または git diff --staged の出力
• 何を変更したか、なぜ変更したかの説明
• 変更したファイルの一覧

仕組み

ステップ 1：変更の背景を集める

ユーザーに質問するか、diff から推測して、以下を把握します。

1. 何を変更したか — 影響を受けたファイル、関数、ロジック
2. なぜ変更したか — バグ修正、新機能、リファクタリング、パフォーマンス改善など
3. 何がきっかけか — イシュー番号、ユーザーの要望、技術的負債など

ユーザーが生の git diff を提供した場合は、そこからこの背景を自動的に抽出します。

ステップ 2：コミットの種類を特定する

以下のガイドを使って、変更を Conventional Commits の種類に当てはめます。

種類	使用する場面
feat	新しい機能や能力を追加する
fix	バグや誤った動作を修正する
refactor	動作を変えずにコードを再構成する
perf	パフォーマンスを改善する変更
docs	ドキュメントのみの変更
style	書式、空白、セミコロンの不足など（ロジックの変更なし）
test	テストを追加または更新する
build	ビルドシステムや依存関係の変更
chore	ソースコードやテストに影響しない、その他の保守作業
ci	CI/CD パイプラインの変更
revert	以前のコミットを取り消す

詳細な例については、references/conventional-commits-guide.md を参照してください。

ステップ 3：コミットメッセージを書く

以下の構成に従います。

<type>(<optional scope>): <short imperative summary>

<body — the story: why this change was made, what problem it solves>

<footer — issue refs, breaking change notices>

各部分のルール

件名（1 行目）：

• 命令形を使います。「added」や「fixes」ではなく、「add」「fix」「remove」のようにします
• 最大 72 文字
• 末尾にピリオドを付けません
• コロンの後は小文字にします

本文（ストーリー）：

• 何をではなく、なぜを説明します（何を変更したかは diff を見ればわかります）
• 変更前に存在していた問題を説明します
• 該当する場合は、検討した代替案にも触れます
• 1 行を 100 文字未満にします
• 件名との間に空行を入れます

フッター：

• イシューを参照します：Closes #123、Fixes #456、Refs #789
• 破壊的変更を明記します：BREAKING CHANGE: <description>

ステップ 4：出力を生成する

コピーできるコードブロックでコミットメッセージを出力し、その後に、伝えたストーリーを説明する平易な英語の 1 行を添えます。

出力例：

fix(auth): prevent token refresh loop on expired sessions

When a user's session expired mid-request, the auth middleware was
triggering a token refresh, which itself failed validation and triggered
another refresh — causing an infinite retry loop that crashed the app.

This adds a recursion guard flag that aborts the refresh cycle if a
refresh is already in progress, returning a clean 401 instead.

Closes #312

伝えたストーリー： セッションの期限切れ時に発生する、気付かれにくい無限ループがアプリをクラッシュさせていました。この変更でループを早期に止め、適切なエラーを返します。

---

1 つの diff から複数のコミットを作る場合

diff に論理的に分けられる変更が含まれている場合は、複数のコミットメッセージに分け、その旨をユーザーに伝えます。以下を目安にしてください。

• 目的の異なるファイルが複数ある → コミットを分けるのが適切な可能性が高い
• 同じファイルに異なる目的の変更がある（例：バグ修正とリファクタリング）→ 分割を提案する
• すべてが密接に関連している → 1 つのコミットで問題ありません

---

エッジケース

状況	対応方法
ユーザーが diff 以外の背景を提供していない	ファイル名と変更されたシンボルから種類とスコープを推測する
変更が多くのファイルにまたがり、明確なテーマがない	「これは 1 つの論理的な変更ですか、それとも複数ですか？」と尋ねる
破壊的変更を検出した	BREAKING CHANGE: フッターを自動的に追加する
ユーザーが「短くして」と言った	本文を省略し、わかりやすい件名だけを書く
イシュー番号がない	フッターを完全に省略する

---

クイックリファレンス

# Get your staged diff to paste into Copilot
git diff --staged

# Or get the last uncommitted working tree changes
git diff

種類の例やスコープのガイドラインについては、references/conventional-commits-guide.md を参照してください。