commit-changes

コミットの概要

コミットメッセージは3回読まれます。次に git log を見る人、変更履歴を書く人、リリース内容を宣伝文やユーザーガイドのセクションにするよう依頼された LLM です。3者すべてに向けて、一度で書きましょう。

構成

1. 説明する前に検証する。 変更に見合った範囲で、プロジェクトのフォーマッターとテストを、プロジェクト独自のコマンドで実行します。概要ではテストの状況を事実として述べるため、正確でなければなりません。実行しなかったチェックは明記してください。
2. 実際の差分を読む — git status --short、git diff --stat、そして今回のセッションで自分が書いたのではないものの差分ハンクを確認します。会話の記憶をもとに要約せず、真実はツリーにあります。この機会にステージ済みのファイルにバイナリがないかも確認してください — バイナリには承認が必要を参照。
3. 差分に合わせた分量にする（以下の分量を参照）。次に、変更に見合う項目だけを使って、構成に沿って概要を作成する。
4. ユーザーに見せて止める。 まだコミットしてはいけません。execute-plan など、無人で実行されるスキルがこの手順を事前承認できる場合は、その旨が記されています。
5. 承認されたらコミットする。プッシュはしない。 同じ依頼の中で求められた場合に限り、プッシュしてください。

分量

メッセージの長さは変更の規模に合わせます。テンプレートの長さに合わせるのではありません。以下の読者はそれぞれ、冗長な文章の代償を払います。git log を流し読みする人は余分な文章を読み飛ばす必要があり、変更履歴を作成する LLM は、本文が大げさであれば、1行の修正を機能発表に膨らませてしまいます。

• 小さな修正 — 1つのハンク、1つのファイル、ユーザーに見える効果が1つ — には、件名と1〜3文を付けます。何が問題で、何を変更したかを述べ、差分から明らかでなければ理由も説明します。見出しは不要です。
• 中規模の変更 — 複数のファイル、1つの機能、または判断を伴う1つのバグ修正 — には、冒頭の段落に加えて、以下のセクションから内容のあるものだけを付けます。通常は判断事項と検証です。途中で見つかったバグには段落を設け、見つからなかった場合は見出しを設けません。
• 大規模な変更群 — 多数のファイル、複数の機能、またはマージ — には完全な構成を使います。以下のテンプレートはこのケース向けに書かれています。

各セクションのルールは同じです。伝えるべき事実がある場合に含め、なければ省きます。1文しかない見出しは、変更の規模がテンプレートより小さいことを示しています。「トレードオフ：なし」とは書かず、その項目自体を省きます。

読者によって長さは変わりません。削るときに残すべき内容だけが異なります。

• git log では、どの規模の変更でも、件名からユーザーにとって何が変わったかが分かる必要があります。
• 変更履歴には、そのまま掲載できる1文が必要です。小さな修正なら本文の最初の文がそれに当たるため、リスト内の誤字修正であっても、ユーザーに伝わる表現で書きます。
• 次のエンジニアには、差分から理由が分からない場合、その理由が必要です。理由が明白でない2行の修正なら理由を記し、理由が明らかな20ファイルのリファクタリングなら、形だけの判断事項セクションは設けません。

検証については、規模を理由に省略することはありません。短くする場合も、実行した内容と実行しなかった内容を簡潔に記します。

構成

大規模な変更群では、全体の構成を使います。小さな変更では、分量を参照し、件名と冒頭に加えて、内容のあるセクションだけを使います。

<subject: what a user can now do, or what changed for them — one line>

<opening: the problem it solves, in two or three sentences. What was wrong
before, and what the change is. This paragraph is the one a changelog or a
marketing blurb can lift whole, so write it in user terms, not module terms.>

<Themed sections with headings.> Group by what the reader cares about, not by
module or file. "The menu", "The tab strip", "Typography" beat
"src/menu" and "lib/render".

<Decisions worth keeping.> For each: what was chosen, what the alternative
was, and why it lost. A decision recorded without its alternative is an
assertion; with it, it is an argument the next person can re-open honestly.

<Bugs found along the way.> Especially pre-existing ones. Say plainly whether
a user would have felt it — that is what decides if it earns a changelog line.

<Trade-offs and costs.> What got worse, what a behaviour change costs someone
who relied on the old one.

<Closing: verification.> What was tested, what was confirmed by running the
app, and — separately and explicitly — **what was not**.

これらの要約が役立つ理由

• リファクタリングではなく、ユーザーに見える変更から書き始めます。 リファクタリングについては、変更内容ではなくその方法を説明する箇所として、後のほうに記載します。
• 何をしたかだけでなく、なぜそうしたかも書きます。 git diff を見れば何をしたかは分かります。ツリーから再現できないのは、判断の理由だけです。
• 採用しなかった選択肢も明記します。 「最初のメニューの中にネストするのではなく、その横に2つ目のメニューを置きました。ネストすると、3つの関数で深さを扱う必要があったためです」と書けば、次の人が「簡素化」の名目で元に戻さない理由が伝わります。
• 予想外のことを記録します。 プラットフォーム固有の癖、ドキュメントどおりに動かなかったAPI、重要な役割を果たしていた定数などです。こうした情報は、あとから再現できないものです。
• 未確認の事項は、独立した文で明示します。 下流のLLMは、機能がリリースされるとすぐに断言してしまいます。単体テストしか行っていない場合や、実際の動作を一度も確認していない場合は、読み飛ばされないようにその旨を書いてください。
• 項目を減らすのではなく、各項目を簡潔にします。 情報が密でも問題ありませんが、冗長なのはいけません。各行には、読者が推測できない事実を含めてください。変更に関するそうした事実が3つだけなら、要約は3文です。

誠実さに関するルール

要約は後続の工程で広く参照されるため、これらは通常以上に重要です。

• diffにない動作を説明してはいけません。
• 実行していないテストや手動確認を、実施したと主張してはいけません。
• 変更がフラグで制御されている場合は、フラグ名とデフォルト値を明記してください。
• プラットフォーム固有の変更は、その旨を明記してください。LinuxユーザーにWindows限定の機能を約束する変更履歴は、サポート問い合わせの原因になります。
• 何も書かないより、「視覚的には確認していません」と書いてください。何も書かれていないと、確認済みと受け取られます。

バイナリには承認が必要です

ユーザーに事前に確認せずに、バイナリファイルをコミットしてはいけません。 動画、音声ファイル、アーカイブ、コンパイル済みの成果物、フォント、大きな画像など、すべてが対象です。ファイル名とサイズを伝えて確認し、返答を待ってください。

gitの履歴は永久に残るためです。一度コミットされたblobは、後のコミットでファイルを削除しても、すべてのクローンに残り続けます。作業ツリーがクリーンに見えても、.git は容量を使い続けます。履歴から取り除くには履歴の書き換えが必要です。プライベートブランチなら簡単ですが、マージされ、プルされた後では影響が大きくなります。後から目立たずに取り消す方法はありません。そのため、この確認はコミット後ではなく、コミット前に行います。

作業ツリーではなく、コミット前に毎回ステージ済みのファイルを確認してください。バイナリは、numstatの両方の列に - と表示されます。

git diff --cached --numstat | awk '$1=="-" && $2=="-" {print $3}'

何か表示されたら、そこで止めて確認してください。各ファイルの内容、サイズ、そして変更に必要と思われる理由を伝えてください。通常は、コミットするより次のいずれかが望ましいです。

• 代わりにホストします。 メディア、サンプル録音、ダウンロード可能なペイロードは、アセットホストやオブジェクトストレージに置き、リポジトリにはURL、チェックサム（例：SHA-256）、取得手順だけを残してください。
• 代わりに生成します。 ビルド手順でファイルを生成できる場合は、その手順をコミットし、生成物は無視するようにしてください。

これは承認のための確認であり、禁止ではありません。少数のブランド素材のように、バイナリが本当にツリーに必要な場合もあります。何を許可するかはユーザーが決めます。重要なのは、判断を後から簡単に覆せるうちに、ユーザー自身が決められることです。

コミット

• ドキュメントも同じコミットに含めます。ドキュメントも変更の一部です。そのため、判断について言及する概要を書く場合は、プロジェクトで判断記録を管理しているなら、その記録も一緒に含めます。
• 既存のコミットを修正するか、新しいコミットを作成するかは判断事項なので、決めつけずに明記する価値があります。既存のコミットと同じ作業単位であれば修正し、別個の工程であれば新しいコミットを作成します。どちらを選んだか、その理由とともに伝えれば、ユーザーが方針を変更できます。
• メッセージの末尾には、自分の環境またはプロジェクトで必要とされている共同作成者や署名のトレーラーを付けます。他のエージェントのセッションからコピーしたものは決して使いません。
• メッセージ本文はファイルまたはヒアドキュメントから指定します。-m フラグを連続して使ってはいけません。前述の構成が保持されないためです。Windows PowerShell では、本文をファイルに書き込み、git commit -F path を使う方法を推奨します。
• **プッシュしないでください。**後から行う場合も、便宜上行う場合も同様です。

注意点

• 未追跡の不要ファイル。 git add -A の前に git status で不要なファイルがないか確認し、コミット対象から除外します。パス除外のパススペックは特殊なファイル名で失敗する場合があります。ステージング後に、前ではなく、git status で確認してください。git add -A はバイナリファイルを誤って含めてしまう原因にもなります。実行後に上記の numstat チェックを行ってください。
• 意図しない再フォーマット。 作業開始時にツリーがクリーンでないと、フォーマッターが変更と無関係なファイルまで変更することがあります。意図的な変更に見せかけず、そのことを伝えてください。
• 古いビルド。 作業中にユーザーがテストを行っていた場合、ユーザーのスクリーンショットが説明対象の変更より前の状態を示している可能性があります。ユーザーのフィードバックとコードの内容が食い違う場合は、その旨を一文添えるとよいでしょう。