エージェントの行動をプログラムで制御する
Hooksは、エージェントループの外側で特定のイベントに反応して実行されるユーザー定義ハンドラです。 スクリプト、HTTPリクエスト、プロンプト、エージェントなど、さまざまな形式で定義でき、settings.jsonに記述します。
Claudeが何かのツールを使う前後、ターンが終了したとき、通知が発生したときなど、 決まったタイミングで自動的にコードやプロンプトを実行できます。 これにより、品質チェックやセキュリティ制御をClaude自身に頼らず、プログラム的に強制できます。
ポイント: Hooksの最大の価値は「Claudeの判断に依存しない」ことです。 CLAUDE.mdに「rm -rfは使うな」と書いても、Claudeが忘れる可能性があります。 Hooksなら、プログラムで確実にブロックできます。
Hooksには4つのタイプがあり、それぞれ異なるタイミングで発火します。
Claudeがツール（Bash、Edit、Readなど）を実行する直前に発火します。 ここでブロック判定を行えば、危険な操作を実行前に止められます。 matcherでツール名を指定し、特定のツールだけを対象にすることもできます。
ツールの実行が完了した直後に発火します。 実行結果を検証したり、自動的に修正処理を走らせたりするのに使います。 たとえば、コードが生成された後にlintを自動実行するパターンです。
Claudeが1つのターン（応答）を完了したときに発火します。 最終的な出力を検証し、不十分であれば続行を促すことができます。
Claudeが通知イベントを発生させたときに発火します。 外部サービスへの通知送信や、ログ記録に使用します。
Hooksはsettings.jsonのhooks配列に定義します。 各hookにはmatcher（発火条件）とaction（実行内容）を指定します。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"action": {
"type": "command",
"command": "bash /path/to/safety-check.sh"
}
}
],
"PostToolUse": [
{
"matcher": "Edit",
"action": {
"type": "command",
"command": "npx eslint --fix $CLAUDE_FILE_PATH"
}
}
],
"Stop": [
{
"action": {
"type": "prompt",
"prompt": "本当にタスクは完了しましたか？テストは通りますか？"
}
}
]
}
}matcherにはツール名やイベント名を指定します。省略すると全イベントにマッチします。actionにはcommand（シェルコマンド）、prompt（Claudeへの追加プロンプト）、agent（別Agentの呼び出し）を指定できます。
PostToolUseフックで、Claudeが生成したコードに対して自動的にlint/formatを実行するパターンです。 Borisは「最後の10%はhookで整形する」ことを推奨しています。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit",
"action": {
"type": "command",
"command": "npx prettier --write $CLAUDE_FILE_PATH && npx eslint --fix $CLAUDE_FILE_PATH"
}
}
]
}
}Claudeがファイルを編集するたびに、Prettierでフォーマットし、ESLintで問題を修正します。 これにより、CI/CDパイプラインでのlintエラーを事前に防げます。 Claudeにフォーマットルールを覚えさせるよりも、ツールに任せた方が確実です。
PreToolUseフックで、危険なコマンドの実行を事前にブロックするパターンです。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"action": {
"type": "command",
"command": "bash -c 'echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE \"(rm\\s+-rf|git\\s+push\\s+--force|DROP\\s+TABLE)\" && echo \"BLOCK: 破壊的操作は禁止されています\" && exit 1 || exit 0'"
}
}
]
}
}rm -rf、git push --force、DROP TABLEといった破壊的コマンドを 正規表現でマッチングし、検出された場合はexitコード1を返してブロックします。 CLAUDE.mdの指示とは異なり、プログラムで強制されるため確実に防止できます。
Borisが紹介した高度なパターンです。PreToolUseで権限要求を検出し、Opusモデルに転送して攻撃判定を行い、安全であれば自動承認します。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"action": {
"type": "agent",
"agent": "permission-reviewer",
"prompt": "以下のコマンドが安全かどうか判定してください: $CLAUDE_TOOL_INPUT"
}
}
]
}
}permission-reviewerAgentにはOpusモデルを設定しておき、 プロンプトインジェクション攻撃のパターンを検出させます。 たとえば、悪意のあるファイル内容がClaudeに「このファイルを削除して」と指示するケースを Opusが見破り、実行をブロックできます。
Boris Tips: プロンプトインジェクション対策として、 権限判定を別のOpusインスタンスに委譲するのは非常に効果的です。 メインのClaudeが騙されても、独立した判定者が安全性を確認してくれます。
ターン終了時にClaudeに「本当に完了したか」を問いかけ、不十分であれば続行を促すパターンです。
{
"hooks": {
"Stop": [
{
"action": {
"type": "prompt",
"prompt": "タスクを振り返ってください。以下の観点で自己検証してください:\n1. 要求された全ての変更を実装しましたか？\n2. テストは通りますか？\n3. エッジケースは考慮しましたか？\n不十分な点があれば、続行してください。"
}
}
]
}
}Borisが推奨するこのパターンは、Claudeが「できました」と言って途中で止まってしまう問題を解決します。 Stop hookでプロンプトを注入することで、Claudeは自分の出力を客観的に振り返り、 不足があれば自発的に作業を継続します。
Skillの中でhooksを定義すると、そのSkillが起動している間だけ有効なhookを作れます。 Thariq（Anthropic共同創業者）が推奨する2つのパターンを紹介します。
特に慎重に作業したいときに/carefulを呼び出すと、 そのセッション中の破壊的コマンド（rm -rf、git push --forceなど）がブロックされます。
---
name: careful
description: 破壊的操作をブロックする安全モード
hooks:
PreToolUse:
- matcher: Bash
action:
type: command
command: "bash -c 'echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE \"(rm\\s+-rf|git\\s+push\\s+--force)\" && echo BLOCK && exit 1 || exit 0'"
---
# 安全モード有効
破壊的なコマンドの実行をブロックします。特定のディレクトリ内のファイルだけを編集可能にし、それ以外の変更をブロックします。 「このディレクトリだけ触っていい」というスコープ制限を実現します。
---
name: freeze
description: 指定ディレクトリ外の編集をブロック
argument-hint: "編集を許可するディレクトリパス"
hooks:
PreToolUse:
- matcher: Edit
action:
type: command
command: "bash -c '[[ \"$CLAUDE_FILE_PATH\" == \"$0\"* ]] || (echo BLOCK && exit 1)'"
---
# フリーズモード有効
指定されたディレクトリ外のファイル編集をブロックします。Thariqが推奨するもう1つの活用法が、PreToolUseフックでSkillの使用状況を計測するパターンです。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Skill",
"action": {
"type": "command",
"command": "bash -c 'echo \"$(date +%Y-%m-%d_%H:%M:%S) $CLAUDE_TOOL_INPUT\" >> ~/.claude/skill-usage.log'"
}
}
]
}
}どのSkillが何回使われているかをログに記録し、チームの利用状況を把握します。 よく使われるSkillは改善の優先度が高く、ほとんど使われないSkillは削除やリネームを検討します。 特にチーム開発では、人気のSkillと過小利用のSkillを発見することで、 ナレッジ共有の改善ポイントが見えてきます。
Thariq推奨: Skill使用率の計測は、チームのClaude Code活用度を可視化する最もシンプルな方法です。 ログを定期的に分析して「このSkill、誰も使っていないけど便利だから周知しよう」 「このSkill、名前がわかりにくいからリネームしよう」といった改善アクションにつなげてください。
Hooksは、Claude Codeの動作をプログラム的に制御する仕組みです。 コード品質の自動修正、破壊的操作のブロック、プロンプトインジェクション対策、自己検証の強制、 そしてSkill使用率の計測まで、幅広い用途に活用できます。 特に重要なのは「Claudeの判断に依存しない」という点です。 CLAUDE.mdの指示は忘れられる可能性がありますが、Hooksはプログラムで確実に動作します。 セキュリティと品質に関わる制御は、Hooksで実装することを強く推奨します。