Claude Code で Conventional Commits を自動生成する — git diff から type と scope を推論させる

変更量が多い日ほど、コミットメッセージが「update」「fix」「wip」だけで埋まっていく — そんな経験はないでしょうか。私自身、一人で複数サイトのコードを触っているとログが荒れがちで、あとで「どのコミットで何を直したのか」を追うのに時間を取られることがありました。

Claude Code は git diff をそのまま読める環境にいるので、コミットメッセージ生成は本来とても得意な作業です。ただし、何の手当てもせずに「いい感じでコミットして」と頼むと、件名だけが整っていて本文が空、あるいは毎回違う書式、という状態になりがちです。

なぜ Conventional Commits を Claude Code に任せたいのか

Conventional Commits は feat:・fix:・refactor: などの接頭辞で変更種別を明示する規約です。feat: add login form のように一目で意図が分かるため、後から履歴を掘り返すときの負担が大幅に下がります。

手で書けば済む話ではあるのですが、毎回 type と scope を考え直すのは思っている以上に疲れます。そして疲れると、冒頭で挙げたような「update」一辺倒の履歴が出来上がります。これは Claude Code が肩代わりするのに向いている、典型的な「判断の繰り返し」です。

前提として、Conventional Commits の全体像や周辺ツールを押さえたい方は、先にClaude Code の Git ワークフロー自動化に目を通しておくと、この記事の位置づけがよく分かります。

最小構成で試す — 1つのプロンプトから始める

いきなりフックやスラッシュコマンドを作る前に、まずは単発のプロンプトで動きを確認するのがおすすめです。Claude Code のチャットに次のテキストをそのまま貼って、挙動を見てください。

次の手順でコミットメッセージを作成してください。
 
1. `git diff --staged` を実行して、ステージされた差分を確認する
2. 変更内容を 1〜2 行で要約する
3. 下記のテンプレートに沿って出力する(本文は不要なら省略可)
 
<type>(<scope>): <subject>
 
<body>
<footer>
 
type は feat / fix / refactor / perf / docs / test / chore / build / ci
のいずれかを選び、推論の根拠も 1 行だけ示してください。

ここで重要なのは「推論の根拠を 1 行だけ示す」という指示です。ただ結果だけを受け取ると、feat と fix の境界があいまいなコミットで違和感が残ります。根拠が見えると、その場で「これは refactor だから書き直して」と返しやすく、会話を1往復で終わらせやすくなります。

/commit スラッシュコマンドに育てる

挙動に満足したら、毎回貼り付けるのは面倒なのでスラッシュコマンド化します。プロジェクト直下の .claude/commands/ に次のファイルを置くだけで、/commit と打つだけで呼び出せるようになります。

---
description: "Conventional Commits 形式でコミットメッセージを生成する"
allowed-tools: Bash(git diff:*), Bash(git status:*)
---
 
`git diff --staged` を実行し、Conventional Commits 形式でコミットメッセージを
提案してください。規則は以下の通りです。
 
- type は feat / fix / refactor / perf / docs / test / chore / build / ci から選ぶ
- subject は 50 文字以内、命令形で書く
- body は「何を」「なぜ」の順で 1 段落以内にまとめる
- 機能追加か既存挙動の変更か迷ったら fix ではなく feat を選び、根拠を body に書く
 
最後に `git commit -m "..."` 形式で貼り付けやすい1行も併記してください。

allowed-tools で git diff と git status だけ許可しておくと、コミットの内容と関係ないコマンドが差し込まれる余地がなくなり、挙動が安定します。スラッシュコマンド全般の設計はClaude Code のカスタムスラッシュコマンドガイドにまとめたので、複数のコマンドを整理したい方は併せてご覧ください。

PostToolUse フックで差分を要約する自動化

もう一歩進めて、ステージングのタイミングで差分要約を自動生成したくなったら、フックを使います。PostToolUse で git add を検知し、そのまま差分の要約をメモリファイルに書き出す、という流れです。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"$(date -Iseconds)\" >> .claude/last-stage.log && git diff --staged --stat >> .claude/last-stage.log'"
          }
        ]
      }
    ]
  }
}

この構成の狙いは「コミットメッセージを書く直前に、そのセッション中に何をステージしたかを思い出せる」ことです。フックの仕組みそのものはClaude Code のフック自動化で詳しく扱っているので、イベント種別の全体像を押さえたい場合はそちらを参照してください。

注意点として、フックから直接 Claude に問い合わせるような設計は避けるのがおすすめです。コミット前は差分の「ログ化」だけに留め、メッセージ生成はユーザーが /commit を叩いたときに行う、と役割を分けたほうが、意図しないコミットが発生しにくくなります。

chore / refactor / fix の誤判定を減らす工夫

Conventional Commits の運用で一番もめるのが type の選び方です。Claude Code も例外ではなく、放っておくと以下のような取り違えが起きます。

• バグ修正なのに feat: 欠けていた機能を「追加した」と解釈してしまう
• リファクタなのに fix: 動作は変わらないはずなのに、差分を見て「壊れていたから直した」と誤認する
• 設定変更なのに chore: 依存関係の更新を全部 chore にまとめてしまい、build や ci が埋もれる

対策は、判断基準をプロジェクトの CLAUDE.md に短く書いておくことです。私が 4 サイト運用で使っている書き方を抜き出すと、次のような形になります。

## コミットメッセージの方針
 
- ユーザーから見て挙動が変わる追加/変更: feat
- 既にあった挙動が意図通りに戻る修正: fix
- 挙動を変えない内部構造の変更: refactor
- 依存更新はパッケージ名が分かる場合 build、わからなければ chore
- CI ファイル (`.github/workflows/` 等) のみの変更: ci
- 迷ったら feat か refactor を優先し、fix は使わない

「迷ったら fix を使わない」の一文が、体感でいちばん効きます。理由は単純で、fix は後から CHANGELOG に書くときに重み付けが強くなるため、安易に使うと「何も壊れていなかったのに fix が並ぶ」履歴になりやすいからです。プロジェクトのリリースノートをきれいに保ちたい方は、このルールを入れてみてください。

CLAUDE.md の設計そのものを見直したい場合は、CLAUDE.md とメモリの使い方で運用パターンをいくつか紹介しています。

実際のビフォー/アフター

イメージが掴みにくいと思うので、私が先週実際に行ったコミットで比較してみます。疲れた頭のまま手で書いた場合と、/commit に差分を読ませて生成した場合の違いです。

Before（手書き・疲れた状態）:

fix article slug

After（差分から生成）:

fix(articles): correct category path for newly-migrated MDX files

Two MDX files were moved from api-sdk/ to claude-code/ but their
internal links still pointed at the old category, causing 404s in
production. Update the links to match the new category.

手書きのほうは、後から何を直したのか分かるためにコミット本体を開く必要があります。生成されたほうは「どの不具合をどう直したのか」がコミットメッセージだけで完結しています。1 コミットごとに数分ずつしか変わらない差ですが、何百コミットも積み重なると、履歴を遡る時間として跳ね返ってきます。

明日からできる最初の一歩

すべての仕組みを一度に入れようとすると、かえって運用が続きません。まず今日は、.claude/commands/commit.md を 1 ファイルだけ作って /commit を叩いてみてください。5 分で設定でき、それだけでも履歴の品質は目に見えて変わります。

フックや CLAUDE.md の整備は、/commit が自分の書き方に馴染んできてから手を付けても遅くありません。道具は、自分の手に馴染んだ順に足していくのがいちばん長続きします。