メインコンテンツへスキップ
見出し画像

Claude CodeのHooksで作業の前後に処理を挟む方法

    イチロー

    Hooksが役に立つ場面

    Claude Codeにコードを書かせていて、「Prettierをかけ忘れたままコミットされていた」という経験はないでしょうか。個人の技術ブログでは、LLMがコードを書く場合はフォーマットを実行するかどうかをLLMが判断するため、フォーマットされないままコミットされることが多いと指摘されています [S4]。

    Hooksを使うと、この「実行するかどうか」をLLMに任せずに済みます。HooksはClaude Codeのライフサイクルの決まった時点で実行される仕組みで、LLMの判断ではなく、特定の処理が常に実行されます [S1]。

    Hooks are user-defined shell commands. Claude Code runs them at specific points in its lifecycle, which gives you deterministic control: certain actions always happen rather than relying on the LLM to choose to run them.

    この記事では、公式ドキュメントの内容を中心に、設定場所の選び方、作業の「後」と「前」に処理を挟む例、対象の絞り込み方、つまずきやすい点を整理します。

    仕組みの要点

    最初に押さえておきたい点は次の3つです。

    • hookを作るには、設定ファイルに hooks ブロックを追加します [S1]。

    • イベントが発生すると、Claude Codeはイベントごとのデータを、JSONとしてスクリプトのstdinに渡します [S1]。

    • Claude Codeは、ターミナル、IDE拡張、Desktopアプリ、クラウドセッションのどこで動いていても、同じhookイベントを発生させます [S2]。

    つまり「設定ファイルに書く」「stdinのJSONを読んで処理する」という流れです。

    どこに書くか：設定場所の比較

    hookをどこに定義するかで、適用範囲が変わります [S2]。

    設定ファイル 適用範囲 共有 出典 ~/.claude/settings.json すべてのプロジェクト しない（マシン内だけで使う） [S2] .claude/settings.json 単一プロジェクト リポジトリにコミットできる [S2]

    選び方の目安は次のとおりです。

    • 自分だけが全プロジェクトで使いたい処理なら ~/.claude/settings.json が向いていると考えられます。

    • チームで同じ整形・チェックをそろえたいなら .claude/settings.json です。コミットすると、リポジトリをクローンした全員が同じ権限・hooks・プラグインを使えます [S3]。

    補足として、hookの設定は設定レベル間で置き換えられずに合算されます [S2]。ユーザー・プロジェクト・ローカルの設定は、管理設定のhookを消さずに自分のhookを追加します [S2]。一方、hooks以外の同じキーが複数の場所で設定されている場合は、最も上位のレベルの値が使われます [S3]。

    なお、Claude Codeをインストールしても設定ファイルは作成されません [S3]。ファイルがなければ自分で作る必要があります。Windowsでは、~/.claude は %USERPROFILE%.claude を指します [S3]。

    設定と確認の手順

    1. 適用範囲を決めて、上の表から設定ファイルを選ぶ（なければ作成する）[S3]。

    2. 設定ファイルに hooks ブロックを追加する [S1]。個人ブログでは、/hooks コマンドから設定する方法と、.claude/settings.json を直接編集する方法の両方が紹介されています [S4]。

    3. Claude Codeのプロンプトで /hooks と入力し、hooksブラウザで設定を確認する [S1]。

    4. /status を実行し、どの設定ソースが有効になっているかを確認する [S3]。

    Claude Codeは設定ファイルを監視しており、hooksの変更も含め、ほとんどの編集を再起動なしで実行中のセッションに反映します [S3]。

    例1：編集の「後」に自動整形する

    公式ドキュメントの整形の例では、PostToolUse イベントと Edit|Write のmatcherを使うため、ファイルを編集するツールの後にだけ実行されます [S1]。コマンドは、jqで編集されたファイルのパスを取り出し、Prettierに渡します [S1]。

    個人ブログの例も考え方は同じです。stdinで受け取ったJSONから tool_input.file_path を取り出し、JavaScriptやTypeScriptのファイルパスであれば prettier --write を実行しています [S4]。また、xargs -r は引数がない場合にコマンドを実行しないためのオプションとして使われています [S4]。

    情報源の間で違いがある点は次の2つです。

    項目 公式ドキュメント 個人ブログ 出典 matcher Edit|Write Write|Edit|MultiEdit [S1][S4] 成功時の表示 会話に何も表示しない 結果が折りたたまれて表示され、ctrl + r で展開できる [S1][S4]

    成功時の表示については、公式ドキュメントの記述を基準にしてください。表示が違うのは、記事が書かれた時期のバージョン差による可能性がありますが、確認できませんでした。

    例2：編集の「前」にブロックする

    公式ドキュメントには、保護ファイルの編集をブロックする例もあります。スクリプトが対象のファイルパスを保護パターンの一覧と照らし合わせ、終了コード2で終了して編集をブロックします [S1]。macOSとLinuxでは、スクリプトに実行権限（chmod +x）が必要です [S1]。

    終了コードの扱いで注意したいのは次の点です。

    • 終了コード2：編集をブロックする [S1]。

    • 終了コード0：PreToolUse hookが0で終わっても、ツールの呼び出しは承認されず、通常の権限確認の流れに進みます [S1]。

    「0で終われば許可される」わけではないので、許可を自動化する目的には使えないと考えられます。

    対象を絞り込む：matcher と if

    方法 動き 出典 matcherなし そのイベントが発生するたびに毎回実行される [S1] matcher（正規表現） Edit.* はEditとNotebookEditの両方に一致する。完全一致させたい場合は ^Edit$ のように書く [S2] if（権限ルールの書式） ツール名と引数をまとめて照合する。"Edit(*.ts)" はTypeScriptファイルの場合にだけ実行される [S2]

    注意点が2つあります。matcherに対応していないイベントにmatcherを書いても、エラーにならずに無視されます [S2]。また、if によるフィルタはベストエフォートなので、許可・拒否を厳密に強制したい場合はhookではなく権限システムを使うよう公式ドキュメントは案内しています [S2]。

    同じイベントに複数のhookが一致した場合は、すべてのhookのコマンドが最後まで実行されてから、Claude Codeが結果をまとめます [S1]。

    Windowsで使うときの注意点

    • argsを指定しない形式（shell form）では、コマンド文字列がシェルに渡されます。WindowsではGit Bash、Git Bashが入っていなければPowerShellが使われます [S2]。

    • command hookに "shell": "powershell" を設定すると、そのhookをPowerShellで実行できます [S2]。

    • npm、npx、eslintなどが node_modules/.bin に置く .cmd と .bat のシムは実行ファイルではないため、シェルを通さないと起動できません [S2]。

    jqを使う例は、実行環境にjqが入っていることが前提になると考えられます。

    よくある失敗

    • JSONの書き方の誤り：設定ファイルは厳密なJSONで、// コメントや末尾のカンマは構文エラーになり、次回の起動時に Settings Error として報告されます [S3]。

    • イベント名の誤り：不明なhookイベント名など一部の項目だけが不正な場合は Settings Warning となり、その値はスキップされ、ファイルの残りは有効なままです [S3]。「設定したのに動かない」ときは警告を確認してください。

    • matcherの広すぎ・狭すぎ：Edit.* のような書き方は意図しないツールにも一致します [S2]。

    • timeoutを考えない：timeoutの既定値は、command・http・mcp_toolが600秒、promptが30秒、agentが60秒です [S2]。重い処理をhookに入れる場合は、この値を意識しておくとよいと考えられます。

    安全面の確認

    個人ブログでは、hooksのコマンドはユーザーの確認なしに実行されるため、予期しないコマンドが実行される可能性があると注意しています [S4]。そのため、hookに書くコマンドは追加する前に内容を確認しておくのが安全と考えられます。チームで .claude/settings.json を共有する場合は、hooksの変更もレビュー対象にしておくと安全と考えられます。

    次に取る行動

    1. まず自分のプロジェクトの .claude/settings.json に、PostToolUse ＋ Edit|Write の整形hookを1つだけ追加する [S1]。

    2. /hooks と /status で、設定が読み込まれているか確認する [S1][S3]。

    3. 動作を確認したら、保護ファイルのブロックなど PreToolUse 側のhookを追加する [S1]。

    4. 厳密な許可・拒否が必要なルールは、hookではなく権限システムで設定する [S2]。

    参考情報

    • [S1] Automate actions with hooks（Anthropic（Claude Code Docs）、公開日: 確認できず、取得日: 2026-11-03） https://code.claude.com/docs/en/hooks-guide

    • [S2] Hooks reference（Anthropic（Claude Code Docs）、公開日: 確認できず、取得日: 2026-11-03） https://code.claude.com/docs/en/hooks

    • [S3] Settings files and precedence（Anthropic（Claude Code Docs）、公開日: 確認できず、取得日: 2026-11-03） https://code.claude.com/docs/en/settings

    • [S4] Claude Code の hooks でフォーマッターを実行する（azukiazusa.dev（個人の技術ブログ）、公開日: 確認できず、取得日: 2026-11-03） https://azukiazusa.dev/blog/claude-code-hooks-run-formatter

     
     

    イチロー

     
     
    Claude CodeやClaudeの「これどうするの？」を、公式ドキュメントなどの一次情報をもとに整理しています。設定・機能・使い分けのほか、自動化や個人開発、スマートホームのAPI、note・ブログ運営の基本も。記事はすべて無料、参考にした情報源は記事内に載せています。

    あなたへのおすすめ