3行まとめ
- 1PreToolUse
危険なtool callを実行前に止めます。
- 2PostToolUse
実行後にformat、lint、対象テストなどの軽量検査を返します。
- 3Stop
最終応答にレビュー材料が揃っているか確認します。
HooksはCIや人間レビューの代替ではなく、レビュー漏れを減らす補助線です。
Claude Code Hooksは、AIに「忘れずに確認して」と頼む代わりに、実行前、実行後、完了前へ置けるレビューゲートです。
PreToolUseは危険なtool callを実行前に止める層、PostToolUseは実行後の軽量検査を返す層、Stopは最終応答にレビュー材料が足りないときに差し戻す層として分けると、チーム導入時の責任範囲が見えやすくなります。
ただしHooksはpermissions、managed settings、人間レビュー、CIの代替ではありません。2026年6月8日にClaude Code公式Docsを確認し、手元では claude --version が 2.1.138、node --version が v25.9.0 であることだけを確認しています。
この記事でわかること
PreToolUse、PostToolUse、Stopの責務を分けます。
deny/askとHookの役割を混ぜずに設計します。
Managed、Project、Localなどのスコープを分けます。
通常のBashやEditと同じようにレビュー対象へ入れます。
実務で事故になりやすい操作、検査、完了報告をどこで扱うかが中心です。
この記事では、Claude Code Hooksをチームで使う前に決めるべき設計を扱います。Hookのイベント名をすべて覚える記事ではありません。実務で事故になりやすい「実行してからでは遅い操作」「編集後に見落としやすい検査」「完了報告に足りないレビュー材料」を、どのHookに任せるかを整理します。
具体的には、次の判断ができる状態を目指します。
- PreToolUse、PostToolUse、Stopの責務を分けられる
permissionsのdeny/askとHookを混ぜずに設計できる.claude/settings.json、.claude/settings.local.json、managed settingsの置き場所を分けられる- MCP toolやsubagent呼び出しを、通常のBashやEditと同じようにレビュー対象として見られる
- 最小構成のHookを入れる前に、失敗条件と無効化されやすい条件を説明できる
Xの直近検索ではCodexとClaude Codeの比較、AIコーディングのharness engineering、Hooks活用への関心が見えました。ただし追跡アカウント単体の直近投稿は公開検索で十分に確認できず、Xページ取得もエラーだったため、この記事ではXを事実根拠にしていません。技術的な説明はClaude Code公式Docs、公式permissions/settings/security/MCP/subagentsの記述を軸にしています。
前提知識
すべてのHookイベントを最初から使うより、責務が明確な3つから始めると設計しやすくなります。
Claude Code Hooksは、Claude Codeのライフサイクル上の特定地点で動くユーザー定義の処理です。公式Docsでは、shell command、HTTP endpoint、LLM promptなどをHook handlerとして実行できると説明されています。イベントには PreToolUse、PostToolUse、Stop、UserPromptSubmit、Notification、SubagentStart、SubagentStop などがあります。
チーム導入でまず見るべきなのは、すべてのHookイベントではなく、次の3つです。
| Hook | タイミング | 任せやすい役割 | 任せにくい役割 |
|---|---|---|---|
PreToolUse | tool callの実行前 | 危険コマンドの拒否、確認への差し戻し、入力の制限 | 実行後のテスト結果確認 |
PostToolUse | tool call成功後 | lint、format、差分、短い検査結果の返却 | 副作用の予防 |
Stop | Claudeが応答を終える直前 | 最終応答に不足した検証結果やリスクの差し戻し | すべての品質保証の完全自動化 |
Hookの前に、permissionsの存在を外せません。Claude Codeのpermissionsはallow、ask、denyでtool useを管理します。公式Docsでは、deny、ask、allowの順で評価され、denyは優先されます。PreToolUseが allow を返してもdeny/askルールを迂回できるわけではありません。ここを間違えると、Hookを安全装置として過信しやすくなります。
CIやGitHub Actions側の境界も別物です。Claude CodeをCIに入れる場合のprompt injectionや権限分離は、Claude Code GitHub ActionsをCIに入れる前にで扱ったように、workflow permissions、secrets、fork PRの扱いまで含めて設計する必要があります。HooksはローカルまたはClaude Code実行環境内のゲートであり、CI全体の権限設計を置き換えるものではありません。
結果
- 1止める
PreToolUseで危険操作を実行前に止めます。
- 2検査する
PostToolUseで実行後だから分かる軽い検査を返します。
- 3差し戻す
Stopで完了報告に必要な材料が足りない場合だけ戻します。
Hookが重すぎる、判定が曖昧、出力が長い、という状態はレビューゲートをノイズに変えます。
チームでClaude Code Hooksを使うなら、最初に入れるべき設計は「PreToolUseで止める」「PostToolUseで検査する」「Stopで完了前に差し戻す」の3層です。
Hookを増やすほど安全になる、という見方は危ういです。Hookが重すぎると、開発者はローカル設定で無効化したくなります。Hookの判定が曖昧だと、Claudeが何を直せばよいか分からず、同じ差し戻しを繰り返します。Hookの出力が長いログのままだと、レビューゲートではなくノイズになります。
実務での初期方針は、次のくらいが扱いやすいです。
| 層 | 最初に守るもの | 返す情報 | 成功条件 |
|---|---|---|---|
| PreToolUse | 破壊的Bash、秘密情報ファイル、想定外の本番操作 | 拒否理由と代替案の方向 | 危険操作が実行前に止まる |
| PostToolUse | 編集後のformat、lint、禁止パス変更、短いテスト | 直すべき失敗だけ | Claudeが次の一手を選べる |
| Stop | summary、tests、not run、risks、files changed | 足りない項目 | レビューに必要な材料が揃う |
検証記事としてのE2E実行ログではありません。この記事では2026年6月8日に公式Docsを確認し、ローカルではバージョン確認だけを行いました。Hookの入力フィールドやsettingsの挙動は更新され得るため、導入前には自分のClaude Codeバージョンで /hooks、/permissions、設定ファイルの読み込み元を確認してください。
PreToolUseで実行前に止める
`rm -rf` など、復旧に時間がかかる操作です。
`git push –force` や保護ブランチへのpushです。
migration実行や本番データ更新など、影響範囲が大きい操作です。
credentialファイルの読み取りや外部送信を実行前に止めます。
PreToolUseの新規実装では、permissionDecisionをhookSpecificOutput側へ寄せる設計が扱いやすくなります。
PreToolUse はtool callが走る前のゲートです。ここに置くべきものは、実行してしまうと取り返しがつきにくい操作です。
たとえば、次のような操作はPostToolUseでは遅い可能性があります。
rm -rfや広範囲削除git push --forceや保護ブランチへのpush- 本番DB更新やmigration実行
.env、秘密鍵、credentialファイルの読み取りや外部送信curl | shのように外部コードを即時実行するコマンド- MCP tool経由の投稿、更新、削除、課金対象API呼び出し
公式Hooks referenceでは、PreToolUseは hookSpecificOutput.permissionDecision として allow、deny、ask、defer を返せると説明されています。以前のtop-level decision / reason はPreToolUseでは非推奨なので、新規に書くなら hookSpecificOutput 側へ寄せます。
最小の考え方は、Bash全体を雑に止めることではありません。日常的に必要な git diff、npm test、rg まで止めると、Hookはすぐ邪魔者になります。まずは「実行されたら困るもの」だけに絞ります。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"if": "Bash(git push *)",
"command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pretooluse-danger.mjs"
},
{
"type": "command",
"if": "Bash(rm *)",
"command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pretooluse-danger.mjs"
}
]
}
]
}
}バージョン差分を確認してから使う
確認項目
if フィールドは公式Hooks guideで説明されており、Claude Code v2.1.85以降が必要です。古いバージョンでは期待どおり絞り込めない可能性があるため、チーム配布前にローカルの claude --version を確認します。
拒否理由は短く返す
実装方針
Hook script側では、危険操作を検出したら短い理由を返します。実行可能な危険手順を詳しく出す必要はありません。
#!/usr/bin/env node
let raw = "";
for await (const chunk of process.stdin) raw += chunk;
const input = JSON.parse(raw || "{}");
const command = input.tool_input?.command ?? "";
const denied =
/\brm\s+-rf\b/.test(command) ||
/\bgit\s+push\b.*--force/.test(command);
if (denied) {
console.log(JSON.stringify({
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "Destructive or history-rewriting command blocked. Propose a dry-run or ask for human approval."
}
}));
}ここで大切なのは、Hookを企業ポリシーの唯一の防波堤にしないことです。全社で禁止したい操作はmanaged settingsやpermissionsのdenyへ置き、Hookはより文脈的な判断や説明を返す層にします。denyルールはHookのallowで上書きできないため、最小権限の設計と相性がよいです。
ファイル編集も同じです。Edit、Write、MultiEdit をすべて止めるのではなく、対象パスと変更種別を見るべきです。認証、決済、CI、migration、lockfile、AGENTS.md、.claude/settings.json のようなファイルは、通常のUI文言修正とはレビュー強度が違います。AGENTS.mdや運用ルールの変更レビューは、AGENTS.mdを変更レビューに入れる前にで扱ったinstruction driftの問題ともつながります。
PostToolUseで実行後に検査する
編集後に崩れた形式や基本的な静的検査を確認します。
変更ファイルが触ってはいけない場所を含んでいないか見ます。
対象ファイルに近いunit testを走らせ、失敗の要点を返します。
大きすぎる生成物や不要な差分を早めに見つけます。
全文ログより、Claudeが次に直せる短い指示のほうが修正に進みやすくなります。
PostToolUse はtool callが成功した後に動きます。ここを「危険操作を止める場所」と考えると危険です。ファイル書き込み、コマンド実行、外部送信などの副作用は、すでに起きています。
実行後だから分かる軽い検査に絞る
条件
PostToolUseに向いているのは、実行後だからこそ分かる軽量検査です。
- 編集後にformatやlintを確認する
- 変更ファイルが禁止パスを含んでいないかを見る
- テストを一部だけ走らせ、失敗の要点をClaudeへ返す
- 生成物が大きすぎないか確認する
- tool outputが長すぎる場合に、次の行動に必要な部分だけを返す
PostToolUseの出力は、人間に見せるログそのものではなく、Claudeが次に直せる指示にします。たとえば npm test の全文を返すより、「src/billing.test.ts の境界値ケースが1件失敗。期待値は税込110、実値は100」のように短く返したほうが、次の修正に進みやすくなります。
設定例は、編集系toolにだけ軽量検査を紐づける形から始めると扱いやすいです。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{
"type": "command",
"command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/posttooluse-edit-check.mjs"
}
]
}
]
}
}ここで毎回フルCIを走らせると、すぐ重くなります。PostToolUseは細かく、短く、頻繁に返る検査に向いています。時間がかかるE2E、外部APIを含む統合テスト、DB初期化が必要な検査は、Stop、CI、PRチェックへ回したほうが運用しやすいです。
機密情報は出してから隠さない
注意点
また、PostToolUseで機密情報を隠す設計には注意が必要です。Claudeが見るtool outputを加工できる場面があっても、秘密情報を出してから隠すのは順番が逆です。秘密情報が出る可能性のあるtool callは、PreToolUseやpermissions側で止めます。AIコーディングエージェントにIssue、Docs、MCP出力を読ませるときのprompt injectionや情報境界は、AIコーディングエージェントのprompt injection対策の論点とも重なります。
PostToolUseを入れるときの判断基準は、次の3つです。
- 検査結果が10秒から数十秒で返るか
- 失敗理由がClaudeにとって修正可能な粒度か
- 失敗時に人間がHookを無効化したくなるほど重くないか
Hookの目的は、Claudeを罰することではありません。次の一手を小さくすることです。
Stopで完了宣言の前に差し戻す
stop_hook_activeを見ずに毎回ブロックすると、同じ差し戻しが続きやすくなります。
Stop はClaudeが応答を終えるタイミングで動くHookです。ここには、最終応答に足りないレビュー材料をチェックする役割が向いています。
stop_hook_activeでループを避ける
注意点
公式Docsでは、Stop hooksは stop_hook_active と last_assistant_message を受け取ると説明されています。stop_hook_active は、すでにStop hook由来でClaudeが継続中かどうかを見るためのフィールドです。これを見ずに毎回ブロックすると、同じ差し戻しが続きます。公式Docsでは8回連続ブロック後にClaude CodeがHookを上書きしてturnを終えることにも触れています。
最終応答の事実だけを見る
評価基準
Stopに置くべき完了条件は、チームのレビュー習慣に合わせます。たとえば、最終応答に次の項目がなければ差し戻す、という形です。
- 変更内容の短いsummary
- 実行したtests
- 実行していない検査と理由
- 変更ファイルまたは重要な差分
- 残リスク
- 人間にレビューしてほしい箇所
Stop hookの出力は、エラー通知ではなく作業継続の指示にできます。公式Docsでは additionalContext を使い、Claudeへ「テストを走らせてから終了して」といった追加文脈を返す例が示されています。
#!/usr/bin/env node
let raw = "";
for await (const chunk of process.stdin) raw += chunk;
const input = JSON.parse(raw || "{}");
const message = input.last_assistant_message ?? "";
if (input.stop_hook_active) process.exit(0);
const required = ["Tests", "Not run", "Risks"];
const missing = required.filter((word) => !message.includes(word));
if (missing.length > 0) {
console.log(JSON.stringify({
hookSpecificOutput: {
hookEventName: "Stop",
additionalContext: `Before finishing, add the missing review fields: ${missing.join(", ")}. Keep it short and include only facts you verified.`
}
}));
}この例は英語ラベルを見ていますが、実際のチームではPRテンプレートや最終報告の語彙に合わせます。日本語運用なら「テスト」「未実行」「リスク」「変更ファイル」などに寄せたほうが自然です。
Stop hookでやりすぎないことも大切です。Stopは「完成度を100点にする採点者」ではなく、「レビューに必要な材料が欠けていないかを見る受付」です。文章の美しさまで判定し始めると、Claudeが同じ箇所を書き換え続けたり、作業完了が不必要に遅れたりします。
チームで配るならsettings、permissions、MCP、subagentsを分ける
Hookだけで権限設計を置き換えるのではなく、settingsとpermissionsを先に整理します。
共有ルールはProject、個人例外はLocal
配置
Claude Codeの設定にはスコープがあります。公式Settings docsでは、Managed、User、Project、Localのように、どこに置くかで影響範囲が変わると説明されています。
| スコープ | 主な置き場所 | 向いているもの | 注意点 |
|---|---|---|---|
| Managed | 管理者配布の設定 | 全社禁止ルール、上書き不可の制限 | プロジェクト側から解除できない前提で慎重に扱う |
| User | ~/.claude/ | 個人の好み、全プロジェクト共通の補助 | チーム標準として共有されない |
| Project | .claude/settings.json | repo標準のHook、ask/deny、チームルール | commit対象なのでレビューが必要 |
| Local | .claude/settings.local.json | 個人の一時例外、ローカル実験 | チーム全体の安全策にはならない |
チームで配るHookは、基本的にProject settingsとリポジトリ内のHook scriptへ置きます。そうすれば、Pull Requestでレビューできます。個人の実験はLocal settingsに寄せます。本当に上書き不可にしたいものはmanaged settingsの領域です。
read-onlyでも出力範囲を確認する
MCP
MCPはさらに注意が必要です。Claude CodeはMCPによって外部ツール、DB、API、issue trackerなどに接続できます。便利ですが、toolの数と副作用の範囲が増えます。read-onlyに見えるMCPでも、巨大なログ、個人情報、秘密情報、prompt injectionを含む外部テキストを返す可能性があります。
MCP toolをHookの対象にするなら、次を確認します。
- MCP serverがlocalかremoteか
- OAuth scopeやtokenがどの権限を持つか
- toolがreadだけかwriteも持つか
- 出力が長くなりすぎないか
- 本番データや個人情報を返す可能性があるか
- tool callの承認を人間が見るべきか
subagentsも同じです。レビュー専用、テスト専用、DB専用のsubagentを作ると、責務を分けやすくなります。一方で、Agent呼び出し自体、subagentのtool権限、SubagentStopでの完了条件という新しい境界も増えます。Codex側のsubagent運用を考える場合は、Codex subagentsをチームで使う前にのように、並列化、権限、コスト、レビュー結果の統合まで見たほうが判断しやすくなります。
最小実装は3ファイルから始める
- 1.claude/settings.json
チームで共有するHook設定を置きます。
- 2pretooluse guard
実行前に止める操作を判定します。
- 3posttooluse check
編集後の軽量検査を短く返します。
- 4stop checklist
完了応答に必要なレビュー材料を確認します。
最小構成は、守る条件が説明できる範囲に絞ると運用しやすくなります。
最初から大きなHook frameworkを作る必要はありません。小さく始めるなら、次の3ファイル構成で十分です。
.claude/
settings.json
hooks/
pretooluse-danger.mjs
posttooluse-edit-check.mjs
stop-review-gate.mjs.claude/settings.json は、どのイベントでどのHookを呼ぶかだけを書きます。Hook scriptはNode.jsやshellでよいですが、チームで読みやすい言語に寄せます。重要なのは、Hook script自体も通常のアプリコードと同じようにレビューすることです。
バージョンと読み込み元を先に見る
手順
導入前に、次のコマンドで最低限の前提を確認します。
claude --version
node --versionこの記事の作成時点では、手元の claude --version は 2.1.138 (Claude Code)、node --version は v25.9.0 でした。公式Docsにはローカル確認バージョンより新しいフィールドも含まれるため、background_tasks や session_crons のような新しめのStop入力は、チームの実バージョンで確認してから使います。
最初のPreToolUseは、危険コマンドと機密ファイルだけに絞ります。PostToolUseは編集後の軽量チェックにします。Stopは最終応答のレビュー材料だけを見ます。この3つが安定してから、MCP tool、subagent、HTTP hook、prompt hookへ広げます。
deny回数と差し戻し理由を残す
計測
運用時は、Hookを入れたあとに次の数を記録すると調整しやすくなります。
| 観測するもの | 見たい理由 |
|---|---|
| PreToolUseのdeny回数 | 本当に危険操作を止めているか、誤検知が多すぎないか |
| PostToolUseの検査失敗 | AIが繰り返し壊しやすい箇所があるか |
| Stopの差し戻し理由 | 最終報告で欠けやすいレビュー材料は何か |
| Hookの平均実行時間 | 開発体験を壊していないか |
| Hook無効化の相談 | ルールが現実に合っているか |
この記録を持たずにHookを増やすと、「なんとなく安全そうな設定」が増えます。増やす前に、まず減らせるルールがないかを見るほうが長持ちします。
失敗点
PostToolUseは実行後なので、外部送信や削除の予防には向きません。
日常作業の摩擦が増えると、Local settingsや一時回避で外されやすくなります。
Stopでは丁寧さより、テスト結果、未実行理由、リスク、変更範囲を見ます。
Hookは細かく増やすより、レビューに必要な事実を短く返せる設計が重要です。
一つ目の失敗は、PostToolUseで危険操作を止められると考えることです。PostToolUseは実行後です。外部送信や削除が起きた後でログを見ても、予防にはなりません。危険操作はPreToolUseかpermissions側で止めます。
二つ目は、Hookを広くしすぎることです。Bash 全体をaskにする、編集系toolを全部止める、毎回フルテストを走らせる、といった設計は、最初は安心に見えます。しかし日常作業の摩擦が増えると、開発者はLocal settingsや一時回避でHookを外したくなります。
三つ目は、Stop hookで文章を採点し始めることです。最終応答が丁寧かどうかより、レビューに必要な事実があるかを見ます。テスト結果、未実行理由、リスク、変更範囲が揃っていれば、文章の細かい好みは人間レビューで十分です。
四つ目は、Hook自体をレビューしないことです。HookはAIの動きを制御するコードです。ここにバグがあると、危険な操作を見逃したり、逆に通常作業を止めたりします。.claude/settings.json や .claude/hooks/ の変更は、通常のアプリコードと同じようにレビュー対象にします。
五つ目は、MCPをread-onlyだから安全と扱うことです。read-onlyでも、秘密情報や個人情報を読む可能性があります。出力にprompt injectionが含まれることもあります。write権限だけでなく、read権限の範囲もレビュー対象です。
実務で使うなら
- 1レビュー条件を書く
何を守るのか、何を差し戻すのかを先に文章で決めます。
- 2権限を分ける
permissions、settings scope、人間承認フローを整理します。
- 3繰り返しだけHook化
何度も起きるレビュー漏れを小さくHookへ移します。
- 4出力を短くする
ログ全文ではなく、次に直せる要点を返します。
守っている条件を説明できないHookは、あとから運用の負担になりやすくなります。
実務導入では、Hookを作る前にレビュー条件を書き出します。よくある順番は逆です。先に便利そうなHookを入れ、あとから何を守っているのか説明できなくなります。
まず、次のように分けます。
| 目的 | Hookにする前の確認 |
|---|---|
| 危険コマンドを止める | permissionsのdenyで足りるか、PreToolUseで文脈判断が必要か |
| 編集後に検査する | 10秒から数十秒で返せるか、失敗理由を短く返せるか |
| 完了報告を整える | PRテンプレートやレビュー基準と同じ語彙になっているか |
| MCP操作を制限する | OAuth scope、toolの副作用、出力の機密性を確認したか |
| subagentを使う | 親sessionとsubagentの権限境界を説明できるか |
次に、チーム内でHookの所有者を決めます。誰が誤検知を直すのか、誰が公式Docs更新を追うのか、誰がmanaged settingsとProject settingsの境界を決めるのか。ここが曖昧だと、Hookは古くなります。
最後に、人間承認の位置を残します。Claude Code Hooksは、作業を速くしながらレビュー材料を揃えるための補助です。決済、認証、個人情報、本番DB、secrets、CI/CD、権限設定に関わる変更では、人間の承認を外さないほうがよいです。法人導入やAPIキー、非公開リポジトリの扱いまで含める場合は、権限表、承認フロー、ログ保管、例外申請まで一緒に決めます。
AI Dev Lab Japanでは、チーム導入前のAIコーディング権限設計、HooksやMCPの棚卸し、レビューゲート設計の相談も扱っています。まずは既存リポジトリで「AIに読ませてよいもの」「実行してよいもの」「人間承認が必要なもの」を分けるだけでも、導入判断はかなり現実的になります。
セキュリティ・コスト注意
APIキー、顧客データ、非公開リポジトリ情報をログや追加文脈へ出さないようにします。
送信先URL、環境変数、到達できる範囲を確認します。
接続先、OAuth scope、toolのread/write権限を確認します。
重い検査やsubagentの並列化は、待ち時間と利用量を増やします。
秘密情報はPostToolUseで後から消す前提ではなく、PreToolUseやpermissionsで出さない設計にします。
Hooksは、セキュリティを補強できます。ただし、Hookを入れたから安全になる、とは言えません。公式Security docsでも、Claude Codeはpermissions、approval、sandbox、credential storage、MCP trust verificationなど複数の保護を組み合わせています。Hookはその一部です。
Hookログへ出さない
機密情報
特に注意したいのは、秘密情報です。APIキー、社内コード、個人情報、顧客データ、非公開リポジトリ情報を、HookのログやClaudeへの追加文脈へ出さないようにします。PostToolUseでredactionする前提ではなく、PreToolUseやpermissionsで出力されないようにするのが基本です。
HTTP hookの送信先を制限する
外部送信
HTTP hookを使う場合は、送信先URLと環境変数の扱いを確認します。公式Settings docsでは、HTTP hooksが到達できるURLのallowlistとして allowedHttpHookUrls が説明されています。外部URLへHook payloadを送る設計は、便利さより先にデータ境界を見ます。
重い検査はCIやPR側へ逃がす
コスト
コスト面では、Hookが重いほどAIコーディングの体験が悪くなります。毎回フルテスト、毎回大きなログ要約、毎回外部API問い合わせ、毎回複数subagent起動という設計は、待ち時間と使用量を増やします。Hookは軽く、CIは重く、PRレビューは人間が判断する、という役割分担にしたほうが続きます。
また、Hookの出力が長すぎると、Claudeの文脈を圧迫します。Hookは「何が失敗したか」「次に何をすべきか」を短く返します。大きなログは保存先だけ示し、必要な抜粋だけをClaudeに渡します。
導入しない方がよいケース
まずは権限、設定スコープ、PRレビュー条件、人間承認フローを文章で決めます。
次の状態なら、Hooksを増やす前に設計を戻したほうがよいです。
- permissionsのdeny/askが未整理
.claude/settings.jsonの変更レビューがない- Hook scriptの所有者がいない
- Stop hookで何を完了条件にするか決まっていない
- MCP serverのscopeやtoken権限が分からない
- 機密情報をPostToolUseで隠せばよいと考えている
- Hookが失敗したときの回避手順がない
この状態でHookを入れると、見た目だけ安全な自動化になります。まずはpermissions、settings scope、PRレビュー条件、人間承認フローを文章で決めます。その後に、繰り返し発生するレビュー漏れだけをHook化します。
FAQ
安全にはなりません。permissions、managed settings、CI、人間レビューも必要です。
明確な禁止はdenyを土台にし、文脈つきの判断をPreToolUseで足します。
毎回は重くなりやすいため、軽い検査はPostToolUse、重い検査はCIやPRチェックに回します。
通常のtoolと同じように、scope、権限、出力の機密性をレビューします。
最初の1本は、危険操作のPreToolUseガードか、完了報告のStopチェックリストが扱いやすい入口です。
Claude Code HooksだけでAIコーディングは安全になりますか
なりません。Hooksはpermissions、managed settings、CI、人間レビューを補強する仕組みです。危険操作をPreToolUseで止められても、秘密情報の扱い、MCPのscope、CIの権限、レビュー承認までは別に設計が必要です。
PreToolUseとpermissionsのdenyはどちらを優先すべきですか
全社またはチームで明確に禁止したいものはdenyに置きます。PreToolUseは、tool inputの文脈を見て差し戻し理由を返したい場合や、ask/deferの判断を足したい場合に使います。PreToolUseのallowはdeny/askを迂回しないため、denyを土台にするほうが安全です。
PostToolUseでテストを全部走らせるべきですか
毎回のフルテストは重くなりやすいです。PostToolUseには軽いformat、lint、対象ファイルに近いunit test、禁止パス検査が向いています。重いE2Eや統合テストはStop、CI、PRチェックに回します。
Stop hookで無限ループしませんか
設計を誤ると起きます。stop_hook_active を見て、すでにStop hook由来で継続中なら通す、差し戻し理由を1つか2つに絞る、同じ条件で繰り返し止めない、という実装にします。公式Docsでは連続ブロック上限にも触れられています。
MCP toolにもHookをかけるべきですか
副作用や機密性があるMCP toolには検討すべきです。ただしHook以前に、OAuth scope、toolのread/write範囲、serverの所有者、出力内容を確認します。Hookで後から隠すのではなく、危険な呼び出しは実行前に止めます。
チームの最初の1本は何を作るべきですか
危険Bashを止めるPreToolUseか、最終応答にtests/not run/risksを要求するStop hookが始めやすいです。どちらも、効果と誤検知を確認しやすいからです。PostToolUseは便利ですが、重い検査を入れすぎないように注意します。
関連資料と導線
secrets、workflow permissions、fork PR、prompt injectionを別に設計します。
instruction driftと権限競合をレビュー対象にします。
read-only開始、OAuth scope、出力の機密性、人間承認を先に決めます。
並列化で増えるコストとレビュー統合を確認します。
Hooksは、設定ファイル、権限、MCP、CI、レビュー基準と強く結びつきます。
Claude Code Hooksは、AIコーディングの設定ファイル、権限、MCP、CI、レビュー基準と強く結びつきます。Hooks単体の記事として読むより、次の観点とセットで見ると判断しやすくなります。
- CIにClaude Codeを入れるなら、secrets、workflow permissions、fork PR、prompt injectionを別に設計する
- AGENTS.mdやCLAUDE.mdを運用するなら、instruction driftと権限競合をレビュー対象にする
- MCPを接続するなら、read-only開始、OAuth scope、出力の機密性、人間承認を先に決める
- subagentを使うなら、並列化で増えるコストとレビュー統合を確認する
更新通知や新しいClaude Code/Codexの仕様変更チェックを追いたい場合は、記事末尾のニュースレター導線から更新を受け取れます。本文の判断材料を確認した後に、必要な人だけ登録する位置づけです。
次に読むなら
参照した主な情報源
- https://code.claude.com/docs/en/hooks
- https://code.claude.com/docs/en/hooks-guide
- https://code.claude.com/docs/en/permissions
- https://code.claude.com/docs/en/settings
- https://code.claude.com/docs/en/security
- https://code.claude.com/docs/en/mcp
- https://code.claude.com/docs/en/sub-agents
更新履歴
- 2026-06-08
Claude Code公式DocsのHooks、Hooks guide、Permissions、Settings、Security、MCP、Sub-agentsを確認しました。
- ローカル確認
`claude –version` は `2.1.138`、`node –version` は `v25.9.0` であることを確認しました。
- Xの扱い
需要シグナルの補助として扱い、本文の事実根拠には使わない方針にしました。
仕様やバージョンに依存する判断は、確認日と確認範囲を残すとレビューしやすくなります。
- 2026-06-08: Claude Code公式DocsのHooks、Hooks guide、Permissions、Settings、Security、MCP、Sub-agentsを確認。ローカルでは
claude --versionが2.1.138 (Claude Code)、node --versionがv25.9.0であることを確認。Xは需要シグナルの補助としてのみ扱い、本文の事実根拠には使わない方針で公開前チェックを行った。