Claude Code hooksの使い方と実録【2026年】

Claude Code hooksは、セッション開始時や応答の終了時など決まったタイミングで、指定したスクリプトを必ず動かす仕組みです。僕の会社では「AIが忘れると困ること」をフックに任せ、2026年10月1日には週次枠95%を検知したフックが12セッションに引き継ぎメモを指示しました。設定方法と注意点までまとめます。

Claude Code hooksとは？何ができるのか

Claude Code hooksとは、Claude Codeの動作の決まった時点で、自分で用意したシェルコマンドを自動で実行させる仕組みです。公式ドキュメントは、AIが実行するかどうかを選ぶのではなく「必ず起きる」ようにできる点を、フックの価値として挙げています。ルールの強制、繰り返し作業の自動化、外部ツールとの連携に使います。

Claude Codeとは、ファイルの読み書きやコマンド実行まで含めて、Claudeに作業そのものを任せるツールです。チャットと違って作業の途中経過がたくさんあるので、「ファイルを書き換えた直後」「ツールを使い終わった直後」「応答を終えようとした瞬間」といった節目が生まれます。この節目にスクリプトを差し込めるのがフックです。

公式ガイドが挙げている使い方は、編集したファイルの自動整形、危険なコマンドの実行前ブロック、入力待ちになったときのデスクトップ通知、セッション開始時の情報の差し込みなどです。2026年10月時点の公式リファレンスには、SessionStartからSessionEndまで30を超えるイベントが並んでいます。

フックの種類は、シェルコマンドを動かす command が基本です。ほかに、指定したURLへイベントの内容を送る http、MCPサーバーのツールを呼ぶ mcp_tool、Claudeのモデルに判断させる prompt と agent があります。MCPそのものについてはMCPとは何かをまとめた記事で書いています。

ここで押さえておきたいのは、フックがAIの「外側」で動くことです。CLAUDE.mdやスキルに書いた指示は、AIが読んで、守るかどうかをその場で判断します。フックはAIの判断を通らずにスクリプトが動きます。だから「忘れたら困ること」「毎回必ず確認したいこと」はフックに向いています。スキルとの使い分けはClaude Codeのスキル解説も参考にしてください。

フックはどこに書く？設定の基本と主なイベント

フックは設定ファイルの hooks という項目に、「どのイベントで」「どのツールのときに」「何を動かすか」をJSONで書きます。全プロジェクト共通なら ~/.claude/settings.json、そのプロジェクトだけなら .claude/settings.json です。設定内容は /hooks で一覧できます。

僕の環境で、ツールを使い終わるたびにスクリプトを動かす設定は次の形です（パスは一部省略しています）。

"PostToolUse": [
  { "hooks": [
      { "type": "command",
        "command": "python3 ~/.claude/hooks/handoff-guard.py hook",
        "timeout": 10 } ] }
]

matcher とは、フックを動かす対象のツール名を絞り込む条件です。"Edit|Write" と書けばファイル編集のときだけ動き、省略すればすべてのツールで動きます。上の例は省略しているので、全ツールの使用後に毎回動きます。

よく使うイベントの早見表

スクリプトの返し方は2通り

フックのスクリプトは、終了コードかJSONで結果を返します。終了コード0は成功で、2は「止める」です（止められるイベントの場合です。ツール実行後のPostToolUseなどは、もう実行済みなので2を返しても止まりません）。公式ドキュメントでは、それ以外の0以外のコードは、ほとんどのイベントで「止めないエラー」として扱われ、処理はそのまま進みます。うっかり exit 1 で止めたつもりになるのは、よくある失敗です。

JSONで返す場合は、イベントごとに使える項目が決まっています。additionalContext とは、フックからClaudeの文脈に文章を差し込むための項目で、セッション開始時やツール実行後に「次はこれを確認して」と伝えるのに使います。PreToolUseでは permissionDecision に allow・deny・ask・defer のいずれかを返して、ツールの実行可否を決められます。

Stop hookとは、Claudeが応答を終えようとしたときに動き、"decision": "block" を返すと終了を取り消して作業を続けさせられるフックです。reason は必須で、ここに書いた文章が「なぜ続けるのか」としてClaudeに渡ります。引き継ぎメモを書かせる仕組みは、この性質を使っています。

なぜ非エンジニアの会社がフックを使うのか？

理由は、指示で書いたルールは長い作業の途中で抜けるからです。僕の会社は社内ルールをCLAUDE.mdやノートにまとめてClaude Codeに読ませていますが、1セッションが数百ターンに伸びると、最初に読んだルールより目の前の作業が優先されます。抜けると困る確認だけをフックに移すと、AIの注意力に頼らずに済みます。UserPromptSubmitで毎回「日本語で返す」と念押しする使い方は、Claude Codeが英語で返してくる時の直し方に書きました。

僕の会社はマーケティング支援の会社で、エンジニアはいません。広告運用、LP制作、SNS運用、経理の下準備をClaude Codeに毎日任せています。日々の使い方はClaude Codeの業務活用事例にまとめました。

フックを入れ始めたきっかけは、ルールを足すほど守られなくなったことです。料金の記事で書いたとおり、僕の会社ではMax 20xでも週の半ばで週次枠の6〜7割を使っていました。対策のルールはCLAUDE.mdに書いていましたが、書いただけでは守られないものがありました。

指示とフックの向き不向きは、次のように分けています。

2026年10月1日時点で、僕のユーザー設定に登録しているフックは8件です。SessionStartに2件、UserPromptSubmitに1件、PreToolUseに1件、PostToolUseに2件、PostToolUseFailureに1件、Stopに1件で、動かしているスクリプトは6本です（Web取得の成功時と失敗時、StopとPostToolUseは、それぞれ同じスクリプトを使い回しています）。どれも中身はPythonかシェルの短いスクリプトで、Claude Code自身に書かせ、僕は「何を検知して、何をさせたいか」だけを決めました。

実録1：週次枠95%でStop hookが引き継ぎメモを書かせた

週次枠が尽きる前に、作業中のセッションへ引き継ぎメモを書かせるフックを作りました。使用量が95%を超えると、Stop hookが応答の終了を1回だけ取り消し、「区切って引き継ぎメモを書いて」と指示します。2026年10月1日にこれが初めて本番で発動し、12セッションが約5分でメモを書くか、不要と返しました。

引き継ぎメモ（社内では「HANDOFF」と呼んでいます）とは、作業の目的、終わったこと、次の一手、触っているファイルを書いた短いメモです。週次枠が尽きると、セッションは返事も書き込みもできなくなります。枠が戻ったあとや別のセッションに引き継ぐときに、新しいセッションがこのメモだけで続きから再開できるようにするのが目的です。

発動したときの記録

フックのログに残っていた時刻をそのまま並べます（2026年10月1日、日本時間）。

止められたのは、実はこの記事の下書きを頼んでいたセッションでした。作業の途中で「週次枠が95%に達しました。今の作業を区切って、引き継ぎメモを書いてから終えてください」と割り込まれ、メモを書いたうえで12セッションへ連絡を配りました。人が12個の画面を回って声をかける作業が、5分ほどで終わったことになります。

作りの要点

Stop hookのスクリプトが返しているのは、次のJSONだけです。

{ "decision": "block",
  "reason": "週次枠が95%に達しました。今の作業を区切って、引き継ぎメモを書いてから終えてください。（書き先と中身の指定が続く）" }

そのうえで、止めすぎないための条件を4つ入れています。1つ目は、1セッションにつき1回しか止めないことです。止めたセッションには目印のファイルを残し、2回目からは素通りさせます。2つ目は、95%を超えた後に始まったセッションを対象外にすることです。引き継ぎ先として新しく開いたセッションまで止めないためで、会話記録ファイルの作成時刻で判定しています。

3つ目は、サブエージェントの中では動かさないことです。公式の入力項目には、サブエージェント内で呼ばれたときだけ agent_id が入るので、それを見て抜けます。4つ目は、無人で動く定期タスクのセッションも対象外にすることです。誰も見ていない画面で引き継ぎメモを書かせても、読む人がいないからです。

一斉連絡は、最初に止められたセッションが担当します。担当の取り合いにならないよう、先に担当の印を書き込んだセッションだけが連絡を配る作りです。連絡を受けたセッションは、次に応答を終えるときにStop hookが「もう対応済み」と判断して素通りさせます。

実録2：使用量を測らせ、取りこぼした定期作業を知らせる

フックは「止める」だけでなく、「頼む」「知らせる」にも使えます。僕の会社では、ツールを使った後のフックで使用量の計測をセッションに頼み、セッション開始時のフックで取りこぼした定期作業を知らせています。どちらも、人が覚えておく必要のある確認を仕組みに移したものです。

使用量の%を、セッション自身に測らせる

95%のガードには、今の使用量が何%かという数字が要ります。ところが僕の環境で確かめた範囲では、フックに渡される入力には使用量の%が入っていません。デスクトップアプリでは、ステータスラインから値を書き出す方法も使えませんでした。ターミナルで使う場合の表示の手順は、Claude Codeの使用量をステータスラインに常時表示する方法に書いています。

そこで、ツール実行後に動くPostToolUseのフックが、「作業の区切りで公式の使用量確認ツールを1回呼んで、結果を記録して」と additionalContext でセッションに頼む形にしました。間隔は、使用量が85%未満なら60分ごと、85%以上なら15分ごとです。全セッションで共有の記録を1つだけ持ち、誰かが測ったら他のセッションには頼みません。

2026年9月29日20時台の初回計測は76%でした。そこから10月1日11時55分までの約40時間で、フックが計測を頼んだ回数はログ上で30回です。計測の結果、10月1日11時55分時点で週次枠は96%、Fableモデルの枠は9月29日の初回計測の時点からすでに100%でした。

取りこぼした定期作業を、セッション開始時に1行で知らせる

僕の会社では、週次の経理チェックやNEWSのネタ出しを定期タスクとしてClaude Codeに任せています。ただ定期タスクはアプリが起動していないと動きません。2026年9月の見直しでは、5本の定期タスクのうち定刻に最後まで終わったのは8月24日の2本だけで、その後2週間はゼロでした。

そこでSessionStartのフックで、締切を過ぎたのに成果物が無い定期作業を検知し、セッションの冒頭に差し込むことにしました。判定は「実行済みの印」ではなく、成果物のファイルが実在するかで行います。実行済みの印だけが更新され、成果物がゼロだった事故が実際にあったからです。

差し込む文章には、扱い方も書いています。冒頭で1行だけ知らせる、勝手に実行しない、断られたら同じセッションで蒸し返さない、の3つです。別の作業のために開いたセッションを、定期作業に乗っ取らせないための決まりです。無人で動かす仕組みについてはヘッドレスモード（claude -p）の記事で詳しく書いています。

Web取得の失敗を見逃させない

もう1本、Webページの取得ツールが失敗したり、ほぼ空の結果を返したりしたときに、別の取得手段を順に試すよう促すフックもあります。取得失敗時と、結果が150文字未満のとき、「Just a moment」のようなボット確認画面の文言が含まれるときに、1行の注意を差し込みます。止めはしないので、誤検知しても注意が1行増えるだけです。注意を受けたあとに取得手段をどう上げていくかは、Claude CodeでURLが読めない時の対処にまとめました。

フックを作るときの注意点は？無限ループ・止めすぎ・誤検知

注意点は3つです。Stop hookが止め続けて終わらなくなる無限ループ、条件の誤りで必要な作業まで止める止めすぎ、そして判定のゆるさによる誤検知です。僕の会社では、このうち止めすぎを実際にやってしまい、自動ブロックを停止しました。どれも、スクリプト側の判定で防ぐのが基本です。

無限ループ：stop_hook_activeを必ず見る

Stop hookは、条件を満たす限り何度でも終了を取り消せます。条件が「ファイルが存在すること」のように満たされないままだと、Claudeは延々と作業を続けます。公式の仕様では、Stop hookが連続8回止めると、Claude Codeが次の取り消しを無視してターンを終わらせます。それでも8回分の使用量は消えます。

stop_hook_active とは、今の応答がすでにStop hookによって続けられたものかどうかを示す入力項目です。公式ドキュメントは、これが true なら止めずに抜けるよう勧めています。僕の引き継ぎメモのフックも、冒頭でこの値を見て、true なら何もしません。加えて、1セッション1回の目印ファイルで二重に防いでいます。

止めすぎ：自前の数字で止めると誤爆する

2026年9月16日に、使用量が増えすぎたら重い処理を止めるフックを入れました。ツール実行前のPreToolUseで、一括処理や上位モデルへの委譲を deny で止める作りです。判定には、会話記録から自前で集計した使用量を使っていました。

ところが3日後の9月19日、この自前の集計では予算の116%と判定されて「厳格モード」に入っていたのに、公式の使用量は全モデルで47%でした。枠を半分以上残したまま重い作業を止め、毎回の応答に警告まで出していたことになります。後の検証では、自前の集計は同じ期間の実際の額より約2.6倍多く出ていました。

この件以来、自動ブロックは止めています。フックの配線と集計は残してあり、スクリプト側のスイッチで戻せる状態です。95%の引き継ぎガードで公式の使用量確認ツールの値だけを使うことにしたのは、この失敗があったからです。止めるフックの判定材料には、公式の値か、確実に検証できる値だけを使ってください。

失敗を仕組みに変える考え方は、AI導入の失敗事例7つにも書きました。

誤検知と、気づきにくい不具合

誤検知は、止めないフックなら被害が小さく済みます。Web取得のフックは「150文字未満なら疑う」というゆるい判定ですが、注意を1行足すだけなので問題になっていません。止める・書き換えるフックほど、判定は厳しく、条件は狭くします。

公式ドキュメントのトラブルシューティングには、気づきにくい不具合も載っています。シェルの設定ファイルに無条件の echo があると、その出力がJSONの前に混ざり、JSONとして読まれなくなります。終了コード0だと画面には何も出ず、記録はデバッグログにしか残りません。「設定したのに効かない」ときは、まずここを疑うのが近道です。

ほかにも公式が明記している注意点を4つ挙げます。コマンド型のフックは自分のユーザー権限でそのまま動くので、そのユーザーが触れるファイルはすべて変更も削除もできます。入れる前に中身を読み、単体で試すのはこのためです。PostToolUseはツールの実行後に動くため、実行された操作を取り消すことはできません。Stop hookはタスクの完了時だけでなく応答を終えるたびに動き、逆にユーザーが中断したときには動きません。そして同じイベントに合うフックは並列で動くので、同じツールの引数を書き換えるフックを複数置くと、最後に終わったものが効き、どれになるかは決まりません。

どこから始めればいい？最初の1本の選び方

最初の1本は、止めないフックから始めるのが安全です。入力待ちになったときの通知や、セッション開始時に今日の予定や取りこぼしを知らせるフックなら、判定を間違えても作業は止まりません。慣れてから、ツール実行前のブロックや、Stop hookのような止めるフックに進みます。

僕のおすすめの順番は次のとおりです。

作り方は、Claude Codeに頼むのがいちばん早いです。「応答を終えるたびに、〇〇なら△△させるStop hookを作って。1セッション1回だけで、stop_hook_activeがtrueなら何もしないこと」のように、イベント名と止める条件まで言葉で伝えます。できたスクリプトは、サンプルのJSONを流し込んで単体で試してから設定に入れてください。

フックを一時的に全部止めたいときは、設定に "disableAllHooks": true を書きます。公式ドキュメントによると、個別の1本だけを無効にする設定はありません。僕は止める可能性があるフックには、スクリプト側にスイッチを持たせています。

Claude Codeの基本的な使い方がまだの方は、Claude Codeの使い方ガイドから読むのがおすすめです。使用量の枠の仕組みはClaude Codeの料金と上限の実録で詳しく書いています。フックを含めた社内の仕組みづくりの支援もしているので、気になる方はウラカタのサービス一覧をご覧ください。

まとめ

• Claude Code hooksは、決まったタイミングでスクリプトを必ず動かす仕組みです。CLAUDE.mdの指示と違い、AIの判断を通らずに実行されます
• 設定は settings.json の hooks に書きます。止めるときは終了コード2か "decision": "block"、情報を渡すときは additionalContext を使います
• 僕の会社では、週次枠95%でStop hookがセッションを止め、2026年10月1日に12セッションへ引き継ぎメモを書くよう指示しました
• Stop hookは stop_hook_active を見て、1回だけ止める作りにします。公式の上限は連続8回です
• 止めるフックの判定には、公式の値か検証済みの値だけを使います。自前の集計で止めて、枠が半分以上残っているのに作業を止めた失敗がありました