コミットメッセージを「それっぽく一行で」済ませると、あとで自分が困る。Claude Code に任せるなら、そこを雑にしないほうがいい。粒度がバラついたメッセージは、履歴を読めなくするだけでなく、変更の単位まで崩す。逆に、作法を先に揃えておくと、コミットはただの作業ログではなく、あとから効くメモになる。
Claude Code は、雑に「コミットメッセージ書いて」と頼んでも一応それなりに出す。だが、その「それなり」は危ない。人間の頭の中にある意図が曖昧なままだと、AI は平気で広くまとめすぎるし、逆に細かすぎる差分を無理に1本へ寄せることもある。筆者は最初、ここを軽く見ていた。結果、1コミットに「UI の文言修正」と「不要ファイル削除」と「README 更新」が混ざり、あとで戻すときにかなり面倒だった。履歴が説明になっていない。あれは地味に痛い。
やるべきことは単純だ。Claude Code に「何を、どの粒度で、どういう型で」書かせるかを先に決める。
たとえば、こんな方針にする。
まずは、Claude Code にそのまま投げる依頼文を固定してしまうのが早い。毎回ゼロから考えるとブレるからだ。
変更内容を見て、コミットメッセージを日本語で1案ください。
次のルールで書いてください。
- 1行目は要約、50文字前後を目安にする
- 1行目は「〜する」「〜を修正する」のように、動作がわかる形にする
- 必要なら2行目を空けて、本文に理由や補足を書く
- 1つのコミットで説明しきれない変更は、まず分割案を出す
- 余計な装飾や絵文字は入れない
- 変更内容にないことは書かない
差分を見て、粒度が大きすぎるならそれも指摘してください。
この依頼のいいところは、ただメッセージを出させるだけでなく、粒度の破綻を先に検出させる点だ。ここを抜くと、見た目だけ整った「便利そうな文」が出て終わる。履歴としての価値は上がらない。
もう少し実務寄りにするなら、コミットメッセージの型まで決めてしまうと安定する。たとえば、次のような形だ。
コミットメッセージは次の形で統一してください。
<要約>
<必要な場合のみ補足>
要約は「何をしたか」がひと目でわかるようにする。
補足には、なぜその変更をしたか、見落としやすい影響範囲、元に戻すときの注意を書く。
英語の慣習に寄せるなら、要約を命令形にそろえる運用が扱いやすい。たとえば Fix login validation や Remove stale cache files のような形だ。日本語でも同じで、「〜を修正する」「〜を削除する」「〜に対応する」のように動詞をそろえると、一覧で見たときに気持ち悪さが減る。チームで揃える価値があるのはここだ。表現の好みより、履歴の読みやすさが勝つ。
大事なのは、Claude Code に「よさそうな文」を作らせるより、変更の単位を見させることだ。差分がでかいのに1本でまとめると、あとでどこが変わったか追えない。これは開発だけの話ではない。文書整理でも同じで、1つの作業に見えて、実際は「古いファイルの削除」「名前変更」「内容修正」が混ざっていることが多い。そこを分けずに丸めると、戻したいときに詰まる。
たとえば、ディレクトリ整理や書類作成で使うなら、こんな頼み方が効く。
このフォルダの変更内容を確認して、作業単位ごとにコミットメッセージ案を分けてください。
削除、移動、内容修正が混ざっている場合は、1本にまとめず分割案を先に出してください。
各案は「何をしたか」がわかる短い要約にしてください。
これで、Claude Code は「まとめて1本」に流れにくくなる。非エンジニアの作業でも、この考え方はそのまま通る。古いPDFの削除、案件名の変更、ひな形文書の修正が混ざっているなら、履歴も分ける。あとで「どの操作で何が起きたか」が追えるからだ。ファイル整理は見た目を整える作業に見えて、実際は履歴を整える作業でもある。
注意したいのは、Claude Code に丸投げすると、変更理由まで勝手に盛ることがある点だ。差分にない事情を入れ始めたら危ない。たとえば「パフォーマンス改善のため」と書いてあるのに、実際はただの文言修正だったりする。こういうのは後で読み返したときにノイズになる。理由を書くなら、コードやファイルの変更から直接言える範囲に絞るべきだ。
筆者が一度やらかしたのは、不要なファイル削除と設定変更を同じコミットに入れてしまったことだ。Claude Code にメッセージだけ書かせたら、どちらも「整理」に見える文が出てきた。見た目は整っていたが、実際には復旧時の手がかりが足りない。そこからは、先にこう指示するようにした。
コミットメッセージを書く前に、変更を次の3種類に分けてください。
- 挙動変更
- 文書変更
- 整理・削除
混ざっているなら、1コミットにまとめるべきでない理由も短く書いてください。
この一手間で、メッセージの質がかなり変わる。Claude Code は文章を整えるのは得意だが、作業の切り方まで自動で正しくなるわけではない。そこは人間が決める部分だ。
運用としては、毎回の自由入力より「自分のチーム用のひな形」を持つのが強い。たとえば、リポジトリの説明文や作業ルールに、コミットの型を1つ書いておく。Claude Code にそのルールを読ませてからメッセージを書かせれば、ブレが減る。チームで表記ゆれが出やすいなら、ここを先に固めたほうがいい。後から整えるのはだるい。
最後に、ひとつだけ強めに言う。Claude Code にコミットメッセージを「書かせる」のは簡単だが、「履歴として使える形にさせる」には指示が必要だ。粒度がそろっていない履歴は、あとで誰も読みたくない。そこを避けるために、要約の長さ、文体、本文の要否、分割の基準を最初に決める。これだけで、メッセージはただの説明文から、ちゃんと使える記録に変わる。
細かい書式の揺れが気になるなら、次に詰めるべきはコミットの型より、差分そのものの切り方だ。Claude Code に「どこで分けるべきか」を見させる運用にすると、メッセージの精度も一段上がる。そこまでやって初めて、AI に書かせる意味が出る。