Guard rails：模型与操作之间的制动层

一个小任务，权限却过宽

你交给 agent 一件小事：修复某个模块中的 validation。它为了更稳妥，多扫了几个目录，打开了敏感的 config 文件，然后顺手把一些不相关的 cleanup 也塞进同一个 PR。

表面上一切正常，测试也通过了。但 context 已混入无关文件，secret 可能已进入 transcript（你与 agent 之间对话的完整记录），而 review 也因为待修改部分和「顺手」部分混在同一个 PR 里而被稀释。

agentic coding 中 guard rail 是什么

Guard rail 是介于 agent 与操作之间的一层：有风险的操作予以拦截，可疑的操作发出警告。它就像楼梯边缘的护栏：不会让你走得更好，但能降低踩空变成事故的概率。与 prompt 中的提示语（prompt instruction）不同，guard rail 运行在工具调度层，不依赖模型是否「记住」。

区分 guard rail 与提示语

Guard rail 如何工作

Harness 是包裹模型的运行时层。模型只决定「我想读这个文件」或「我想执行这条命令」；harness 才是接收 tool call、管理权限、调用 hook、决定让 tool 运行或拦截、并将结果返回给模型的一方。Hook 是 harness 在 tool call 生命周期的固定时间点自动调用的小脚本——收到 prompt 时、tool 执行前、tool 执行后——用于介入检查。由于所有真实操作都经过 harness，这里是挂载 guard rail 的地方。

概念背景延伸阅读：Duy /zuey/ 的 Harness Engineering là gì?。

ClaudeKit Hooks 映射图

ClaudeKit Hooks 的更多细节可见 VividKit Guides。

Hook 不在模型内部。它位于 Claude Code 的生命周期中：settings.json 决定调用哪些 hook，.ck.json/ENV 决定运行时行为，hook 的输出可以允许运行、拦截、注入 context，或在 tool 或 session 结束后写入 state/artifact。

一次 tool call 经过 guard rail 的流程

关键点：pre-tool hook 返回 exit code。Exit 0 允许 tool 运行，exit 2 拦截并将原因推送给模型。流程中三个主要介入点有对应的技术名称：UserPromptSubmit（收到 prompt 时）、PreToolUse（tool 执行前）、PostToolUse（tool 执行后）。Stop/SubagentStop 在 session 或 subagent 结束时运行，因此位于上方的生命周期映射图中。

两种拦截方式

CK 中的七类 guard rail

各分组在哪里查阅

9 个常见场景

Settings 与各 config 层

两层 config 决定哪些 guard 运行：settings.json 将 hook 挂载到 Claude Code 的生命周期；.ck.json 逐个启用/禁用 hook 并调整 threshold。

# Global scope
~/.claude/settings.json
~/.claude/.ck.json
~/.claude/hooks/*.cjs

# Project scope
.claude/settings.json
.claude/.ck.json
.claude/hooks/*.cjs

settings.json：哪些 hook 在哪个时间点运行

以下片段仅展示全新 CK 安装中 PreToolUse 的一个切面：CK 提供 scout-block 和 privacy-block，并将它们连接到生命周期，以便 Claude Code 在 tool 运行前调用。已安装机器上的完整 hook config 包含更多生命周期事件；需要查看的地方是 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 是生命周期映射：用户发送 prompt 时调用哪个 hook，tool 运行前调用哪个 hook，tool 完成后由哪个 hook 继续处理。全局安装时，CLI 会将模板中的相对命令替换为 node "$HOME/.claude/hooks/scout-block.cjs" 形式；项目安装时，路径通常保持 .claude/hooks/... 形式。

按 3 个标签读取 hook 表格

不要把所有内容归为「默认开启/关闭」。一个 hook 的状态有三个不同层面：

下表是 stable claudekit-engineer@2.19.1 的 hook 列表快照。2026-06-09 更新：claudekit-engineer@2.19.2-beta 准备移除 task-completed-handler 和 teammate-idle-handler；当 upstream ClaudeKit 发布新版本时，列表可能变为 14 个 hook。

容易忽略的点：isHookEnabled() 只在 hooks.<name> 为 false 时禁用。缺少 key 通常被视为 enabled。但部分 guard 还有独立开关：privacy-block 仍读取旧 key privacyBlock=false，simplify-gate 有 simplify.gate.enabled 和 ENV CK_SIMPLIFY_DISABLED=1。

手动启用/禁用与 hook 自检

如需快速调整，在目标 scope 修改 .ck.json。当 key 明确设置时，项目 config 优先于全局；缺少 key 时继续 inherit/默认。对于已在 settings.json 中 wire 的 hook，设为 false 即禁用，设为 true 可在上层 scope 禁用后重新启用。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 是否被触发，看生命周期事件而非文件名。同一 hook 脚本只有当 settings.json 中的 event/matcher 与当前操作匹配时才运行。下表是快速检查每个 hook 的方法；not wired 的 hook 需先 wire 或通过手动 CLI 调用（若脚本支持）。

// ~/.claude/settings.json 或 .claude/settings.json
{
  "env": {
    "CK_SIMPLIFY_DISABLED": "1"
  }
}

scout-block——拦截读取无用目录

Agent 经常读取 node_modules/、在根目录使用 **/*.ts glob（glob 是路径匹配模式；**/*.ts 表示所有子目录中的所有 .ts 文件）、cat dist/index.js。每次都会将数万 token 塞入 context，拉高成本并降低后续 turn 的质量。scout-block.cjs 注册 PreToolUse，在所有 Read/Bash/Glob/Grep 之前运行。

# Baseline .ckignore——由 pattern-matcher.cjs 处理
node_modules
dist
build
.next
.nuxt
__pycache__
.venv
venv
vendor
target
.git
coverage

privacy-block——拦截 secret，强制用户明确审批

Agent 接触 .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，调用 AskUserQuestion。若用户批准，hook 消息会引导通过已批准路径读取文件，例如在询问后执行 cat ".env"；代码也支持 APPROVED: 前缀。核心点：必须有明确的 approval，不能让模型自行解读 consent。

simplify-gate——当 diff 膨胀超出 scope 时拦截 ship

一个小任务可能膨胀成触及过多文件的 PR：修复 validation、添加 cleanup、改格式、调整几个相邻 helper。当 agent 说「OK ship」时，simplify-gate.cjs 注册 UserPromptSubmit，读取 git diff HEAD，仅在 prompt 包含以下内容时判断：ship merge pr deploy publish。

simplify.threshold 的默认值：总新增+删除行数、触及文件数、单个文件中的最大新增行数。只有在 simplify.gate.enabled=true 时 gate 才会拦截；这些值可在 .ck.json 中覆盖。

// project .ck.json——真正启用
{ "simplify": { "gate": { "enabled": true } } }

matchedSeverity() 会忽略 "don't ship"、"ship on"——"ship on Friday" 也会通过。若要在该 scope 的所有 session 中关闭 gate，在 settings.json 的 env key 下设置 CK_SIMPLIFY_DISABLED=1。

workflow-artifact-gate——5 个 artifact JSON

完整 pipeline → 每个 phase 留下一个记录决策的 JSON 文件，如同每步之后的收据。此 hook 设计用于挂载到 UserPromptSubmit + PreToolUse(Bash)，但不在全新安装后默认运行的 hook 集中；需要使用须 opt-in。

此 gate 有两种处理级别。在 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，将 rules 文本注入每个 prompt。这里需要区分两层：hook 是注入 context 的机制，而 CLAUDE.md 中的 rule 是被注入的内容。按 (sessionId, baseDir) 设置 5 分钟 TTL 以避免 token 消耗。

Guard skills——用户调用的 guard 层

code-reviewer agent 运行 9 项检查清单：并发、error boundary、API contract、向后兼容、输入验证、auth/authz、N+1、数据泄露、事实核查。合并前的最后一道 guard。

已知缺口

Best practices 与常见陷阱

相信 guard rail 前的 6 个检查问题

• settings.json 当前将哪些 hook 挂载到哪些生命周期？
• .ck.json 禁用了哪些 hook？（outer + inner config）
• 当前 Claude Code session 是否在跳过权限提示的模式下运行？
• 是否有项目 .ckignore override？node_modules 是否被 ! 加入 allowlist？
• CLAUDE.md 中的 rule 文件是否齐全？
• 本 session 中是否有 hook 静默 crash（检查 stderr）？

术语速查