commit-message-storyteller

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

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

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

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

前提条件

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

• git diff または git diff --staged の出力
• 変更した内容とその理由の説明
• 変更したファイルの一覧

仕組み

ステップ 1：変更の背景を把握する

ユーザーに次の内容を尋ねるか、diff から推測してください。

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

ユーザーが生の git diff を提示した場合は、diff からこれらの背景を自動的に抽出してください。

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

次のガイドを使って、変更を Conventional Commits の種類に対応付けてください。

種類	使用する場面
feat	新しい機能や能力を追加する
fix	バグや誤った動作を修正する
refactor	動作を変えずにコードを再構成する
perf	パフォーマンスを改善する変更
docs	ドキュメントのみの変更
style	書式、空白、セミコロンの不足などの変更（ロジックの変更なし）
test	テストの追加や更新
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 に示されています）
• 変更前に存在していた問題を説明します
• 関連する場合は、検討した代替案にも触れます
• 各行を 100 文字未満にします
• 件名との間に空行を入れます

フッター：

• Issue を参照します：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: フッターを自動的に追加する
ユーザーが「短くして」と言った	本文を省略し、明確な件名だけを書く
Issue 番号がない	フッター全体を省略する

---

クイックリファレンス

# 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 を参照してください。