最終更新 11月8日 18:55

ハーネス開発者向け|クロードのhooksで編集後の整形を必ず走らせる

開発基盤向け|クロードでhooksで編集後の整形を必ず走らせる

ソフトウェア開発部門|Claude Codeのhooksで編集後の自動整形を100%強制する最小設定手順

自律型AIコーディングエージェント「Claude Code (CLI)」を導入した開発現場において、極めて頻繁に発生するのが「エージェントがコードの自動整形を行わず、プルリクエスト(PR)のレビューがインデントや改行の差分ノイズで汚染される」というトラブルです。

多くのチームがプロジェクト用指示ファイル(CLAUDE.md)に「コード編集後は必ずPrettierを実行すること」と追記して解決を図ろうとします。しかし、指示ファイルにルールを記述するだけでは強制力を持たず、トークン消費量やコンテキストの混雑状況によって、モデルがフォーマット実行を勝手にスキップしてしまいます。その結果、コードレビューのたびに人間が手動でリント漏れを指摘し、再整形を依頼するという本末転倒な工数が発生します。

本稿では、ソフトウェア開発部門やテストハーネスを運用するエンジニアに向けて、公式のフック機構である「hooks(自動実行)」の PostToolUse イベントを活用し、コード編集後にフォーマッタを100%決定論的に強制実行する最小構成の設定手順を解説します。曖昧な自然言語指示から脱却し、システム的に差分ノイズを根絶する環境を確立します。

【3秒でわかる結論:コード整形の自動強制ルール】
・指示と強制の分離: CLAUDE.md は確率的推論(努力目標)。例外なく走らせる整形は hooks(決定論的強制)に切り離す。
・最小構成のイベント: 編集後フック PostToolUse を使い、matcher(絞り込み)を Edit|Write に限定する。
・禁止との混同を避ける: 危険コマンドの遮断は PreToolUse、編集後の整形は PostToolUse。同一フックに処理を詰め込まない。
・チーム共有の鉄則: プロジェクトルートの .claude/settings.json に配置し、Git管理下でレビュー対象にする。

【図解】プロンプトによる指示(確率的実行)とhooksによる自動実行(決定論的実行)の構造比較。整形処理はシステム側のフックへ逃がすのが鉄則
目次

指示ファイル(CLAUDE.md)に書くだけでは強制できない理由

開発現場で最も多い誤りは、指示ファイル(CLAUDE.md やシステムプロンプト)に「編集後は必ずフォーマッタを実行してください」と強く指示すれば、エージェントがそれを遵守すると過信してしまうことです。

公式ドキュメントでも明記されている通り、CLAUDE.md の役割はモデルに文脈や優先度を伝える「プロンプト(静的メモリ)」に過ぎません。LLMは本質的に確率モデルであるため、複雑なタスクや長大なコンテキストを処理している最中には、指示の一部を重要度が低いと判断して意図的に省略することがあります。

機能区分 実行の性質 役割と使い分けの基準 適したユースケース
指示ファイル(CLAUDE.md) 確率的(プロンプト推論) 文脈の提供・プロジェクト全体の設計方針 命名規則、ビルドコマンド、禁止アーキテクチャ
スキル(Skills / Tools) オンデマンド(モデル判断) 関連性が高いと判断された時にロード・実行 特定のAPI仕様確認、手動呼び出しスクリプト
フック機能(hooks) 決定論的(100%強制実行) 特定イベント発生時にOS/ランタイム側でフック ファイル編集後のPrettier実行、コミット前Lint

「毎回同じ方針を伝える」のは指示ファイル、「必要な時に呼び出す」のはスキル、「例外なく100%走らせる」のはフック(hooks)です。この役割分担を曖昧にしたままプロンプトの文言修正を繰り返しても、フォーマット漏れの根本的な根絶は不可能です。

整形を固定する最小構成:PostToolUseとmatcherの指定

コード編集後にフォーマッタ(Prettier等)を強制実行するための最小構成は、設定ファイル(settings.json)の hooks 配下に PostToolUse を定義することです。

ここで極めて重要なのが、matcher(絞り込み条件)を必ず Edit|Write に限定することです。matcherを空にしてしまうと、ファイルの閲覧(View)やディレクトリの走査(LS)、通常のBashコマンド実行など、あらゆるツール呼び出しのたびに無駄なフォーマッタが起動し、開発レスポンスが極端に悪化します。

プロジェクト用設定ファイル(.claude/settings.json)の記述例

リポジトリルートに .claude/settings.json を作成(または既存ファイルを編集)し、以下の設定を配置します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $FILE_PATH"
      }
    ]
  }
}

※環境変数 $FILE_PATH には、エージェントが実際に変更を加えたファイルの相対パスが渡されます。対象ファイルを直接指定してフォーマッタを実行することで、プロジェクト全体の不要な再走査を防ぎ、ミリ秒単位で処理を完了させることができます。

整形(PostToolUse)と禁止(PreToolUse)は別イベントで設計する

フック機能を導入する際、もうひとつの典型的なつまずきが「編集後のコード整形」と「危険なコマンドの禁止」を同一のフック内に混在させてしまう設計です。

Claude Codeのイベントライフサイクルにおいて、実行の「前」と「後」は完全に独立したフェーズとして定義されています。

【図解】Claude Codeにおけるツール実行ライフサイクル。実行前の拒否(PreToolUse)と実行後の整形(PostToolUse)を厳格に分離する
  • PreToolUse(ツール実行前ゲート): エージェントがコマンドを実行する直前にインターセプトする。危険な操作(例: rm -rf / や本番DBへの接続コマンド)を正規表現等で検知し、実行そのものを中止(拒否)させるために使用します。
  • PostToolUse(ツール実行後処理): ツールによる変更がディスクに書き込まれた直後に起動する。ファイル編集が成功したことをトリガーに、フォーマッタやテストランナーを走らせるために使用します。

これらをひとつのシェルスクリプトに詰め込むと、エラーハンドリングの切り分けが複雑化します。「危険な操作の遮断」と「編集後の整形」は、別々のチケット・別々のイベント定義として直交的に管理してください。

手元で差分を確認する最小導入の5ステップ

チーム全体の設定ファイルを書き換える前に、手元のローカル環境で確実に動作を検証するための5つの手順です。

【図解】PostToolUseフックの導入から差分目視確認、README記録までの5ステップ検証フロー
  1. フォーマッタと対象拡張子の確定: プロジェクトで使用しているフォーマッタ(Prettier, Biome, Black等)がローカルのシェルから直接実行できることを確認します。
  2. settings.json へのフック追記: リポジトリルートの .claude/settings.json に PostToolUse の設定を追記します(既存のキーを上書き消去しないよう注意)。
  3. セッション内コマンドで登録確認: Claude Code (CLI) を起動し、ターミナル内で /hooks を実行します。登録されているフックの一覧とコマンドが正しく表示されることを確認します。
  4. 最小ファイルでの受け入れ確認: 空のテスト用ファイルを作成し、エージェントに「1行だけ関数を追加して」と依頼します。編集直後にフォーマッタが走り、Gitの差分(git diff)に正しく整形されたコードだけが残っていることを目視で確認します。
  5. 運用の明文化とGitコミット: 動作確認が完了した設定ファイルをコミットし、リポジトリの README.md 等に発火条件(PostToolUse / Edit|Write)を1行記録します。

設定の置き場とレビュー観点:プロジェクト共有と個人設定の分離

Claude Codeの設定ファイルには、二重のスコープが存在します。

設定ファイルのパス スコープ 管理方法 推奨される格納項目
~/.claude/settings.json ユーザー(個人)設定 個人ローカル管理(Git対象外) OS通知(Notification)、個人のシェル環境依存の設定
.claude/settings.json プロジェクト共有設定 リポジトリでGit管理(チーム共通) チーム共通のPostToolUse(Prettier等)、ビルドフック

コードレビュー時の3大チェックポイント

プロジェクトの settings.json を更新するプルリクエストでは、レビュアーは以下の3点を確認してください。

  1. 既存イベントの破壊がないか: 他の開発者が定義したフックや設定を、JSONの全上書きによって誤って消去していないか。
  2. matcher が適切に絞り込まれているか: 空欄やワイルドカードになっておらず、Edit|Write に閉じているか。
  3. コマンドが他メンバーの環境で動作するか: 特定個人のマシンにしかない絶対パス(例: /Users/username/...)がハードコードされていないか。必ず npx やプロジェクトの仮想環境経由で呼び出されているか。

現場でよくあるつまずきと切り分け手順

フックが意図通りに動かない場合は、再インストールを疑う前に、以下の優先順位で原因を切り分けてください。

  1. コマンドがPATHに存在しない: ターミナルから直接 npx prettier --version 等を叩き、実行可能か確認する。パスが通っていない場合は、絶対パスではなくプロジェクトローカルのバイナリ参照(npx 経由等)へ修正する。
  2. matcher の文字列ミス: Edit|Write のスペルミスや、前後に余計な半角スペースが入っていないか確認する。
  3. /hooks コマンドでの反映確認: 設定ファイルを編集したにもかかわらず /hooks に反映されていない場合、セッションを再起動(または claude -r で再接続)する。
  4. 二重実行の発生: ユーザー設定(~/.claude/settings.json)とプロジェクト設定(.claude/settings.json)の両方に同じ PostToolUse を書いていないか確認する。設定が重複していると、1回のファイル変更に対してフォーマッタが2回起動します。
  5. OS依存のシェルの差異(Windows): Windows環境でPowerShellを標準にしている場合、シングルクォートや環境変数の展開記法($FILE_PATH)が異なる場合があります。クロスプラットフォームで運用する場合は、npm scripts(npm run format -- $FILE_PATH)などを介して実行するのが最も安全です。

よくある質問(FAQ)

Q1. デスクトップ版のClaudeでも同じhooks設定が反映されますか?

A1. 反映されます。
Claude DesktopとClaude Code (CLI) は共通の settings.json およびフック構成を参照します。ただし、対話の履歴(セッションログ)は環境ごとに分離されます。

Q2. ターミナル内の /hooks コマンドから直接設定を追加・変更できますか?

A2. 直接の追加・変更はできません。
/hooks コマンドは、現在アクティブになっているフックの件数やコマンド内容を閲覧するための「参照専用メニュー」です。追加・編集・削除を行う際は、直接 settings.json を編集するか、エージェントに対して「settings.jsonのhooksにPostToolUseを追加して」と依頼してください。

Q3. スキル(Skills)だけでもコード整形は代用できませんか?

A3. 代用は推奨されません。
スキルはモデルが必要性を判断したときにのみ呼び出されるオンデマンドの機構です。編集のたびに「100%例外なく走らせる」という強制力を持たせるには、ランタイムが直接割り込む hooks を使用する必要があります。

Q4. hooksの導入によって作業効率は何倍になりますか?

A4. 倍率のような抽象的な数値で評価するものではありません。
現場で測定すべき指標は、「PRレビュー時に発生するフォーマット指摘の件数」です。フックを導入することで、フォーマットに関する指摘と修正往復のチケットは実質的にゼロになります。手元の git diff に余計な差分が残らない状態そのものが客観的な導入成果です。

Q5. 危険なコマンドの禁止も PostToolUse にまとめて書いてよいですか?

A5. まとめてはいけません。必ず PreToolUse に分離してください。
PostToolUse はコマンドが実行された「後」に発火するため、破壊的コマンドの実行を未然に阻止することはできません。操作の拒否やバリデーションは、必ず実行前に発火する PreToolUse に記述してください。

導入初週(1週間)の定着ロードマップ

開発チーム内でhooks運用を破綻なく定着させるための5日間のステップです。

  • Day 1: フォーマッタ選定と単体実行の確認

    チームで統一するフォーマッタ(Prettier等)を確定し、ローカルターミナルで正常にファイル整形が実行できることを確認する。
  • Day 2: ローカル最小構成の記述と /hooks 確認

    .claude/settings.json に PostToolUse(matcher: Edit|Write)を1件だけ追加。/hooks を実行して登録内容を目視確認する。
  • Day 3: 空ファイルを用いた受け入れ確認

    新規のテストファイルに対してエージェントにコード生成を依頼。編集直後に自動整形が走り、Git差分が正しく保たれているか検証する。
  • Day 4: リポジトリへのコミットとREADME更新

    設定ファイルをリポジトリへコミット。README.md の開発者向けガイドに「Claude Code利用時はPostToolUseによりPrettierが自動起動する」旨を1行追記する。
  • Day 5: チームレビューとPreToolUse(禁止設定)の検討

    チームメンバーに設定をプルしてもらい、環境差異によるエラーが出ないか確認。整形が安定した段階で、必要に応じて危険コマンドを遮断する PreToolUse の設計へ進む。

まとめ

コード編集後の自動整形を現場に定着させる唯一の解は、確率的にしか動かない CLAUDE.md への記述をやめ、ランタイムが確実に割り込む公式の hooks(PostToolUse)を採用することです。

matcherを Edit|Write に閉じ、危険な操作の禁止(PreToolUse)とはイベントを明確に分離する。そして、チーム全体の設定は .claude/settings.json に集約してGit管理する。この最小構成を守るだけで、フォーマット差分によるレビューの消耗は完全に過去のものとなります。

まずは今日、リポジトリの .claude/settings.json を開き、PostToolUse のフックを1行定義することから始めてください。

参考文献

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

コメント

コメントする

目次