安全なコミットと迅速なレビューのための Claude Code Git フック

なぜコミット時の自動化が重要か

多くのレビューの手間は「難しい」コードから来るのではなく、コミットに紛れ込む避けられるミスから来ます：デバッグフラグを残したまま、差分を騒がしくする未整形ファイル、テストの更新漏れ、あるいは設定にコピーされた秘密情報。どれも小さい問題ですが、重なるときれいなレビューを遅いやり取りに変えます。

コミット時の自動化はこれを止める最も簡単な場所です。チェックがコミット直前に実行されれば、変更がまだ頭の中にあるうちに問題を拾えます。ミスの修正は数秒で済みます。数日後にプルリクで見つかり、さらにコミットが積み重なったあとでレビュワーが何が起きたのかを尋ねるのと比べれば格段に効率的です。

Git フックはローカルで CI を待たずに動くため実用的な道具ですが、魔法ではありません。フックはスキップされたり、誤設定されたり、マシンごとに不揃いになったりします。単独で品質を保証することはできません。ゲートではなくガードレールと考えてください。

フックが最も役立つのは「レビュー税」を防ぐことです。つまり、繰り返し現れる低付加価値の指摘を減らすこと。よくある例はトークンに見える機密文字列、フォーマットやリンタのノイズ、「適切なテストを実行したか？」という基本チェック、そしてレビュワーが意図を理解するのに役立つ小さなコンテキスト要約です。

ここで Claude Code の git フックがうまくはまります：単調な検証作業を行い、コミットの瞬間に読みやすい文脈を少し追加できます。

期待値を合わせることが重要です。ローカルフックは速く予測可能に保ち、皆が嫌がらないようにしてください。速いチェックはラップトップで、遅いチェックは後で行います。良い分割例は、コミット時に数秒、CI で数分です。もしフックが定常的に長時間かかり人が "skip" を使うようになると、リポジトリを守れなくなります。

シンプルな例：あるモジュールを変更し、関数を少しリファクタリングしたとします。自動化がなければレビュワーは 400 行の移動に目を通し、テストについて何も言及がなく、基本的な質問をしなければなりません。コミット時チェックがあれば、コミットは整形され、関連するテスト群が実行され、コミットメッセージには短い要約が入ります。レビューは本来の場所、つまり設計に集中できます。

Claude Code が git フックに付け加えるもの

Git フックは単純なチェックに向いていますが、多くは「はい/いいえ」ルールで止まります："ファイルは整形されているか？" や "リンタは実行されたか？" のように。Claude Code はステージされた差分やいくつかの関連ファイルを読み取って、人間がどのように変更をレビューするかに近い判断を軽量に付け加えることができます。

Claude Code の git フックでは、フックはリポジトリに存在するものだけでなく、実際にあなたが変更したものを見ることができます。これにより自動化はより選択的になります。触ったモジュール、編集された設定ファイル、新しい環境変数に集中でき、すべてのコミットをフルビルドとして扱う必要がなくなります。

「差分を読んで考える」ことで効果を発揮する実用的な作業例：

• 少し難読化されていたり行に分かれていたりする場合でも、API キー、トークン、秘密鍵のような可能性のある秘密をフラグ化する。
• ステージされたファイルだけにコンテキストを踏まえてフォーマッタを走らせ、フォーマッタが無関係な大規模変更を起こすときは警告する。
• 変更内容に基づいてテストを提案または要求する（例：支払いロジックを触ったらこのユニットテスト群を実行）— 全部を走らせるのではなく。
• 差分からレビュワー向けの短い要約を生成する：何が変わったか、なぜ、リスクのある箇所、検証方法。

制約は重要です。遅いフックはスキップされます。目的は一般的なミスを早期にキャッチするガードレールを増やすことであって、コミットごとに第2の CI を実行することではありません。

速度と信頼性を最優先に

良いルールは：数秒で終わらないものはおそらく CI や pre-push に置くべき、ということです。多くのチームはコミット時にクイックなローカルチェックを行い、重いテストスイートは後回しにします。

障害モードを設計しておきましょう。モデル呼び出しがタイムアウトしたときにコミットをブロックするか、より単純なチェックにフォールバックするかを決めておきます。フォールバックがあるとワークフローが予測可能になり、フックを無効にする習慣を避けられます。

オンライン vs オフラインとプライバシー

一部の環境はホステッドモデルを呼び出し、他はより隔離された環境で実行します。どのコードを開発機から出すか（あるいは出さないか）を決め、送る内容を制限してください。ステージされた差分と少数の参照ファイルで十分なことが多いです。

機密性の高いリポジトリで作業する場合は、どこで解析が走るか、何がログに残るかを明示してください。具体例：コミットが STRIPE_SECRET=... のような新しい設定値を追加する場合、フックはコミットを止めて何が危険に見えるかを説明し、リモートに到達する前にシークレットマネージャかローカルの env ファイルに移すことを提案できます。

適切なフックを選び、速く保つ

人がフックを有効にし続け、コミットを恐れないようにするには、正しい仕事に正しいフックを使い、遅い処理をホットパスから外すことが重要です。

チェックを置く場所の単純なマップ：

• pre-commit: 明白な問題をブロックする高速ローカルチェック（フォーマット、秘密スキャン、クイックリン ト）
• commit-msg: メッセージだけで済むチェック（チケット ID、長さ、conventional format）
• pre-push: 共有レポジトリに送る前にキャッチする価値のある重い作業（遅いテスト、型チェック、ビルド）

Claude Code の git フックを追加するときは、それが即座に現れる親切なレビュワーのように振る舞うようにしてください。ネットワーク呼び出し、フルテストスイート、長時間の解析が必要なものは pre-push や CI に置きましょう。

何をどこで走らせるかを決める実用的な方法は、速度と影響で分類することです。高リスクの問題を捕まえられて数秒で終わるなら pre-commit に置きます。30～90 秒かかるなら pre-push に移すか、特定ファイルが変更されたときだけ実行します。

チームはまた施行レベルについて明確にする必要があります。個人レポだとオプトインでも良いでしょう。チームリポでは基本（秘密、フォーマット、コミットメッセージルール）は強制し、ローカルでは重いチェックは助言として扱い、CI を最終ゲートにするのが一般的です。

フックの出力は思ったより大事です。失敗したフックは何が起きたかと次に何をすべきかを示すべきです。メッセージは短く具体的に。可能なら正確なファイルと行を示し、1 つの明確な修正コマンドを出し、本当に緊急時にのみ回避する方法（いつ回避すべきでないか）を説明し、「verbose」を要求するまで巨大なログは出さないでください。

例：Koder.ai からプロジェクトをエクスポートしてローカルでコミットを始めると、速い pre-commit フックはコピーされた API トークンを即座に検出できます。一方で pre-push は "変更モジュールだけのテスト" を遅めに実行して、誰かがブランチを共有する前に捕まえます。

コミット前に秘密をブロックする

シークレットとは、あなたとして行動できたりプライベートなシステムへアクセスできたりするものを指します。API トークン、OAuth クライアントシークレット、クラウドキー、DB パスワード、プライベートな Webhook URL、署名鍵、そして一時的なテスト資格情報です。ひとつの誤ってコミットされたものがフォークや CI ログ、あるいは貼られた差分に残れば、もはや一時的ではありません。

最も簡単な勝ち筋は、あなたがこれからコミットしようとしているものだけをスキャンすることです。フックはリポジトリ全体ではなくステージされた変更（インデックス）をチェックすべきです。これにより速くなり、触っていない古いファイルからのノイズを避けられます。フィードバックも公平に感じられます：「このコミットに問題がある」ではなく「あなたのリポジトリはかつて問題があった」ではない形です。

早めにフラグを立てる典型的な対象は、高エントロピーなトークン（長くランダムに見える文字列）、既知のキー形式（AWS キー、GitHub トークン、JWT）、設定ファイルでの password=... や api_key: ... のようなパターン、埋め込み認証情報を含む private URL、.env ファイルや本番設定のコピーなどです。

誤検出は起きます。特にテストデータ、ハッシュ、例示ドキュメントで。狭い allowlist を導入して、フック全体を無効にせずに先に進めるようにしましょう。allowlist は狭めに：フィクスチャの正確なパスや、検出器が認識する "dummy" や "example" のような明示的マーカー。

秘密が見つかったら、コミットを失敗させて次にすべきことを示してください。Claude Code のフックは差分に基づく短い説明をフレンドリーに出すことができますが、重要なのは明確で安全な次手です：

ERROR: Possible secret detected in staged file: config/app.yaml (line 12)
Reason: looks like an API token
Next steps:
1) Remove it from the change or move it to env vars
2) Rotate the token (assume it is compromised)
3) Re-stage and retry commit
If this is a false positive, add a narrow allowlist rule in .secrets-allowlist

具体例：誰かがバックエンドの設定を更新し、開発環境で機能させるために TEMP_API_KEY を追加したとします。フックはコミットを止め、それを環境変数に移すことを提案し、もし実際のキーならローテーションするよう注意します。これは小さな中断ですが、後の大掛かりな掃除を防ぎます。

フォーマットを遅くせずに強制する

フォーマットの衝突はレビュワーの時間を浪費しますが、遅いフックはフック無効化の最大の理由です。スイートスポットは単純なルール、言語ごとに一つのツール、そしてステージされたものだけに触ることです。

言語ごとに一つのフォーマッタを選び、それを真実の源にしてください。二つのフォーマッタが食い違ったり、フォーマッタと自動修正するリンタが両方あるとノイズと終わりのない摩擦になります。つまらなく保ちましょう：1 つの JS/TS フォーマッタ、1 つの Go フォーマッタ、1 つの Dart フォーマッタ。全員が同じバージョンを使うようにして、フックの出力がマシン間で安定するようにしてください。

最大の速度改善はステージされたファイルのみをフォーマットすることです。コミットごとにリポジトリ全体を整形するのが pre-commit に対する最大の不満の原因です。ステージのみのアプローチは、差分をあなたが変更した箇所に集中させ、レビュワーが望む結果をもたらします。

クイックな選択肢のセット：

• ステージされたファイルのみでフォーマットを実行する
• 安全な変更（スペース、引用符、インポート順）は自動修正する
• 人の判断が必要な場合は早めに失敗させる
• フォーマッタが何も変えなければ出力を静かにする
• 可能ならキャッシュを使うが正確性を損なわないこと

自動修正と失敗のどちらにするかはチームの好みですが、混合アプローチがうまく働くことが多いです。機械的な編集は自動修正が良く、"コミット→失敗→再実行→コミット" のループを避けられます。人の判断が必要な場合は失敗させ、1 行で誰でも 10 秒でできる指示を出してください。

プラットフォーム間のノイズを引き起こす小さな事項を標準化してください。行末や末尾空白はよく問題になります。

簡単なポリシー：

• リポジトリは LF 行末を強制する
• 変更された行の末尾空白を削る
• ファイルは改行で終わることを保証する
• 生成物や vendor はフォーマット対象外にする

Claude Code のフックが手助けできるのは、どのステージされたファイルにどのフォーマッタが必要かを検出し、正しい順で実行して再ステージし、失敗を平易な言葉で説明するような "つなぎ" の部分です。例えば Go ファイルと TS ファイルの両方がステージされていれば、それぞれ適切なツールで整形して再ステージし、「2 ファイルが整形されました、動作変更なし」といった短い通知を出すことができます。レビュワーは差分がきれいになり、開発者は頻繁にコミットしても罰せられないと感じます。

変更に対して必要なテストを要求する

シンプルなルールでコミットを安全にしつつ辛くしない方法：実際にステージしたものにマッチするテストだけを実行すること。フックがステージ済み差分（作業ツリーではなく）を見れば、半端なファイルから来る誤報を避けられます。

変更された領域を検出することから始めましょう。多くのリポジトリは自然な構造を持っています：パッケージ、サービス、アプリ、モジュール。フックは git diff --cached --name-only を読み、それらのパスを少数のテストコマンドにマップできます。

わかりやすく保てるいくつかのマッピングルール：

• web/ または frontend/ -> npm test（または最小のターゲットコマンド）
• api/ または server/ -> バックエンドのユニットテスト（デフォルトで統合はスキップ）
• mobile/ -> 高速なウィジェット／ユニットテスト（フルデバイスは除く）
• db/ または migrations/ -> マイグレーションリントと小さなスキーマチェック
• shared/ -> 共有パッケージのテストと、速いコンシューマを追加

Claude Code のフックを使えば一歩進めて、ステージされたファイル名を見て最小限のテスト集合を提案し、そのコマンドを実行することもできます。ただし最終的な決定ルールは予測可能にするためにルールベースにしておくことを推奨します。

コミットとプッシュで仕事を分けてください。コミットは速く保つべきです。実用的なパターン：

• コミット時：速く選択的なセット（触ったモジュールのリンティング＋ユニットテスト）を実行
• プッシュ時：より広いセット（統合、E2E スモーク、クロスモジュールテスト）を実行
• CI：フルスイートを実行しカバレッジゲートを強制

フレークする遅いテストには明確な方針が必要です。さもないとフックがノイズになります。チームで合意したブロック基準と警告基準を決めてください。実用的な方法は、明確な失敗（通常安定しているユニットテストやフォーマット）でブロックし、既知のフレークテストは警告にして短いメッセージを出し、遅いスイートは push/CI に移すことです。フレークテストはバグと同様に扱い、追跡して修正し、安定したら警告モードを解除します。

コミット時に短いレビュアー要約を生成する

良い差分は必ずしも読みやすいとは限りません。短いコミット時要約によって、10 分の読み物が 2 分の確認に変わることがあります。特に複数ファイルに触れるリファクタや複雑な変更で有効です。

アイデアは単純です：git commit を実行するとき、フックが Claude Code にステージされた差分を読ませ、レビュワーが常に気にする問いに答える 3～6 行のメモを生成します：何が変わったか、なぜか、リスクはどの程度か、どうやってテストしたか。

シンプルな要約テンプレート

出力は短く一貫させ、レビュワーが信頼できるようにします：

• What: 主な変更点を一文で（ファイル一覧ではない）
• Why: ユーザ問題やバグの説明
• Risk: 低・中・高 と一行の理由
• Testing: 実行した内容（または “not run” と明記）
• Notes: マイグレーション、フラグ、ロールアウト手順などレビュに重要なもの

これを直接コミットメッセージに入れる（フッタとして）か、PR 説明にコピーするためのファイルに保存することができます。コミットメッセージはコンテキストが変更に伴って移動するので有用です。別ファイルはクリーンな慣習的コミットを好むチーム向けです。

要約で秘密を漏らさない

要約ツールはレビュワーよりも厳格にすべきです。モデルに差分を送る前に、API キー、秘密鍵、トークン、.env の値、認証情報に一致する行をフィルタリングしてください。リポジトリにキャプチャされた HTTP トラフィックがあるならヘッダやクッキーもフィルタリングします。機密パターンが検出されたら行を伏せ字にするか、"credentials-related changes redacted" のような汎用要約にフォールバックします。

例：請求エンドポイントを更新し 3 ファイルに触れたとします。ステージ差分はリネームでノイズが多いですが、要約はこう言います：「二重課金を防ぐため請求作成に冪等キー処理を追加。理由：リトライで重複課金が発生。リスク：中（支払い経路）。テスト：billing サービスのユニットテスト、手動リクエスト再生。」レビュワーが最初に必要とする情報だけが提供されます。

ワークフロー例：1 回のコミットで驚きを減らす

小さなバグ修正と設定の修正を同じコミットで行ったとします。バグは billing/tax.go の 1 行変更。設定は config/staging.yaml のエンドポイントを新しくする更新です。

git commit -am "Fix tax rounding" を実行すると、Claude Code の git フックがクイックなチェックを予測可能な順で実行します。

最初に秘密スキャンはリポジトリ全体ではなく変更箇所を見ます。ステージされた設定に実際の API キーらしきものが含まれているとフラグします。

ERROR: Possible secret detected in config/staging.yaml:12
Pattern: api_key=sk_live_...
Fix: remove the key and use an env var reference (e.g., API_KEY)
Override: set ALLOW_SECRETS=1 (not recommended)

値を環境変数参照に置き換えて再コミットします。

次にフォーマットは重要な箇所だけで走ります。Go ファイルが整形されていなければ "run gofmt on billing/tax.go" のような短いヒントで失敗します。フォーマッタを実行するとフックは数秒で通ります。

その後、テストゲートがターゲットに絞ったセットを実行します。billing/ に触れているので billing のユニットテストだけを走らせます（フルスイートではありません）。テストが失敗したらローカルで再現するコマンドを正確に示します。ラウンドのエッジケースを修正して同じテストを再実行します。

最後にフックは差分からレビュワー要約を生成します。短く具体的に：

• What changed: Fix rounding in tax calculation for values ending in .005
• Config: staging now reads API key from env var
• Tests: billing unit tests passed
• Risk: affects billing totals, but limited to tax rounding path

レビュワーが見るのは既に整理されたコミットです：秘密は漏れておらず、フォーマットは一貫し、変更に合ったテストが実行されています。準備された要約により、レビュワーは意図に集中できます。

よくあるミスと回避方法

フックを痛いものにすると、フックは失敗します。フックが開発者の流れを壊すほど時間がかかると、人は --no-verify やフック削除に走ります。重い処理は pre-commit に入れず、CI やオンデマンドで実行しましょう。

実用的なルール：pre-commit はタイプミスチェックのように感じられるべきであって、テストスイートではあってはいけません。Claude Code のスマートなチェックを使うなら、何を実行するかを決めるために使い、何でも実行するために使わないでください。

1) フックが遅すぎる

デフォルトで速く、必要なときだけ厳しくする。例：すべてのコミットでクイックフォーマット＋秘密スキャンを実行し、テストは影響を受けたモジュールだけに限定する。

実用的な速度予算：

• pre-commit: 合計 1～5 秒
• commit-msg: 1 秒未満
• それ以上は pre-push や CI に移す

2) 明確なルールなしの AI 出力

AI は提案には優れるがポリシーには弱い。"差分をレビューして" のような投げやりな指示だと毎回違う結果になります。フックに何をさせるか（何を絶対にしてはいけないか）を定義してください。例：レビュワー要約は生成して良いが、フォーマッタが決定的に出した変更以外でコードを書き換えてはいけない、など。

3) ステージ済みと未ステージ済みの混同

多くのフックは誤って作業ツリー全体をスキャンして、ステージしていない変更でコミットを失敗させます。それは不公平に感じます。

常にステージ済みコンテンツを入力として使うようにしてください。テスト方法は：ファイルを編集し、一部だけステージして、フックがステージされたものだけを報告するか確認することです。

4) 誤検出が多すぎる

常に警告が出ると警告は雑音になります。パターンを調整し、既知の安全文字列を allowlist に入れ、あいまいな発見は警告にダウングレードしてください。

具体例：シークレットスキャナが fixtures/ 内のテストキーをフラグするなら、そのフォルダを無視リストに追加してください。一方でアプリ設定ファイル内の本物のキーはブロックし続けます。

迅速なチェックリストと次のステップ

Claude Code の git フックを導入してチームを煩わせないための目標は単純です：本物の問題を早く捕まえ、何もないときは静かにして、コミットループを速く保つこと。

ほとんどのリポジトリで機能する実用的なチェックリスト：

• ほとんどの変更について pre-commit を数秒以内に保つ。遅くなると人はバイパスする。
• ステージされたファイルのみをスキャン、フォーマット、リン トする。他は pre-push や CI に移す。
• 明白な秘密（API キー、秘密鍵、トークン）はブロックする。"もしかして" のケースは警告して開発者に確認させる。
• コミット時に触ったモジュールに対してターゲットテストを要求し、広いテストは push/CI で実行する。
• レビュワーが何を見ればいいか分かる短く一貫したコミット要約を追加する。

役に立つ小さな工夫：レビュワー要約は毎回同じ見た目にしてください。単純なテンプレートで十分です。レビュワーは速く読み取ることを学びます。

Review summary:
- What changed: <1-2 bullets>
- Risky areas: <files/modules>
- Tests run: <command or “not run + why”>

導入を簡単にする次のステップ：

• まずサンドボックスプロジェクトでフローをプロトタイプし、うまく行ったら実際のリポジトリにコピーする
• 1 週間は "warn only" モードで始め、誤検出を測定して最も信頼できるチェックを "block" に切り替える
• 緊急用のエスケープハッチを追加する（例：コミットメッセージで明確な理由を付けてフックをスキップできる）と、その発生をログに残す
• 重い処理（フルテスト、深いシークレットスキャン、依存監査）は pre-push や CI に移し、コミットを速く保つ

チャット中心の方法でツールを作るのが好きなら、Koder.ai (koder.ai) はフック周りの小さなヘルパースクリプト生成やスナップショットとロールバックを使った安全なイテレーションに便利です。