Hook 如何写才不翻车：小、确定、可解释、可回滚

TL;DR： Hook 是确定性治理层，不是第二个 Agent。四条硬性约束：小（代码 ≤ 50 行，复杂度评分 ≤ 20）、确定（同样 stdin → 同样退出码）、可解释（每个 exit 2 必须带规则编号和替代方案）、可回滚（可单独禁用，禁用即时生效）。违反任一条，上线前重写。

Hook 的治理定位

Hook 系统在 Claude Code 工程体系中占据特定位置：它是介于 CLAUDE.md 的非确定性约束和 Permission System 的粗粒度控制之间的确定性脚本层。三层治理机制各有边界：

治理层机制确定性粒度可审计─────────────────────────────────────────────────────CLAUDE.md提示词指令低自由文本无Rules路径作用域指令低目录级无Hooks脚本高调用级有退出码+输出Permission权限系统高工具级有

Hook 不是万能的。它无法做语义判断（"这段代码安不安全"），无法理解上下文（"这次修改是否符合当前任务"）。它只能做模式匹配——路径模式、命令模式、文件名模式。试图让 Hook 超越模式匹配，就是在构建第二个 AI，而第二个 AI 没有推理能力。

决策矩阵：Hook vs Rules vs CLAUDE.md

选择治理机制时，依据以下矩阵：

需求特征CLAUDE.mdRulesHookPermission─────────────────────────────────────────────────────────────────────────"不要修改.env文件"次选--首选--"修改src/auth/后要跑测试"次选次选首选--"代码风格遵循ESLint"首选------"这个项目使用React18"首选次选----"禁止使用rm-rf"----首选--"Bash工具需要授权"------首选"生成的测试放在tests/目录"首选次选----"PR描述必须包含变更范围"次选--首选--"子袋里必须输出JSON格式"次选--首选--"禁止安装新依赖"次选--首选--

选择逻辑：

判断路径：├─是否需要阻断工具调用？│└─是→Hook(PreToolUse)或Permission│├─阻断条件可以用模式匹配表达→Hook│└─阻断条件是工具级别的→Permission│├─是否需要路径作用域的上下文？│└─是→Rules│├─是否是项目级别的行为偏好？│└─是→CLAUDE.md│└─是否需要在事件触发时自动执行操作？└─是→Hook(PostToolUse/Stop)

关键原则：能用 CLAUDE.md 解决的不用 Hook，能用 Hook 解决的不依赖提示词。 CLAUDE.md 的优势是灵活、零执行成本、可迭代。Hook 的优势是确定性、可审计、零上下文消耗。当约束的违反代价高（密钥泄露、生产故障）时，必须用 Hook 兜底，不能只靠提示词。

原则一：小

工程定义

一个 Hook 只做一件事。量化指标：

|指标|硬性上限|超限后果|检测方法|| --- | --- | --- | --- ||有效代码行数|≤ 50 行|审计成本指数增长| wc -l（去掉注释和空行）||条件分支|≤ 5 个 if|测试组合爆炸，覆盖率不足| grep -c 'if|case' ||正则表达式|≤ 3 个|维护困难，误判风险高| grep -cE '[^#]*[[:space:]]*[.*]' ||外部命令调用|0 个|执行时间不可控，确定性丧失|`grep -cE 'curl||环境依赖|≤ 2 个|移植性差|检查 command -v||执行时间|≤ 500ms|每次工具调用增加延迟| time echo '{}' | bash hook.sh |

复杂度评分公式

复杂度=(代码行数/10)+(分支数×2)+(正则数×3)+(外部命令数×5)合格阈值:≤20警告阈值:20~30拒绝阈值:>30示例评分：┌──────────────────────────────────────────────────────────────┐│30行,3分支,2正则,0外部命令││=3+6+6+0=15✓合格││││80行,8分支,5正则,2外部命令││=8+16+15+10=49✗必须拆分││││45行,4分支,3正则,0外部命令││=4.5+8+9+0=21.5⚠临近阈值，审查后决定│└──────────────────────────────────────────────────────────────┘

复杂度超标的拆分策略

当一个 Hook 的复杂度评分超过 20，按职责边界拆分。每个拆分后的 Hook 覆盖一个独立的判定维度：

拆分前（复杂度49）:block-sensitive-files.sh(80行)├─文件路径模式检查(30行)├─文件内容密钥扫描(30行)└─白名单豁免逻辑(20行)拆分后（三个独立Hook）:├─block-sensitive-paths.sh(25行,复杂度8)→matcher:Edit|Write├─scan-secret-patterns.sh(28行,复杂度10)→matcher:Edit|Write└─check-file-whitelist.sh(18行,复杂度5)→matcher:Edit|Write

拆分后的 Hook 在 settings.json 中配置为同一 matcher 下的独立条目，Claude Code 按顺序执行。任何一个 Hook 返回 exit 2 即阻断，不继续执行后续 Hook。

拆分带来的工程收益：

• • 每个 Hook 独立测试、独立部署、独立禁用

• • 任何一个 Hook 出问题，只影响对应的检查维度

• • 团队可以并行维护不同 Hook，不产生合并冲突

• • 新增检查维度时添加新 Hook，不修改已有 Hook

原则二：确定

工程定义

同样的 stdin JSON 输入，永远产生同样的退出码和 stdout 输出。排除所有非确定性来源：

|非确定性来源|典型代码模式|后果|替代方案|| --- | --- | --- | --- ||网络调用| curl, wget|超时/失败时行为不一致|本地模式匹配||时间依赖| date用于条件分支|不同时间行为不同|移除时间条件||文件系统状态| test -f, ls|状态变化导致行为变化|只读 stdin 输入||随机数| $RANDOM, shuf|同一调用结果不同|全量检查或模式匹配||外部进程| git status, npm ls|权限/网络问题导致失败|静态配置||环境变量| $ENV_VAR |不同机器配置不同|硬编码常量|

确定性审查检查清单

审查每个Hook脚本中的每条命令：├─curl/wget/nc→移除。API超时=系统阻塞。├─date用于条件判断→移除。时间规则放StopHook做提醒。├─test-f/ls/stat→移除。Hook只处理stdin。├─$RANDOM/shuf/awk'rand()'→移除。检查逻辑不应有随机性。├─git/npm/docker→移除。外部进程的输出不可控。├─env变量（非PATH/jq）→改为硬编码。环境差异会导致不一致。└─jq/grep/sed→允许。纯文本处理，输入确定则输出确定。

可接受的有限例外

两个场景允许有限的不确定性，但不得影响 PreToolUse 的阻断决策：

原则三：可解释

工程定义

每个 exit 2（阻断）路径的 stdout 输出必须包含四个字段。缺任何一个字段的阻断消息都是不合格的。

BLOCK:[操作描述]—一句话说明被拦截了什么原因:[触发条件]—具体哪个模式被匹配规则:[规则标识]—规则编号或名称，可追溯到文档建议:[替代操作]—Claude可以执行的替代方案

可解释性之所以关键，因为 Claude 会读取 Hook 的 stdout 输出来调整后续行为。消息质量直接决定 Claude 的纠错效率：

低质量阻断消息："BLOCK"→Claude不知道问题所在，反复尝试相同操作，消耗token中等质量阻断消息："BLOCK:不能修改.env文件"→Claude知道.env被保护，但不知道为什么，不知道替代方案高质量阻断消息："BLOCK:尝试修改.env.production原因:文件路径匹配模式[.env.]规则:SEC-003环境变量文件保护建议:使用vaultCLI或AWSSSM更新生产环境变量"→Claude理解规则、知道原因、有明确的替代路径

阻断消息质量度量

|度量维度|合格标准|检查方法|| --- | --- | --- ||exit 2 路径包含操作描述|100%|检查每个 exit 2 前的 echo 语句||exit 2 路径包含规则标识|100%|grep 检查 "规则:" 字段||exit 2 路径包含替代方案|≥ 80%|grep 检查 "建议:" 字段||消息长度 ≤ 4 行|≥ 90%|过长消息降低 Claude 处理效率||exit 0 路径有 stdout 输出|0%|exit 0 不应产生任何输出|

原则四：可回滚

工程定义

每个 Hook 必须满足三个回滚性条件：

禁用机制

机制 1：配置移除（首选）

从 settings.json 中移除 Hook 配置项。效果即时：

{"hooks":{"PreToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"bash.claude/hooks/scan-secret-patterns.sh"}]},{"matcher":"Bash","hooks":[{"type":"command","command":"bash.claude/hooks/block-dangerous-commands.sh"}]}]}}

临时禁用 scan-secret-patterns：移除第一个 hooks 数组中的条目，保留 block-dangerous-commands 不受影响。

机制 2：脚本级 feature flag

在脚本入口处添加快速退出逻辑，通过文件存在性控制：

#!/bin/bash#紧急禁用：创建.claude/hooks/disabled-scan-secret即可禁用此HookDISABLED_FLAG=".claude/hooks/disabled-$(basename"$0".sh)"[[-f"$DISABLED_FLAG"]]&&exit0#...正常Hook逻辑...

一个 touch 命令即可禁用，一个 rm 即可恢复。

机制 3：规则级 feature flag

按规则编号控制，适用于包含多条规则的 Hook：

#!/bin/bashDISABLED_RULES=".claude/hooks/disabled-rules"INPUT=$(cat)FILE_PATH=$(echo"$INPUT"|jq-r'.tool_input.file_path//empty')is_disabled(){grep-q"^$1$""$DISABLED_RULES"2>/dev/null}#SEC-001:.env文件保护if[["$FILE_PATH"==*".env"*]];thenis_disabled"SEC-001"&&exit0echo"BLOCK:.env文件受SEC-001保护"echo"建议:使用环境变量管理工具更新"exit2fi#SEC-002:证书文件保护if[["$FILE_PATH"==*.pem||"$FILE_PATH"==*.key]];thenis_disabled"SEC-002"&&exit0echo"BLOCK:证书文件受SEC-002保护"echo"建议:通过证书管理流程更新"exit2fiexit0

#.claude/hooks/disabled-rules#每行一个规则编号，#开头为注释#SEC-001SEC-002

回滚性验证清单

每个Hook上线前必须通过以下测试：├─[]从settings.json移除Hook配置→ClaudeCode正常运行├─[]Hook脚本文件不存在→ClaudeCode不报错（fail-open）├─[]Hook脚本有语法错误→ClaudeCode不报错（fail-open）├─[]Hook执行超时→ClaudeCode超时后继续（fail-open）├─[]禁用HookA→HookB正常执行└─[]恢复HookA→HookA恢复正常执行

完整的 settings.json 配置示例

以下是一个经过生产验证的完整 Hook 配置，覆盖四个事件类型：

{"hooks":{"PreToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"bash.claude/hooks/block-sensitive-paths.sh"},{"type":"command","command":"bash.claude/hooks/scan-secret-patterns.sh"}]},{"matcher":"Bash","hooks":[{"type":"command","command":"bash.claude/hooks/block-dangerous-commands.sh"}]}],"PostToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"bash.claude/hooks/auto-format.sh"}]}],"Stop":[{"matcher":"","hooks":[{"type":"command","command":"bash.claude/hooks/session-summary.sh"}]}]}}

配置要点：

• • PreToolUse 的 Edit|Write matcher 下挂两个 Hook，按顺序执行。第一个返回 exit 2 则整体阻断，不执行第二个。

• • PreToolUse 的 Bash matcher 只挂一个命令检查 Hook。

• • PostToolUse 只做格式化，不做阻断（PostToolUse 的 exit 2 无阻断语义）。

• • Stop 事件使用空 matcher 匹配所有事件，生成会话摘要。

反模式：生产环境中的 Hook 失败模式

反模式 1：外部 API 调用导致全局阻塞

场景。 团队需要一个 Hook 检测文件内容中的密钥和凭证。文件名模式匹配不够用，于是调用内部分类 API。

有问题的实现：

#!/bin/bash#.claude/hooks/classify-file.sh—反模式：依赖外部APIINPUT=$(cat)CONTENT=$(echo"$INPUT"|jq-r'.tool_input.new_string//.tool_input.content//empty')RESPONSE=$(curl-s-XPOSThttps://internal-api.company.com/classify-H"Content-Type:application/json"-d"{"content":$(echo"$CONTENT"|jq-Rs.)}"--max-time10)CLASSIFICATION=$(echo"$RESPONSE"|jq-r'.classification//"unknown"')if[["$CLASSIFICATION"=="sensitive"]];thenecho"BLOCK:内容被标记为敏感"exit2fiexit0

故障序列。 API 服务器部署新版本重启 → 所有 curl 请求超时 10 秒 → Claude Code 每次文件修改等 10 秒 → 一次会话修改 15 个文件 = 150 秒额外等待 → 团队禁用 Hook。更严重：API 偶尔返回 500 时，classification 解析为 "unknown"，Hook 放行，安全检查被完全绕过。

根因分析：

• • Hook 依赖外部服务，可用性不受控制

• • 10 秒超时对高频调用的 Hook 不可接受

• • 错误路径默认放行，等于 API 故障时检查失效

• • 同样内容，API 正常时阻断，API 故障时放行——违反确定性原则

修复： 移除 API 调用，改用本地正则模式匹配：

#!/bin/bash#.claude/hooks/scan-secret-patterns.sh—修复版set-euopipefailINPUT=$(cat)FILE_PATH=$(echo"$INPUT"|jq-r'.tool_input.file_path//empty')CONTENT=$(echo"$INPUT"|jq-r'.tool_input.new_string//.tool_input.content//empty')#路径模式（确定性）forpatternin".env"".pem"".key""secret""credential";doif[["$FILE_PATH"==*"$pattern"*]];thenecho"BLOCK:路径包含敏感关键词[$pattern]"echo"规则:SEC-004敏感文件路径保护"echo"建议:使用密钥管理服务更新"exit2fidone#内容模式（确定性）if[[-n"$CONTENT"]];thenifecho"$CONTENT"|grep-qE'AKIA[0-9A-Z]{16}';thenecho"BLOCK:内容包含AWSAccessKey格式"echo"规则:SEC-005密钥格式检测"echo"建议:使用AWSIAM角色替代硬编码密钥"exit2fiifecho"$CONTENT"|grep-qE'-----BEGIN(RSA|EC)?PRIVATEKEY-----';thenecho"BLOCK:内容包含私钥标记"echo"规则:SEC-006私钥注入检测"echo"建议:从密钥管理服务加载私钥"exit2fifiexit0

改动对比：

|维度|反模式版本|修复版本|| --- | --- | --- ||外部依赖|curl + API 服务|jq + grep（标准工具）||最坏执行时间|10 秒（超时）|< 100ms||确定性|依赖 API 响应|纯模式匹配||错误处理|API 故障→放行|无外部调用，无此问题||复杂度评分|8+6+3+5 = 22|25/10+4×2+2×3+0 = 11.5|

反模式 2：过宽的 Matcher 导致所有操作被扫描

场景。 一个团队在 PreToolUse 上配置了不区分工具类型的全局 Hook：

{"hooks":{"PreToolUse":[{"matcher":"","hooks":[{"type":"command","command":"bash.claude/hooks/check-everything.sh"}]}]}}

空 matcher 匹配所有工具调用。如果 check-everything.sh 执行耗时 200ms（不算多），一次会话 80 次工具调用 = 16 秒额外延迟。而且每次调用都触发完整检查逻辑，即使工具调用是 Read（只读操作，不存在安全风险）。

修复： 精确设置 matcher，只为有风险的工具类型配置 Hook：

{"hooks":{"PreToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"bash.claude/hooks/block-sensitive-paths.sh"}]},{"matcher":"Bash","hooks":[{"type":"command","command":"bash.claude/hooks/block-dangerous-commands.sh"}]}]}}

Read、Glob、Grep 等只读工具不触发任何 Hook，零额外延迟。

反模式 3：Hook 内部状态管理

场景。 Hook 维护一个"已提醒次数"计数器，超过 3 次后从提醒升级为阻断：

#!/bin/bash#反模式：Hook内部维护状态COUNTER_FILE=".claude/hooks/.remind-counter"COUNT=$(cat"$COUNTER_FILE"2>/dev/null||echo"0")COUNT=$((COUNT+1))echo"$COUNT">"$COUNTER_FILE"if[["$COUNT"-gt3]];thenecho"BLOCK:已提醒3次，现在阻断"exit2fiecho"提醒:请运行测试（第$COUNT次提醒）"exit0

问题：计数器在不同会话间累积，某次手动清理后行为突变。文件权限问题导致写入失败时计数器归零。并发执行时计数器竞态条件。所有这些都是非确定性的来源。

修复： Hook 不维护状态。提醒型 Hook 每次都提醒，阻断型 Hook 每次都阻断。状态管理是 CLAUDE.md 或 Rules 的职责，不是 Hook 的职责。

反模式 4：阻断合法操作导致工作流中断

场景。 一个 Hook 阻断所有对 package.json 的修改：

#!/bin/bash#反模式：规则过宽，阻断合法操作INPUT=$(cat)FILE_PATH=$(echo"$INPUT"|jq-r'.tool_input.file_path//empty')if[["$FILE_PATH"==*"package.json"*]];thenecho"BLOCK:package.json受保护，禁止修改"exit2fiexit0

结果：Claude 无法安装依赖、无法更新版本号、无法修复 vulnerability。开发者不得不频繁禁用 Hook，最终 Hook 形同虚设。

修复： 降级为提醒型 Hook，不做阻断。或者在 PreToolUse 中只对高风险字段做提醒，在 Stop Hook 中做全局检查：

#!/bin/bash#修复版：提醒而非阻断INPUT=$(cat)FILE_PATH=$(echo"$INPUT"|jq-r'.tool_input.file_path//empty')if[["$FILE_PATH"==*"package.json"*]];thenecho"提醒:正在修改package.json"echo"建议:修改后运行npmaudit检查依赖安全性"#exit0—不阻断，只提醒fiexit0

Hook 测试策略

单元测试：固定输入验证退出码

每个 Hook 必须有独立的单元测试脚本。测试框架无需复杂——bash 函数即可：

#!/bin/bash#tests/hooks/test-block-sensitive-paths.shset-eHOOK=".claude/hooks/block-sensitive-paths.sh"PASS=0FAIL=0assert_block(){localdesc="$1"input="$2"result=$(echo"$input"|bash"$HOOK"2>&1)code=$?if[[$code-eq2]];thenecho"PASS:$desc(blocked)"((PASS++))elseecho"FAIL:$desc(expectedblock,gotexit$code)"((FAIL++))fi}assert_pass(){localdesc="$1"input="$2"result=$(echo"$input"|bash"$HOOK"2>&1)code=$?if[[$code-eq0&&-z"$result"]];thenecho"PASS:$desc(passed,nooutput)"((PASS++))elseecho"FAIL:$desc(expectedpasswithnooutput,gotexit$codeoutput='$result')"((FAIL++))fi}#正向测试：应该阻断assert_block".env文件"'{"tool_name":"Edit","tool_input":{"file_path":"/src/.env"}}'assert_block".env.production文件"'{"tool_name":"Edit","tool_input":{"file_path":"/src/.env.production"}}'assert_block".pem证书文件"'{"tool_name":"Write","tool_input":{"file_path":"/certs/server.pem"}}'assert_block"生产配置目录"'{"tool_name":"Edit","tool_input":{"file_path":"infra/prod/kubernetes.yml"}}'#反向测试：应该放行assert_pass"普通源文件"'{"tool_name":"Edit","tool_input":{"file_path":"/src/auth.ts"}}'assert_pass"测试文件"'{"tool_name":"Edit","tool_input":{"file_path":"/tests/auth.test.ts"}}'assert_pass"无文件路径的调用"'{"tool_name":"Bash","tool_input":{"command":"gitstatus"}}'#边界测试assert_pass"空JSON"'{}'assert_pass"nullfile_path"'{"tool_name":"Edit","tool_input":{"file_path":null}}'assert_pass"空file_path"'{"tool_name":"Edit","tool_input":{"file_path":""}}'#汇总echo""echo"Results:$PASSpassed,$FAILfailed"[[$FAIL-eq0]]||exit1

测试覆盖矩阵

每个 Hook 的测试用例必须覆盖三个维度：

|维度|覆盖要求|最少用例数|| --- | --- | --- ||正向（应该阻断）|每个匹配模式至少 1 个|≥ 2||反向（应该放行）|相似但不匹配的输入至少 1 个|≥ 2||边界（异常输入）|空输入、null、缺失字段|≥ 1|

集成测试：与 Claude Code 的端到端验证

单元测试验证 Hook 逻辑的正确性。集成测试验证 Hook 在 Claude Code 运行时中的实际行为。

集成测试步骤：

集成测试清单（手动执行）：1.阻断验证├─启动ClaudeCode├─要求Claude修改.env文件├─确认Claude收到BLOCK消息├─确认Claude没有修改.env文件└─确认Claude选择了替代方案或停止操作2.放行验证├─启动ClaudeCode├─要求Claude修改普通源文件├─确认文件正常修改└─确认没有额外延迟（Hook执行时间<500ms）3.故障降级验证├─故意制造Hook脚本语法错误├─启动ClaudeCode├─确认ClaudeCode正常运行（fail-open）└─恢复Hook脚本4.禁用验证├─从settings.json移除Hook配置├─确认ClaudeCode正常运行├─要求Claude修改原本被阻断的文件├─确认修改成功执行└─恢复settings.json配置

CI 中的 Hook 测试

将 Hook 单元测试集成到 CI pipeline：

#.github/workflows/hook-tests.ymlname:HookTestson:[push,pull_request]jobs:hook-tests:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:Installjqrun:sudoapt-getinstall-yjq-name:Runhookunittestsrun:|fortestintests/hooks/test-*.sh;doecho"Running$test"bash"$test"||exit1done

每次推送或 PR 时自动验证所有 Hook 的行为一致性。

Hook 故障模式与降级

故障分类

|故障类型|表现|频率|Claude Code 行为|影响|| --- | --- | --- | --- | --- ||语法错误|Hook 无法启动|低|fail-open（放行）|检查失效||运行时崩溃|set -e 触发，中途中断|中|fail-open（放行）|检查失效||执行超时|Hook 挂起无响应|低|超时后放行|延迟 + 检查失效||逻辑错误|正常执行但判断错误|高|按错误结果执行|误阻断或误放行||依赖缺失|jq 等工具不可用|中|Hook 报错，放行|检查失效|

降级层级

正常运行：├─PreToolUse:模式检查→阻断或放行├─PostToolUse:增量验证→记录或提醒└─Stop:全局检查→生成报告Hook故障（降级模式）：├─PreToolUse:fail-open→放行所有调用│└─兜底:PermissionSystem（工具级权限仍在）├─PostToolUse:跳过→不记录不提醒│└─兜底:CI/CDpipeline（事后验证）└─Stop:跳过→不生成报告└─兜底:gitdiff+人工review设计决策:fail-open而非fail-closed。Hook是附加控制层，不是核心依赖。故障时回退到无Hook状态，而非锁定所有操作。

逻辑错误的监测

语法错误和运行时错误会导致 fail-open，影响可控。逻辑错误（Hook 正常执行但判断错误）更危险。

监测策略：

Hook 复杂度评估模板

每个 Hook 上线前的标准评估流程：

##Hook上线评估###基本信息-名称:block-sensitive-paths.sh-事件:PreToolUse-Matcher:Edit|Write-类型:command-行为:阻断###复杂度评分-代码行数:25→2.5分-条件分支:2→4分-正则表达式:0→0分-外部命令:0→0分-总分:6.5/20✓合格###确定性审查-[x]无网络调用-[x]无时间依赖-[x]无文件系统状态依赖-[x]无随机数-[x]无外部进程###可解释性审查-[x]每个exit2包含操作描述-[x]每个exit2包含规则标识-[x]每个exit2包含替代方案-[x]exit0路径无stdout输出###可回滚性审查-[x]可通过移除配置禁用-[x]禁用后其他Hook不受影响-[x]脚本出错时fail-open###性能审查-[x]执行时间<500ms（实测:45ms）-[x]matcher设置精确（不匹配只读工具）###测试状态-单元测试:通过（8用例）-集成测试:通过-CI集成:已配置###结论:✓可以上线

Hook 审计模板

##Hook审计记录###基本信息-名称:[文件名]-事件:[PreToolUse/PostToolUse/Stop/SubagentStart/SubagentStop]-Matcher:[正则或空]-类型:[command/prompt]-行为:[阻断/提醒/记录]-规则编号:[如SEC-001]-作者:[姓名]-上线日期:[日期]-上次审查:[日期]###输入-格式:JSON(stdin)-关键字段:[列表]###输出-exit0:[放行条件]-exit2:[阻断条件，仅PreToolUse]-stdout:[阻断消息格式]-stderr:[日志格式]###匹配规则[列出所有模式和对应行为]###禁用方法[具体操作步骤]###变更历史|日期|变更|原因||------|------|------||...|...|...|###误判记录|日期|误判文件/命令|类型|原因|修复||------|-------------|------|------|------||...|...|误阻断/误放行|...|...|

部署分层策略

Hook 的部署应该从低风险到高风险逐步升级，不跳层：

第一层：记录型├─事件:PostToolUse├─行为:记录工具调用到日志文件├─风险:零（不影响执行流程）├─部署时机:项目开始使用ClaudeCode时└─目的:建立行为基线，为后续规则制定提供数据第二层：提醒型├─事件:PostToolUse,Stop├─行为:输出提示信息，不改变行为├─风险:低（只在stdout输出文本）├─部署时机:记录型运行2~4周后└─目的:改善Claude的工作习惯，验证规则准确性第三层：窄规则阻断型├─事件:PreToolUse├─行为:exit2阻断特定操作├─风险:中（可能误阻断）├─规则范围:只覆盖明确的危险操作（.env,rm-rf,--force）├─部署时机:提醒型验证无误后└─目的:保护不可逆操作第四层：宽规则阻断型├─事件:PreToolUse├─行为:exit2阻断大范围操作├─风险:高（误阻断概率高）├─规则范围:覆盖整个目录、整个工具类别├─部署时机:窄规则稳定运行3个月后└─目的:全面安全合规

跳层的后果：直接部署第三层（阻断型）而没有经过第一二层（记录+提醒），规则中的误判会直接阻断合法操作，团队对 Hook 体系的信任受损。

Hook 与 CI/CD 的边界

Hook 和 CI/CD 是互补的两层防护，不重叠不替代：

|维度|Hook|CI/CD|| --- | --- | --- ||执行时机|工具调用前后（事前）|代码推送后（事后）||反馈速度|毫秒级|分钟级||覆盖范围|单次工具调用|完整代码变更||检查深度|模式匹配|任意深度||执行环境|开发者本地|CI 服务器||可靠性|依赖脚本质量|依赖 CI 配置|

分工原则：

• • Hook 做不了深度检查（静态分析、安全扫描） → 交给 CI

• • CI 做不了实时拦截（阻止当前操作） → 交给 Hook

• • Hook 检测"改了不该改的文件" → 模式匹配，毫秒级

• • CI 检测"代码有没有安全问题" → 语义分析，分钟级

季度治理检查清单

##季度Hook治理###有效性├─[]阻断率是否合理？（>10%过宽，=0%可能不工作）├─[]误判率是否可控？（误阻断≤5次/月）└─[]是否有新增的需保护的操作？###复杂度├─[]是否有Hook超过50行？├─[]是否有Hook复杂度评分超过20？├─[]是否有Hook新增了外部依赖？└─[]是否有Hook正则超过3个？###文档├─[]每个Hook是否有审计记录？├─[]上次审查日期是否在3个月内？└─[]禁用方法是否仍然有效？###测试├─[]单元测试是否通过？├─[]是否覆盖了近期的规则变更？└─[]CIpipeline是否包含Hook测试？

交叉参考

• • 22 Hooks 入门[1]：Hook 系统架构、事件列表和执行流程

• • 23 PreToolUse 防护[2]：PreToolUse Hook 的完整实现和阻断模式

• • 24 PostToolUse / Stop 验证[3]：工具执行后的自动验证和会话摘要

• • 25 Subagent Hooks[4]：子袋里上下文注入和结果收集

• • 33 组织治理[5]：团队级别的 Claude Code 治理框架

权衡

Hook 太少，治理不足；Hook 太多，系统脆弱。一个只保护 .env 的 15 行 Hook，比一个试图分类所有文件的 300 行 Hook 更有价值。

四条原则互相强化：小的 Hook 更容易确定，确定的 Hook 更容易解释，可解释的 Hook 更容易回滚。反过来说，复杂的 Hook 引入不确定性，不确定的行为难以解释，无法解释的 Hook 不敢回滚。保持小，其他三条原则自然跟上。

引用链接

[1] 22 Hooks 入门: ./22-hooks-introduction.md[2] 23 PreToolUse 防护: ./23-pretooluse-guardrails.md[3] 24 PostToolUse / Stop 验证: ./24-posttooluse-stop-verification.md[4] 25 Subagent Hooks: ./25-subagent-hooks.md[5] 33 组织治理: ./33-organization-governance.md