Guard rails：モデルとアクションの間のブレーキ層

小さなタスク、広すぎる権限

エージェントに小さな作業を依頼しました：あるモジュールのバリデーションを修正する。より確実にしたいと判断したエージェントは追加でいくつかのディレクトリをスキャンし、センシティブなconfigファイルを開き、さらについでに無関係なcleanupもまとめて同じPRに含めました。

一見すると問題なさそうです。テストもpassしています。しかしcontextには不要なファイルが混入し、secretがtranscript（あなたとエージェントの会話の全記録）に入り込んだ可能性があり、修正すべき部分と「ついで」の部分が同じPRに混在しているためレビューが散漫になっています。

agentic codingにおけるguard railとは

Guard railはエージェントとアクションの間に立つ層です：リスクのある操作はブロックし、疑わしい操作は警告します。階段の端にある手すりのようなもので、歩き方が上手くなるわけではありませんが、一歩踏み外しても事故になる可能性を減らします。プロンプト内の指示（prompt instruction）と異なり、guard railはモデルが「覚えているか」に依存せず、ツール調整層で動作します。

Guard railと指示の違い

Guard railの動作原理

Harnessはモデルを包むruntime層です。モデルは「このファイルを読みたい」または「このコマンドを実行したい」と決定するだけで、harnessがtool callを受け取り、権限を管理し、hookを呼び出し、ツールを実行またはブロックし、結果をモデルに返します。Hookは、検査や状態記録のために介入するため、harnessがtool callのライフサイクル（prompt受信時、tool前、tool後）の固定タイミングで自動的に呼び出す小さなスクリプトです。すべての実際のアクションがharnessを通過するため、guard railを組み込む場所はここです。

概念の背景についてはこちら：Duy /zuey/ による Harness Engineering とは？

ClaudeKit Hooksマップ

ClaudeKit Hooksの詳細はVividKit Guidesで読めます。

HookはモデルI内にはありません。Claude Codeのライフサイクルに位置します：settings.jsonがどのhookを呼び出すかを決定し、.ck.json/ENVがruntime behaviorを決定します。hookの出力は、実行を許可・ブロックし、contextをinjectし、ツールまたはセッション終了後にstate/artifactを記録できます。

guard railを通過するtool callのフロー

重要なポイント：pre-tool hookはexit codeを返します。Exit 0でツール実行、exit 2でブロックして理由をモデルへ送信。フロー内の3つの主要な介入ポイントには対応する技術名があります：UserPromptSubmit（prompt受信時）、PreToolUse（tool前）、PostToolUse（tool後）。Stop/SubagentStopはセッションまたはsubagent終了時に実行されるため、上のライフサイクルマップに示されています。

2種類のブロック

CKの7つのguard railグループ

各グループはどこで参照するか

よくある9つのシナリオ

SettingsとConfig層

どのguardが動作するかを決定する2つのconfig層：settings.jsonがhookをClaude Codeのライフサイクルに組み込み、.ck.jsonが各hookのオン・オフを切り替え、thresholdを調整します。

# グローバルスコープ
~/.claude/settings.json
~/.claude/.ck.json
~/.claude/hooks/*.cjs

# プロジェクトスコープ
.claude/settings.json
.claude/.ck.json
.claude/hooks/*.cjs

settings.json：どのhookがどのタイミングで動作するか

以下のsnippetはfreshなCKインストールにおけるPreToolUseの一断面のみを示しています：CKはscout-blockとprivacy-blockを提供し、ツール実行前にClaude Codeが呼び出せるようライフサイクルにwireします。インストール済み環境のfull hook configにはさらに多くのlifecycle eventがあります。確認すべき場所はClaude Codeのsettings.jsonです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Glob|Grep|Read|Edit|Write",
        "hooks": [
          { "command": "node \".claude/hooks/scout-block.cjs\"" },
          { "command": "node \".claude/hooks/privacy-block.cjs\"" }
        ]
      }
    ]
  }
}

settings.jsonはlifecycleマップです：ユーザーがpromptを送信したときにどのhookが動作するか、ツール実行前にどのhookが呼び出されるか、ツール完了後にどのhookが処理を続けるか。グローバルインストールの場合、CLIはテンプレート内の相対コマンドをnode "$HOME/.claude/hooks/scout-block.cjs"形式に変換します。プロジェクトインストールの場合、pathは通常.claude/hooks/...形式のままです。

3つのラベルでhookテーブルを読む

すべてを「デフォルトでオン・オフ」と単純化しないでください。hookの状態には3つの異なる層があります：

以下のテーブルは stable claudekit-engineer@2.19.1 時点の hook リストのスナップショットです。2026-06-09 更新：claudekit-engineer@2.19.2-beta では task-completed-handler と teammate-idle-handler の削除が準備されています。upstream ClaudeKit が新しい version を release すると、このリストは14 hookになる可能性があります。

見落としやすいポイント：isHookEnabled()はhooks.<name>がfalseのときのみ無効化されます。keyがなければ通常enabledとみなされます。ただし個別のスイッチを持つguardもあります：privacy-blockは旧keyprivacyBlock=falseを読み取り、simplify-gateはsimplify.gate.enabledとENV変数CK_SIMPLIFY_DISABLED=1を持ちます。

手動でのオン・オフと自己確認

素早く変更するには、対象スコープの.ck.jsonを編集します。keyが明示的に設定されている場合、プロジェクトconfigがグローバルより優先されます。keyがなければinherit・デフォルトに従います。settings.jsonでwire済みのhookに対しては、falseで無効化し、上位スコープで無効化されていた場合はtrueで再有効化できます。以下のHook列のhook名はhooks.<name>で使用するkeyと同じです。

// .claude/.ck.json または ~/.claude/.ck.json
{
  "hooks": {
    "scout-block": false,
    "privacy-block": true
  },
  "privacyBlock": true,
  "simplify": {
    "gate": {
      "enabled": true
    }
  }
}

hookがトリガーされるか確認したいときは、ファイル名ではなくlifecycle eventを確認してください。同じhookスクリプトは、settings.jsonのevent・matcherが現在のアクションと一致するときのみ動作します。以下のテーブルは各hookを素早く確認する方法です。not wiredのhookは先にwireするか、スクリプトが対応していれば手動CLIで呼び出す必要があります。

// ~/.claude/settings.json または .claude/settings.json
{
  "env": {
    "CK_SIMPLIFY_DISABLED": "1"
  }
}

scout-block — 不要なディレクトリの読み取りをブロック

エージェントはよくnode_modules/を読んだり、ルートで**/*.tsをglobしたり（globはパスマッチングパターン。**/*.tsはすべてのサブディレクトリのすべての.tsファイルを意味します）、dist/index.jsをcatしたりします。その都度、数万tokenがcontextに詰め込まれ、コストと次のturnの品質を低下させます。scout-block.cjsはPreToolUseを登録し、すべてのRead・Bash・Glob・Grepの前に動作します。

# ベースライン .ckignore — pattern-matcher.cjs が処理
node_modules
dist
build
.next
.nuxt
__pycache__
.venv
venv
vendor
target
.git
coverage

privacy-block — secretをブロックし、ユーザーの明示的な承認を求める

エージェントが.env、id_rsa、*.pem、credentials.yamlに触れると — secretがtranscriptに漏れます。一度contextに入ると、ログに残ったり、reviewer outputに引用されたり、PRにペーストされる可能性があります。

@@PRIVACY_PROMPT_START@@
{ "type": "PRIVACY_PROMPT", "question": {...}, "options": [...] }
@@PRIVACY_PROMPT_END@@

ClaudeはJSONをparseし、AskUserQuestionを呼び出します。ユーザーが承認した場合、hookメッセージは承認済みの方法でファイルを読むよう案内します。例えば確認後にcat ".env"を実行するなど。コードはプレフィックスAPPROVED:もサポートしています。重要な点：明示的なapprovalが必要であり、モデルに同意を自己解釈させません。

simplify-gate — diffがスコープを超えて膨らんだときにshipをブロック

小さなタスクが多数のファイルに触れるPRに膨らむことがあります：バリデーションの修正、cleanupの追加、フォーマット変更、周辺helperの調整。エージェントが「OK ship」と言うとき、simplify-gate.cjsはUserPromptSubmitを登録し、git diff HEADを読み取り、promptに以下のいずれかが含まれる場合のみ評価します：ship merge pr deploy publish。

simplify.thresholdのデフォルト値：追加+削除行の合計、変更ファイル数、1ファイル内の最大追加行数。gateがブロックするのはsimplify.gate.enabled=trueの場合のみで、これらの値は.ck.jsonでoverrideできます。

// プロジェクト .ck.json — 実際に有効化する
{ "simplify": { "gate": { "enabled": true } } }

matchedSeverity()は"don't ship"を無視し、"ship on"から"ship on Friday"も通過します。あるスコープのすべてのセッションでgateを無効にするには、settings.jsonのenvキーにCK_SIMPLIFY_DISABLED=1を設定してください。

workflow-artifact-gate — 5つのartifact JSON

フルパイプライン → 各フェーズが決定を記録したJSONファイルを残します。各ステップ後の領収書のようなものです。このhookはUserPromptSubmit + PreToolUse(Bash)にアタッチするよう設計されていますが、freshインストール後のデフォルトのhookセットには含まれておらず、使用するにはopt-inが必要です。

このgateには2段階の処理があります。ship・push・PR・deployなどのリスクの高いステップでは、hookはフローを即座に停止し、理由をモデルに返せます（emitBlock()）。finalizeやcommitなどの軽いステップでは、hookはフローを続行しながら、モデルが自己修正できるよう警告をcontextに追加します（emitSoft()）。

Skill markdownのHard-gate XML

Hookはtool callのみをブロックします。tool callではなく順序の問題があります：plan前のコーディング、scout前のfix。CKはskill markdownに<HARD-GATE>を組み込んでいます。

<HARD-GATE>
Do NOT write implementation code until a plan exists
and has been reviewed. Exception: --fast skips research
but still requires a plan step. User override: if user
explicitly says 'just code it', respect their instruction.
</HARD-GATE>

ck:cookとck:fixはそれぞれ4つのhard-gate（plan/scout-first、exact-reqまたはroot-cause、no-side-effects）を持ちます。

dev-rules-reminder — ruleをcontextに組み込む

dev-rules-reminder.cjsはUserPromptSubmitを登録し、各promptにrulesテキストをinjectします。ここで明確に区別すべき2つの層があります：hookはcontextをinjectするメカニズムであり、CLAUDE.md内のruleはinjectされるコンテンツです。TTLは(sessionId, baseDir)ごとに5分で、tokenの無駄遣いを防ぎます。

Guard skills — ユーザーが呼び出すguard層

code-reviewerエージェントは9項目のチェックリストを実行します：concurrency、error boundary、API contract、backwards compat、input validation、auth/authz、N+1、data leak、fact-check。マージ前の最後のguardです。

既知のGap

ベストプラクティスと落とし穴

Guard railを信頼する前の6つの確認事項

• settings.jsonは現在どのhookをどのlifecycleにアタッチしているか？
• .ck.jsonはどのhookを無効化しているか？（outer + inner config）
• 現在のClaude Codeセッションはpermission promptをスキップしているか？
• プロジェクトの.ckignoreでoverrideがあるか？node_modulesが!でallowlistされているか？
• CLAUDE.mdのruleファイルは完全か？
• このセッションでサイレントにクラッシュしたhookがあるか（stderrを確認）？

用語集