Git差分からコミットメッセージを作るAIプロンプト｜変更理由まで伝わる実務テンプレート
Gitの差分は確認できても、「何を変えたか」を短い一文にまとめるところで手が止まる。そんなときに使えるのが、ステージ済みの差分からコミットメッセージ案を作るプロンプトです。
対象は、Gitを使い始めた人から、チーム内の書式をそろえたい開発者まで。単なる変更ファイルの列挙ではなく、変更の目的や影響が読み取れるメッセージを目指します。
この記事で分かることは次のとおりです。
- コピペして使える基本プロンプト
- AIに渡すべき入力情報
- 1行形式と本文付き形式の使い分け
- 曖昧なメッセージを改善する方法
- Conventional Commitsに合わせる追加指定
このプロンプトで作れるもの
作りたいのは、差分の要約ではなく、履歴を読む人が変更の意図を判断できるコミットメッセージです。
たとえば、ログイン処理の例外対応を追加した差分に対して、次のような出力を狙います。
ログイン失敗時のエラー処理を追加
認証APIのタイムアウトと不正レスポンスを個別に処理し、
利用者が再試行できるエラーメッセージを表示する。
この形なら、変更したファイル名を知らない人でも、次の3点を把握できます。
- 何を変えたか
- なぜ変えたか
- 利用者や後続処理に何が起きるか
Git公式ドキュメントによると、git diff --stagedは次のコミットに含まれるステージ済み変更を確認するコマンドです。AIに渡す材料も、原則としてこの範囲にそろえると、未ステージの作業が混ざりません。
ここがポイント: AIには「変更内容」だけでなく「変更理由」も渡します。差分だけで理由を断定させると、もっともらしい誤説明が入りやすくなります。
コピペ用の基本プロンプト
次のテンプレートは、通常の1行メッセージと、必要に応じた本文を出力させる構成です。
あなたはGitの変更履歴を整理する開発者です。
以下の情報を基に、コミットメッセージ案を作成してください。
## 変更の目的
{この変更が必要になった理由}
## ステージ済みファイル
{git status --short の結果}
## ステージ済み差分
{git diff --staged の結果}
## プロジェクトのルール
- 使用言語: {日本語 / 英語}
- 1行目の上限: {例: 50文字}
- 接頭辞: {なし / feat / fix / docs / refactor など}
- チケット表記: {不要 / 例: Refs: #123}
## 出力条件
1. 実際の差分で確認できる内容だけを書く
2. 1行目は「何をどう変えたか」が分かる表現にする
3. 変更理由や注意点が必要な場合だけ、空行の後に本文を付ける
4. 複数の独立した変更が混在している場合は、その旨を指摘する
5. 判断材料が不足している内容は推測せず、確認事項として示す
6. コミットメッセージ案を3件提示する
## 出力形式
### 案1
{コミットメッセージ}
### 案2
{コミットメッセージ}
### 案3
{コミットメッセージ}
### 確認事項
{不足情報がなければ「なし」}
このテンプレートの中心は、5番目の「推測しない」という条件です。AIは差分から意図を補完できますが、その意図が実際の仕様と一致するとは限りません。確認事項を別枠にすると、推測がコミット本文へ紛れ込むのを抑えられます。
なお、外部のAIサービスへ差分を貼り付ける前に、APIキー、アクセストークン、個人情報、未公開の仕様が含まれていないか確認してください。社内ルールでコードの外部送信が禁止されている場合は、差分そのものではなく、許可された範囲で変更概要を入力します。
入力時に変える項目
毎回変えるのは変更目的と差分、固定するのはチームの書式です。 ここを分けると、繰り返し使っても出力がぶれにくくなります。
毎回入力する項目
{この変更が必要になった理由}：不具合、要望、保守上の問題など{git status --short の結果}：変更、追加、削除されたファイル{git diff --staged の結果}：実際にコミットする差分{チケット番号}：履歴から課題へ移動できるようにする場合
git status --shortは作業ツリーの状態を短い形式で表示します。ただし、ステージ済みと未ステージの変更が同時に存在する場合があるため、メッセージ作成の中心材料にはgit diff --stagedを使います。
固定しておく項目
- 日本語または英語
- 1行目の文字数
- 句点を付けるか
featやfixなどの種別を使うか- scopeを付けるか
- チケット番号や共同作業者の記載方法
- 本文を付ける条件
チームの既存コミットを数件確認し、共通する書式をこの欄へ移しておくと実用的です。AIに毎回「分かりやすく書いて」と頼むより、判断基準が明確になります。
NG例と改善例
悪いコミットメッセージは、短いことではなく、変更後の状態を特定できないことが問題です。
NG例1：作業名しか書いていない
修正
これでは、対象も結果も分かりません。
改善するなら、差分に現れている動作を入れます。
検索条件を解除した際に一覧を再取得
「検索を修正」のような広い表現より、何が起きるようになったのかが伝わります。
NG例2：ファイル名を並べただけ
config.pyとclient.pyを更新
ファイル名は差分から確認できます。コミットメッセージには、その変更が何を実現したかを残します。
API接続のタイムアウト設定を環境変数へ分離
NG例3：差分から確認できない成果を断定する
API通信を完全に安定化
テスト結果や運用データがなければ、「完全に安定化」は確認できません。差分で確認できる変更へ戻します。
APIタイムアウト時の再試行処理を追加
NGプロンプト
この差分から良いコミットメッセージを作ってください。
{差分}
「良い」の基準も、言語も、出力形式もありません。そのため、長すぎる説明、存在しない変更理由、チームで使わない接頭辞が入りやすくなります。
改善プロンプト
次のステージ済み差分から、日本語のコミットメッセージを作成してください。
- 1行目は50文字以内
- 「何をどう変えたか」を具体的に書く
- 差分にない目的や効果は推測しない
- 理由の説明が必要な場合だけ本文を付ける
- 独立した変更が混在していれば、分割候補を示す
変更理由:
{変更理由}
差分:
{git diff --staged の結果}
改善点は、文字数を指定したことだけではありません。AIが判断してよい範囲と、判断してはいけない範囲を分けたことが重要です。
出力を安定させる3つのコツ
安定した出力には、書式指定より先に、コミット対象を正しく限定する必要があります。
1. ステージ済み差分だけを渡す
git diffだけでは、通常は作業ツリーとステージング領域の差が表示されます。次のコミットに含まれる内容を確認するなら、Gitのgit-diff公式ドキュメントにあるgit diff --stagedまたは同義のgit diff --cachedを使います。
git status --short
git diff --staged
AIが出したメッセージは、差分を確認したうえで採用します。AIに差分を渡す操作と、実際にgit commitを実行する操作は分けてください。
2. 変更理由を1〜2文で補う
コードには「どう変えたか」は現れますが、「なぜその方法を選んだか」は残らないことがあります。
たとえば、リトライ回数を3回から1回へ変更した差分だけでは、負荷対策なのか、応答時間の短縮なのか判断できません。そこで次のように補います。
変更の目的:
外部API障害時にリクエストが滞留するため、再試行回数を減らす。
この一文があれば、AIは数値変更の説明だけでなく、変更理由を本文へ反映できます。
3. 1コミットに複数の目的がないか確認させる
認証エラーの修正とREADMEの全面改稿が同じ差分に入っている場合、1行のメッセージへ押し込むと焦点がぼやけます。
プロンプトに次の条件を追加してください。
差分に独立した目的が複数ある場合は、メッセージを作る前に
「分割推奨」として変更グループを箇条書きで示してください。
ここで見落とされやすいのは、AIが優れた文章を作っても、コミットの単位そのものは改善されないことです。メッセージが長くなり続ける場合は、文章ではなくステージング範囲を見直します。
Conventional Commits対応テンプレート
自動リリースや変更履歴生成にコミットを利用するなら、自由文より構造化された形式が向いています。
Conventional Commits 1.0.0では、基本形を次のように定めています。
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
featは機能追加、fixは不具合修正に使います。破壊的変更は!またはBREAKING CHANGE:フッターで示します。一方、docsやrefactorなどの追加種別は、プロジェクト側のルールとして決める必要があります。
次のプロンプトは、その形式へ限定した版です。
以下の変更情報から、Conventional Commits 1.0.0形式の
コミットメッセージ案を1件作成してください。
## 変更目的
{変更理由}
## ステージ済み差分
{git diff --staged の結果}
## 使用可能なtype
{feat, fix, docs, refactor, test, chore}
## scope候補
{api, auth, ui, docs など。不要なら「なし」}
## 条件
- 形式は type(scope): description とする
- scopeが不要なら省略する
- descriptionは{英語 / 日本語}で{文字数}以内にする
- typeは差分の主目的から1つだけ選ぶ
- 破壊的変更を差分と入力情報から確認できる場合だけ ! を付ける
- 本文には変更理由を書く
- 差分にない効果を推測しない
- 判断できない場合はメッセージを完成させず、必要な確認事項を示す
## 出力形式
コミットメッセージだけをコードブロックで出力する。
たとえば、認証APIのタイムアウト処理を追加した場合は次の形になります。
fix(auth): 認証APIのタイムアウト処理を追加
応答待ちのままログイン画面が停止する問題を防ぎ、
再試行可能なエラーを返す。
ただし、Conventional Commitsはすべてのプロジェクトに必須ではありません。既存履歴が日本語の体言止めで統一されているなら、そのルールを優先した方が履歴を追いやすくなります。
用途別の短い追加指定
基本テンプレートを残したまま、必要な出力だけ追加指定すると使い回しやすくなります。
1行だけ欲しい場合
本文と補足説明は出力せず、コミットの1行目だけを提示してください。
候補は3件とし、それぞれ{50}文字以内にしてください。
本文付きにしたい場合
1行目の後に空行を入れ、本文では次の順に説明してください。
- 変更の背景
- 主な変更
- 確認したテスト
入力にないテスト結果は作らず、「未確認」と明記してください。
チケット番号を付けたい場合
入力されたチケット番号をフッターへ「Refs: {チケット番号}」の形式で記載してください。
番号が未入力ならフッター自体を省略してください。
日本語と英語を比較したい場合
同じ差分について、日本語案と英語案を1件ずつ提示してください。
どちらも同じ変更範囲と意図を表し、英語案に情報を追加しないでください。
実行前チェックリスト
最後に、生成されたメッセージをそのまま採用せず、次を確認します。
- ステージ済み差分だけを説明しているか
- 「修正」「更新」だけで終わっていないか
- ファイル名の列挙ではなく、変更後の動作が分かるか
- 差分にない効果やテスト結果を断定していないか
- 変更理由が実際の目的と一致しているか
- チームの言語、文字数、接頭辞に合っているか
- 独立した変更を1コミットへ詰め込んでいないか
- 機密情報を外部サービスへ送っていないか
Gitのgit-commit公式ドキュメントにもあるとおり、コミット対象の選択とメッセージ作成は別の判断です。AIが担当できるのは、与えられた材料を読みやすい候補へ整えるところまで。最終的に見るべきなのは文章の巧さではなく、そのメッセージがステージ済み差分を正確に説明しているかです。
メッセージがどうしても一文に収まらないときは、プロンプトを長くする前にgit diff --stagedを見直してください。次の分岐点は、文章の調整ではなく、コミットを分けるべきかどうかです。