AIでコミットメッセージを自動生成する:prepare-commit-msgフックでの実装

概要

git commit を実行してエディタが開いた時点で、ステージ済みの差分から作った下書きがすでに入っている状態にします。使うのは Git 標準の prepare-commit-msg フックと、LLM を呼び出すコマンドだけです。

この記事で作るものは次の3つです。

  • シェルスクリプトだけで動く最小構成のフック(CLI 型の AI ツールを呼ぶ)
  • API を直接呼ぶ Python 版のフック
  • 秘密情報を外に出さないためのガード(除外パス・パターン検知・無効化スイッチ)

設計の方針は3つあります。

  1. AI は下書きだけを書く。確定させるのは人間で、エディタで必ず目を通してから保存する
  2. フックが失敗してもコミットを止めない。AI が使えない環境では普段どおりに動く
  3. 差分を外部に送る前にフィルタをかける

環境

  • Git 2.x(prepare-commit-msg フックと pathspec の :(exclude) が使えること)
  • macOS / Linux の POSIX シェル
  • LLM の呼び出し手段は次のどちらか
  • CLI 版: Claude Code の claude -p(非対話モード)。ほかの CLI でも、標準入力を受けて標準出力に返すものなら差し替えられます
  • API 版: Python 3.10 以上と anthropic SDK(pip install anthropic)。環境変数 ANTHROPIC_API_KEY を設定しておきます

発生した問題

コミットメッセージでよく見かける問題は次のとおりです。

  • fix、update、wip のように、何を変えたのかが読み取れないメッセージが並ぶ
  • 1つのコミットに複数の変更が混ざっていて、件名にすると要約しきれない
  • Conventional Commits などの規約があっても、プレフィックスの選び方が人によって違う

差分を読んで要約するのは LLM が得意な作業です。ただし git diff をそのまま外部に送る運用は、秘密情報の扱いで事故が起きやすくなります。

原因

メッセージが雑になるのは、書く人の能力の問題というより、書くタイミングの問題です。コミットする時点では頭が次の作業に移っていて、差分を読み返す余裕がありません。最初の一文を考える手間を AI に任せて、人間は確認と「なぜ変えたか」の追記に集中する、という分担にします。

対応方法

prepare-commit-msg フックの仕様を押さえておきます。

引数 内容
$1 コミットメッセージを書き込むファイルのパス
$2 メッセージの出どころ(message / template / merge / squash / commit。通常のエディタ起動では空)
$3 $2 が commit の場合のコミットSHA(--amend など)

$2 が空のときだけ生成します。 -m で自分で書いたとき、マージ、amend のときは何もしません。これを入れておかないと、手で書いたメッセージを AI が上書きしてしまいます。

実装例

1. プロンプト

出力形式は細かく指定しておきます。LLM はコードフェンスや前置きを付けたがるので、後処理でも取り除きます。

あなたはGitのコミットメッセージを書くアシスタントです。
標準入力で与えられるステージ済みの差分(git diff --cached)から、
Conventional Commits形式のコミットメッセージを1つだけ書いてください。

ルール:
- 1行目: <type>(<scope>): <要約>  typeは feat/fix/docs/refactor/test/chore/perf/ci のいずれか
- 1行目は日本語で50文字以内。scopeが不明なら省略してよい
- 2行目は空行
- 3行目以降: 変更点を箇条書きで3つまで。差分から読み取れる事実だけを書く
- 変更の「理由」は推測で書かない
- 前置き・説明・コードフェンスは出力しない。メッセージ本文だけを出力する

「理由は推測で書かない」というルールが特に重要です。差分からわかるのは「何を変えたか」までで、「なぜ変えたか」はわかりません。ここを AI に書かせると、もっともらしい作り話が履歴に残ります。

2. シェル版フック(CLI を使う)

.git/hooks/prepare-commit-msg として保存し、実行権限を付けます。

#!/bin/sh
# prepare-commit-msg: ステージ済み差分からコミットメッセージの下書きを生成する
MSG_FILE="$1"
SOURCE="$2"

# -m / merge / squash / amend / template のときは何もしない
[ -n "$SOURCE" ] && exit 0
# 一時的に無効化したいとき: AI_COMMIT_DISABLE=1 git commit
[ -n "$AI_COMMIT_DISABLE" ] && exit 0
# CLI が無い環境では何もしない(コミットは止めない)
command -v claude >/dev/null 2>&1 || exit 0

# 送信対象から除外するパス(ロックファイル・環境変数ファイル・鍵類)
DIFF=$(git diff --cached --no-color -- . \
  ':(exclude)*.lock' \
  ':(exclude)package-lock.json' \
  ':(exclude).env*' \
  ':(exclude)*.pem' \
  ':(exclude)*.key' \
  | head -c 20000)

[ -z "$DIFF" ] && exit 0

# 秘密情報らしきパターンがあれば送信しない
if printf '%s' "$DIFF" | grep -Eq 'AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|(api[_-]?key|secret|password|token)[[:space:]]*[:=]'; then
  echo "[ai-commit] 秘密情報らしき文字列を検出したため生成をスキップしました" >&2
  exit 0
fi

PROMPT_FILE="$(git rev-parse --show-toplevel)/.githooks/commit-prompt.txt"
[ -f "$PROMPT_FILE" ] || exit 0

GENERATED=$(printf '%s' "$DIFF" | claude -p "$(cat "$PROMPT_FILE")" 2>/dev/null) || exit 0

# コードフェンスが混ざった場合に取り除く
GENERATED=$(printf '%s\n' "$GENERATED" | sed '/^```/d')
[ -z "$GENERATED" ] && exit 0

# Git が用意したコメント行の前に下書きを差し込む
{
  printf '%s\n\n' "$GENERATED"
  printf '# ↑ AIによる下書きです。内容を確認し、「なぜ」を追記してください。\n'
  cat "$MSG_FILE"
} > "$MSG_FILE.tmp" && mv "$MSG_FILE.tmp" "$MSG_FILE"

exit 0

ポイントは次のとおりです。

  • どの経路でも exit 0 で終わります。フックが 0 以外を返すとコミット自体が中断されるため、AI 側の失敗をコミットの失敗にしません
  • head -c 20000 で送るサイズを制限しています。大きな差分はそもそもコミットを分けるべきというサインでもあります
  • 秘密情報の検知は簡易的なものです。誤検知も見逃しもありえるので、これだけに頼らず、後述の運用ルールと組み合わせてください

3. Python 版フック(API を直接呼ぶ)

CLI を入れられない環境や、モデルとトークン上限を細かく指定したい場合は API を直接呼びます。

#!/usr/bin/env python3
"""prepare-commit-msg: ステージ済み差分からコミットメッセージの下書きを生成する"""
import os
import re
import subprocess
import sys
from pathlib import Path

MAX_CHARS = 20_000
EXCLUDES = [
    ":(exclude)*.lock",
    ":(exclude)package-lock.json",
    ":(exclude).env*",
    ":(exclude)*.pem",
    ":(exclude)*.key",
]
SECRET_PATTERN = re.compile(
    r"AKIA[0-9A-Z]{16}"
    r"|-----BEGIN [A-Z ]*PRIVATE KEY-----"
    r"|(api[_-]?key|secret|password|token)\s*[:=]",
    re.IGNORECASE,
)


def staged_diff() -> str:
    result = subprocess.run(
        ["git", "diff", "--cached", "--no-color", "--", ".", *EXCLUDES],
        capture_output=True, text=True, check=True,
    )
    return result.stdout[:MAX_CHARS]


def generate(diff: str, prompt: str) -> str:
    import anthropic  # 未インストール環境でもフック全体は落とさない

    client = anthropic.Anthropic()  # ANTHROPIC_API_KEY を環境変数から読む
    response = client.messages.create(
        model=os.environ.get("AI_COMMIT_MODEL", "claude-haiku-5-5"),
        max_tokens=400,
        system=prompt,
        messages=[{"role": "user", "content": diff}],
    )
    text = response.content[0].text
    return "\n".join(l for l in text.splitlines() if not l.startswith("```")).strip()


def main() -> int:
    msg_file = Path(sys.argv[1])
    source = sys.argv[2] if len(sys.argv) > 2 else ""
    if source or os.environ.get("AI_COMMIT_DISABLE"):
        return 0

    try:
        diff = staged_diff()
        if not diff.strip():
            return 0
        if SECRET_PATTERN.search(diff):
            print("[ai-commit] 秘密情報らしき文字列を検出したため生成をスキップしました",
                  file=sys.stderr)
            return 0

        root = subprocess.run(["git", "rev-parse", "--show-toplevel"],
                              capture_output=True, text=True, check=True).stdout.strip()
        prompt = (Path(root) / ".githooks" / "commit-prompt.txt").read_text(encoding="utf-8")

        message = generate(diff, prompt)
        if not message:
            return 0

        original = msg_file.read_text(encoding="utf-8")
        msg_file.write_text(
            message
            + "\n\n# ↑ AIによる下書きです。内容を確認し、「なぜ」を追記してください。\n"
            + original,
            encoding="utf-8",
        )
    except Exception as e:  # どんな失敗でもコミットは止めない
        print(f"[ai-commit] 生成をスキップしました: {e.__class__.__name__}", file=sys.stderr)
    return 0


if __name__ == "__main__":
    sys.exit(main())
  • 要約用途なので、既定のモデルは軽量で応答の速いものにしています。環境変数 AI_COMMIT_MODEL で切り替えられます
  • 例外のメッセージをそのまま表示すると、レスポンスの一部が端末に出ることがあるため、クラス名だけを出しています

4. チームで共有する(core.hooksPath)

.git/hooks はリポジトリにコミットされません。チームで共有するならディレクトリを分けて、core.hooksPath で指定します。

mkdir -p .githooks
# 上記のフックとプロンプトを配置
#   .githooks/prepare-commit-msg
#   .githooks/commit-prompt.txt
chmod +x .githooks/prepare-commit-msg
git config core.hooksPath .githooks

core.hooksPath はクローンごとに設定が必要です。README のセットアップ手順に1行足しておきましょう。

確認方法

導入後、次の順番で動作を確認してください。

# 1. 通常のコミット: エディタに下書きが入っていること
echo "hello" > sample.txt
git add sample.txt
git commit

# 2. -m 指定: AI が呼ばれず、指定したメッセージがそのまま使われること
git commit --allow-empty -m "chore: test"

# 3. 無効化スイッチ: 下書きが入らないこと
AI_COMMIT_DISABLE=1 git commit

# 4. 秘密情報ガード: スキップのメッセージが標準エラーに出ること
echo 'password = "dummy"' > guard-test.txt
git add guard-test.txt
git commit
git restore --staged guard-test.txt && rm guard-test.txt

# 5. AI ツールが無い環境: PATH から外してもコミットできること
PATH=/usr/bin:/bin git commit

4 では本物の秘密情報を使わず、必ずダミー文字列で試してください。

注意点

  • 差分は外部サービスに送信されます。 業務のリポジトリでは、契約・社内規程・利用する AI サービスのデータ取り扱い条件を確認してから導入してください。ソースコードの外部送信が認められていない場合は、ローカル LLM を使うか、導入を見送るのが正しい判断です
  • 秘密情報の検知は保険にすぎません。 .env を .gitignore に入れる、シークレットスキャナを併用する、といった基本的な対策のほうが優先です
  • 応答待ちの時間が発生します。 環境やモデルによっては、エディタが開くまで数秒以上かかります。気になる場合は軽量モデルを選ぶか、無効化スイッチを使ってください。なお macOS には標準で timeout コマンドがありません(coreutils の gtimeout などで代用できます)
  • 生成されたメッセージを無確認で確定しない。 差分に表れない意図や、関連する課題の背景は、人間が書き足す部分です
  • git commit --no-verify で飛ばせるのは pre-commit と commit-msg で、prepare-commit-msg は飛ばせません。一時的に止めたいときは AI_COMMIT_DISABLE=1 を使ってください

まとめ

  • prepare-commit-msg フックを使えば、既存の Git の操作を変えずに AI の下書きを差し込める
  • $2 が空のときだけ生成し、失敗時も exit 0 でコミットを止めない
  • 差分は送信前に除外パスとパターンで絞り込み、外部に送ってよいかは事前に確認する
  • AI が書くのは「何を変えたか」まで。「なぜ変えたか」は人間が書く

「一文目を書く手間」が減るだけでも、履歴の質はかなり変わります。まずは個人のリポジトリで試して、自分のコミットの癖に合わせてプロンプトを調整するところから始めてみてください。

\ 最新情報をチェック /

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。