本讲摘要第 17 讲讲了 Hooks 的 4 类事件 安全三件套 质量三件套、本讲是 Hooks 系列的下篇、讲 4 个进阶主题Stop Hook 门控任务完成前的强制质量检查/ SubAgent 事件验收子代理完成后的报告自动汇总/ frontmatter 精准配置matcher / type / command 3 字段的最佳实践/ 三维决策框架性能 × 必要性 × 用户体验。目的是让你从会用 Hook 走向精通 Hook——配置精准、响应快速、用户体验好。本讲的三条主线第一、Stop Hook 门控 SubAgent 事件验收——把质量检查和子代理完成验收自动化成机器强制的门、避免人为遗漏。第二、frontmatter 精准配置——matcher 字段精确定位避免 Edit 漏写 Write/ command 字段最佳实践绝对路径 错误信息清晰 退出码正确。第三、三维决策框架——性能Hook 不能 1 秒/ 必要性是否真的需要拦截/ 用户体验不要频繁打断3 维评分决定 Hook 该不该配。学完本讲、你应该能把 6 个 Hook 串成完整防御链PreToolUse 2 PostToolUse 2 Stop 2)、能用 Stop Hook 强制质量门、能用 SubAgentStop 自动汇总子代理报告、能用三维决策框架判断这个 Hook 该不该配。 详细内容Stop Hook 门控任务完成前的强制质量检查第 17 讲说 Stop Hook 可以强制 Claude 继续、本讲深入到完整的 Stop 门控——任务完成前、跑 4 步质量检查、任一不通过就强制继续、直到 4 步全过才允许停止。4 步质量检查步骤 1:未提交检查(check-uncommitted.sh)——git status看是否有未提交的改动。如果有、exit 2 强制 Claude 提醒先 commit。步骤 2:测试通过检查(check-tests.sh)——pytest tests/ -q看是否全过。如果有失败、exit 2 强制 Claude 修复。步骤 3:文档同步检查(check-docs-sync.sh)——对比 src/ 改动 vs docs/ 改动、如果 src 改了 docs 没改、exit 2 强制 Claude 同步文档。步骤 4:审查 checklist 完整性(check-review-checklist.sh)——如果任务涉及代码改动、检查 review 报告是否包含 Security / Style / Test 3 段。缺一段、exit 2 强制 Claude 补全。4 步门控形成质量门——任务未真正完成前、Stop 永远会被阻断、Claude 必须继续把 4 步都做对才能停下。4 步的全或无语义门控的设计原则4 步必须全过、任一不过就 exit 2。这意味着• 步骤 1 失败 → 阻断、不进入步骤 2 / 3 / 4避免连锁阻断。• 步骤 1 通过 步骤 2 失败 → 阻断、不进入步骤 3 / 4。• 4 步全过 → 放行、允许 Stop。这种短路求值避免了步骤 1 失败但步骤 2 3 4 还跑的浪费、Hook 性能也最优。门控 vs 单检查单检查check-uncommitted.sh 单独配的弱点Claude 完成任务后只检查未提交、可能测试失败但没提醒。4 步门控把 4 个检查串成一个 Stop Hook的好处任一不通过都被强制继续、质量门是复合的而不是单点的。4 步门控的实现见后面完整 Stop Hook 门控实现代码块。SubAgent 事件验收子代理完成后的报告自动汇总第 8 讲讲过子代理完成时、主对话需要汇总子代理输出。本讲用 SubAgentStop Hook 自动化这个过程——子代理完成后、Hook 读子代理输出、检查报告完整性、汇总到主对话的状态文件。验收流程子代理完成任务、准备停止。SubAgentStop 事件触发、Hook 脚本读子代理的输出从 stdin 读 JSON、包含 subagent_output 字段。Hook 检查报告完整性比如代码审查 SubAgent 必须有 Security / Style / Test 3 段、缺一段 exit 2 强制继续。Hook 把汇总报告写到 .claude/state/subagent-reports/-.md。Hook 通知主对话“子代理 [name] 报告已汇总、路径 [path]”。5 步形成子代理验收 自动汇总——避免子代理跑完报告没汇总、主对话不知道结果。验收的 3 个检查项检查项 1报告完整性——子代理输出是否包含所有必要段代码审查Security / Style / Test数据分析数据源 / 处理逻辑 / 结论部署版本号 / 环境 / 健康状态。检查项 2输出格式——是否按约定的 Markdown 结构## 标题、表格、列表。检查项 3状态文件——子代理是否写了状态文件到 .claude/state/.json供主对话读取。3 个检查项任一不过、exit 2 强制子代理继续。验收 vs 不验收不配 SubAgentStop Hook 的弱点子代理完成任务后、主对话只看到任务完成信号、不知道具体结果。需要用户主动 /ask 子代理汇报结果、或者主对话自己再读子代理输出——延迟高、容易遗漏。配 SubAgentStop 的好处子代理报告自动汇总到状态文件 通知主对话、主对话可以直接用结果。延迟从用户主动问降到自动汇总,0 用户操作。frontmatter 精准配置matcher / type / command 3 字段第 17 讲配 Hook 时用了 frontmatter 的 matcher / type / command 3 个字段、本讲讲 3 字段的精准配置最佳实践。字段 1matcher 精确定位matcher 字段决定哪个工具触发——Bash / Read / Edit / Write / Grep / Glob 等。常见写法•matcher: Bash——只对 Bash 工具触发危险命令拦截。•matcher: Edit|Write——对 Edit 或 Write 触发自动格式化。•matcher: *——对所有工具触发Stop 门控。•matcher: Edit——只对 Edit 触发漏写 Write 会导致 Write 不触发。易错点写 Edit 漏写 Write,Write 不触发——Claude 用 Write 改文件时、自动格式化 / Lint 检查不会跑。修正涉及修改文件的 Hook 统一写Edit|Write。字段 2type目前仅 “command”)type 字段目前只支持 “command”、表示 Hook 是一个 shell 命令。未来可能支持 “prompt”(LLM 推理触发、“http”(HTTP 回调等。当前用 “command”。字段 3command 最佳实践command 字段是 Hook 脚本的执行命令、3 个最佳实践实践 1用绝对路径——command: bash /home/user/.claude/hooks/deny.sh而不是command: bash .claude/hooks/deny.sh。绝对路径避免 Claude 在不同目录运行时找不到脚本的问题。实践 2错误信息清晰——Hook 脚本 exit 2 时、stderr 必须输出清晰的拒绝原因第 17 讲坑 2。实践 3退出码正确——0 放行 / 通过、2 拒绝 / 强制继续。其他退出码1 / 3 等行为未定义、不要用。3 字段的精准配置决定 Hook 是否按预期工作——matcher 写错 不触发、command 写错 拒绝 / 强制行为错乱。三维决策框架性能 × 必要性 × 用户体验不是所有想法都要配 Hook。这个 Hook 该不该配有 3 维评估标准。维度 1性能Hook 脚本耗时Hook 在 Claude 工具调用的关键路径上、每次都会跑。如果 Hook 太慢、Claude 整体响应速度被拖慢。判断标准Hook 脚本 1 秒。超过 1 秒、优化或拆到 Stop 触发。4 个性能问题Hook 跑 ruff pylint mypy总耗时 10 秒→ 优化只跑 ruff format( 0.5 秒。Hook 跑 pytest 完整套件2 分钟→ 优化移到 Stop 触发、不阻塞工具调用。Hook 跑 curl 拉远程数据网络延迟→ 优化缓存到本地、避免重复拉。Hook 跑 python -c 复杂逻辑启动开销 0.5 秒 逻辑耗时→ 优化用 bash grep 替代。维度 2必要性是否真的需要拦截有些想法听起来好但实际没必要配 Hook。判断标准Hook 拦截后、真的能避免实际发生过的真实问题吗?4 个必要性问题拦截误删 /tmp/test.txt——真发生过多起吗?没有 → 不配。拦截chmod 777——真发生过吗?发生过 → 配。拦截提交含 TODO 的代码——值得拦截吗?看团队规范 → 视情况。拦截在 main 分支直接 commit——团队用 PR 流程吗?用 → 不需要 Hook 拦截main 分支保护由 GitHub 配不用 → 配 Hook 提醒。维度 3用户体验不要频繁打断Hook 频繁阻断会让用户觉得 Claude 怎么老是被打断。判断标准这个 Hook 每天阻断 5 次吗?是、可能太严了或规则不精准。4 个 UX 问题Stop Hook 强制跑 pytest每天阻断 10 次→ 优化只在涉及 test 改动时跑。PreToolUse 拦截所有 rm 命令连 rm /tmp/test 都拦→ 优化只拦 rm -rf。PostToolUse 跑 ruff --fix改文件 → 改回来循环→ 优化只跑 ruff format、不改语义。Stop Hook 阻断未提交每次任务结束都阻断→ 用户已经 commit 怎么办?优化Hook 只在 git status --porcelain 有输出时阻断。3 维评分• 性能 1 秒 通过、1-3 秒 警告、 3 秒 失败。• 必要性真实问题发生过 通过、理论可能 警告、纯理论 失败。• UX 5 次/天 通过、5-10 次/天 警告、 10 次/天 失败。3 维全通过 应该配有 1 维警告 谨慎配任 1 维失败 不配。维度评分标准通过警告失败性能Hook 脚本耗时 1 秒1-3 秒 3 秒必要性真实问题是否发生过发生过多次理论可能纯理论UX每天阻断次数 5 次/天5-10 次/天 10 次/天多 Hook 编排6 个 Hook 串成完整防御链单个 Hook 是点、多个 Hook 串起来是链。本讲展示 6 个 Hook 串成的完整防御链——PreToolUse 2 个拦截 PostToolUse 2 个记录 / 改进 Stop 2 个门控。完整配置见后面6 个 Hook 完整防御链配置代码块。6 个 Hook 的出场顺序形成防御纵深工具执行前PreToolUse deny-pipe-exec.sh 拦截 pipe 执行curl | sh。工具执行前PreToolUse deny-extra-dangerous.sh 拦截危险命令rm -rf / chmod 777。工具执行后PostToolUse auto-format.sh 自动格式化.py 文件 ruff format。工具执行后PostToolUse audit-log.sh 记录所有 Bash 命令.claude/audit/.log。任务完成时Stop check-uncommitted.sh 检查未提交。任务完成时Stop check-tests.sh 检查测试通过。6 个 Hook 叠加形成防御链——任何一步有漏洞、其他步骤兜底。这是 defense in depth 在 Claude Code 中的工程实现。Hooks 的工程最佳实践 5 条5 条最佳实践是 Hook 工程的检查清单、任何 Hook 都应该按这 5 条评估。最佳实践 1Hook 脚本要轻 1 秒Hook 在关键路径上、每次都跑。轻量级用 grep / awk / sed 比 python -c 快缓存常用结果长时间操作完整测试套件改用 Stop 触发。判断标准Hook 脚本 1 秒 优化。最佳实践 2Hook 拒绝要说清原因Hook exit 2 时、stderr 必须输出清晰的拒绝原因“❌ 拒绝rm -rf 被禁止、原因防止误删、改用 rm -i”。这样 Claude 收到后能告诉用户我被拒了、你可以用 rm -i、形成完整反馈链。判断标准Hook 拒绝时 stderr 输出的信息、用户能直接看懂原因?能、正确。最佳实践 3Hook 规则要精准不要误拦Hook 规则要精准——只拦真正危险的模式rm -rf 关键目录、不拦普通 rm。规则写好后、在测试环境跑 10 测试用例5 个应该被拦 5 个应该被放过的、确保两个集合都正确。判断标准Hook 误拦率 5%?调规则。最佳实践 4Hook 配置后要测试配置 Hook 后立即在测试环境跑 5 个应该被拦的命令和 5 个应该被放过的命令、确认两个集合都正确。再用 Stop Hook 的未提交检查故意制造未提交改动、确认 Hook 能强制 Claude 继续。判断标准Hook 配置后、跑过 10 个测试用例吗?没有、补测。最佳实践 5Hook 进 git 配 PR reviewHooks 是工程资产、不是个人草稿。所有 Hook 脚本和 .claude/settings.json 都进 git、变更走 PR review。这样团队用的 Hook 是一致的、可追溯的、可回滚的。判断标准你的 .claude/hooks/ 目录是本地文件还是 git 跟踪?本地、赶紧入 git。️ 实战代码 第 18 讲配套完整 Stop Hook 门控实现4 步质量检查 任一失败强制继续#!/usr/bin/env bash # .claude/hooks/stop-gate.sh # 4 步质量门控:未提交 / 测试 / 文档 / 审查 checklist # 任一不过 exit 2 强制 Claude 继续 set -e FAIL0 # 步骤 1:未提交检查 if git rev-parse --is-inside-work-tree /dev/null 21; then if ! git diff --quiet HEAD 2/dev/null || [ -n $(git status --porcelain) ]; then echo ⚠️ 步骤 1 失败:还有未提交的改动 2 git status --short 2 FAIL1 fi fi # 步骤 2:测试通过检查(只在涉及 test 改动时跑) if git diff --name-only HEAD 2/dev/null | grep -qE ^(src/|tests/); then if command -v pytest /dev/null; then if ! pytest tests/ -q --tbno /dev/null 21; then echo ⚠️ 步骤 2 失败:测试未通过 2 FAIL1 fi fi fi # 步骤 3:文档同步检查(src 改了 docs 没改) if git diff --name-only HEAD 2/dev/null | grep -qE ^src/; then if ! git diff --name-only HEAD 2/dev/null | grep -qE ^docs/; then echo ⚠️ 步骤 3 失败:src 改了但 docs 没同步 2 FAIL1 fi fi # 步骤 4:审查 checklist 完整性(如果改了 src/) if git diff --name-only HEAD 2/dev/null | grep -qE ^src/; then REVIEW_FILE.claude/reports/review-latest.md if [ ! -f $REVIEW_FILE ]; then echo ⚠️ 步骤 4 失败:没有审查报告(需要先跑 /review) 2 FAIL1 elif ! grep -qE ^## (Security|Style|Test) $REVIEW_FILE; then echo ⚠️ 步骤 4 失败:审查报告缺段(Security / Style / Test 必填) 2 FAIL1 fi fi if [ $FAIL -eq 1 ]; then echo 2 echo Stop 门控未通过,请修复后再次停止 2 exit 2 fi exit 0 第 18 讲配套SubAgentStop 验收 报告自动汇总实现读子代理输出 / 写状态文件 / 通知主对话#!/usr/bin/env bash # .claude/hooks/subagent-accept.sh # 子代理完成后的验收 报告自动汇总 set -e INPUT$(cat) SUBAGENT_NAME$(echo $INPUT | jq -r .subagent_name // unknown) SUBAGENT_OUTPUT$(echo $INPUT | jq -r .subagent_output // ) TIMESTAMP$(date %Y-%m-%d_%H-%M-%S) # 验收 1:报告完整性(代码审查 SubAgent 必须有 3 段) if [ $SUBAGENT_NAME code-reviewer ]; then if ! echo $SUBAGENT_OUTPUT | grep -qE ^## Security; then echo ⚠️ 验收 1 失败:code-reviewer 报告缺 ## Security 段 2 exit 2 fi if ! echo $SUBAGENT_OUTPUT | grep -qE ^## Style; then echo ⚠️ 验收 1 失败:code-reviewer 报告缺 ## Style 段 2 exit 2 fi if ! echo $SUBAGENT_OUTPUT | grep -qE ^## Test; then echo ⚠️ 验收 1 失败:code-reviewer 报告缺 ## Test 段 2 exit 2 fi fi # 验收 2:状态文件(子代理必须写状态文件) STATE_FILE.claude/state/${SUBAGENT_NAME}.json if [ ! -f $STATE_FILE ]; then echo ⚠️ 验收 2 失败:${SUBAGENT_NAME} 没写状态文件 $STATE_FILE 2 exit 2 fi # 验收 3:输出格式(必须有 ## 标题) if ! echo $SUBAGENT_OUTPUT | grep -qE ^## ; then echo ⚠️ 验收 3 失败:子代理输出缺 ## 标题(Markdown 结构) 2 exit 2 fi # 验收通过:汇总报告到主对话 REPORT_DIR.claude/state/subagent-reports mkdir -p $REPORT_DIR REPORT_FILE$REPORT_DIR/${SUBAGENT_NAME}-${TIMESTAMP}.md cat $REPORT_FILE EOF # SubAgent Report: $SUBAGENT_NAME # Timestamp: $TIMESTAMP # State File: $STATE_FILE $SUBAGENT_OUTPUT EOF # 通知主对话(写到 .claude/state/notifications.log) echo [$(date %Y-%m-%d %H:%M:%S)] SubAgent $SUBAGENT_NAME 完成,报告已汇总到 $REPORT_FILE \ .claude/state/notifications.log exit 0 第 18 讲配套6 个 Hook 完整防御链配置.claude/settings.json 完整版// .claude/settings.json(完整 6 个 Hook 防御链) { hooks: { PreToolUse: [ { matcher: Bash, hooks: [ {type: command, command: bash /home/user/.claude/hooks/deny-pipe-exec.sh}, {type: command, command: bash /home/user/.claude/hooks/deny-extra-dangerous.sh} ] }, { matcher: Edit|Write, hooks: [ {type: command, command: bash /home/user/.claude/hooks/deny-edit-lockfile.sh} ] } ], PostToolUse: [ { matcher: Edit|Write, hooks: [ {type: command, command: bash /home/user/.claude/hooks/auto-format.sh}, {type: command, command: bash /home/user/.claude/hooks/audit-log.sh} ] } ], Stop: [ { matcher: *, hooks: [ {type: command, command: bash /home/user/.claude/hooks/stop-gate.sh}, {type: command, command: bash /home/user/.claude/hooks/check-tests.sh} ] } ], SubAgentStop: [ { matcher: *, hooks: [ {type: command, command: bash /home/user/.claude/hooks/subagent-accept.sh} ] } ] } } // 6 个 Hook 串成的防御链: // PreToolUse deny-pipe-exec → 拦截 curl | sh // PreToolUse deny-extra-dangerous → 拦截 rm -rf / chmod 777 / dd // PreToolUse deny-edit-lockfile → 拦截改 lockfile // PostToolUse auto-format → 写完代码自动 ruff format // PostToolUse audit-log → 记录所有 Bash 命令 // Stop stop-gate → 4 步质量门控 // Stop check-tests → 测试通过检查 // SubAgentStop subagent-accept → 子代理验收 报告汇总 第 18 讲配套三维决策框架的实操清单性能 / 必要性 / 用户体验 3 维各 4 个问题# Hook 三维决策框架实操清单 # 维度 1:性能(Hook 脚本耗时) □ 1. Hook 脚本 1 秒吗?(用 time bash hook.sh 测) □ 2. Hook 是否跑网络请求?(curl / wget 会慢,加缓存) □ 3. Hook 是否跑完整测试套件?(pytest 全套 1-2 分钟,改用 Stop 或 subset) □ 4. Hook 是否用 python -c 复杂逻辑?(启动开销 0.5s,改用 bash grep) # 维度 2:必要性(是否真的需要拦截) □ 1. 拦截的命令 / 操作真发生过多起吗?(没有 不配) □ 2. 拦截后能避免实际发生过的真实问题吗?(发生过 配;纯理论 不配) □ 3. 团队有更轻的方案替代吗?(比如 GitHub 分支保护比 Hook 拦截更合适) □ 4. 拦截的频率和价值匹配吗?(高频高价值 配;低频低价值 不配) # 维度 3:用户体验(不要频繁打断) □ 1. 这个 Hook 每天阻断 5 次吗?( 5 次调规则) □ 2. 阻断时 stderr 输出的信息用户能看懂吗?(看不懂 补) □ 3. Hook 是否会误拦合法操作?( 5% 误拦 调规则) □ 4. Hook 是否会循环阻断?(改文件 → 改回来 → 再改,改用 PostToolUse auto-format) # 评分规则 # 性能: 1 秒 通过,1-3 秒 警告, 3 秒 失败 # 必要性:真实问题发生过 通过,理论可能 警告,纯理论 失败 # UX: 5 次/天 通过,5-10 次/天 警告, 10 次/天 失败 # 决策结果 # 3 维全通过 应该配 # 有 1 维警告 谨慎配,记录原因 # 任 1 维失败 不配 # 示例 # Hook: PreToolUse 拦 rm -rf # 性能:grep 匹配 0.1 秒 ✅ 通过 # 必要性:误删事件发生过 3 次 ✅ 通过 # UX:每月阻断 1-2 次 ✅ 通过 # 决策:应该配 # Hook: Stop 强制跑完整 pytest # 性能:pytest 完整 1-2 分钟 ❌ 失败 # 决策:不配(或改用 subset 测试) # Hook: PreToolUse 拦所有 rm 命令 # 性能:grep 匹配 0.1 秒 ✅ 通过 # 必要性:误删 /tmp/test 发生过 0 次 ❌ 失败 # 决策:不配(或只拦 rm -rf)⚠️ 常见坑⚠️ Stop Hook 配太多每步都强制 Claude 继续、反而拖慢任务完成“门控过多的反作用Stop Hook 配 5-6 个、每个都强制 Claude 继续、结果 Claude 任务完成后被反复阻断、体验很差。修正Stop Hook 控制在 2-3 个关键门控未提交 测试通过 文档同步非关键不配。其他质量检查移到 PreToolUse / PostToolUse。判断标准Stop Hook 3 个 太多、精简。⚠️ SubAgentStop 没配置子代理跑完报告没汇总、主对话不知道结果“子代理静默完成陷阱用 SubAgent 跑代码审查第 6 讲 code-reviewer)、完成后主对话只看到子代理任务完成信号、不知道审查结果是什么。需要用户主动 /ask 子代理汇报结果”、或者主对话自己再读子代理输出——延迟高、容易遗漏。修正配 SubAgentStop Hook子代理-accept.sh做自动验收 报告汇总到 .claude/state/subagent-reports/”、主对话可以直接用。判断标准你的 SubAgentStop Hook 配置了吗?没有、补配。⚠️ frontmatter matcher 写错“Edit漏写Write”,Write 不触发matcher 漏写陷阱配置 PostToolUse auto-format 时、matcher 写 “Edit”漏写 Write)、结果 Claude 用 Write 改文件时、自动格式化不触发。修正涉及修改文件的 Hook 统一写 “Edit|Write”用 | 分隔多个工具名。判断标准你的 matcher 字段覆盖了所有相关工具吗?grep “Edit|Write” 检查。⚠️ Hook 配置后没监控执行次数 / 拦截次数 / 性能没度量、无法迭代优化“配了不看的优化盲区Hook 配了之后、不知道每天触发多少次 / 拦截多少次 / 每次耗时多少”、无法判断 Hook 是否真的有用 / 是否误拦太多 / 是否拖慢速度。修正Hook 自带监控——audit-log 记录所有 Bash 命令、stop-gate 记录门控阻断次数、subagent-accept 记录子代理验收结果。每周看一次统计、调整规则。判断标准你最近一次看 Hook 执行统计是什么时候?超过 1 个月 落后了、补监控。 一句话备忘Hooks 高级模式是从会用走向精通——Stop Hook 4 步门控强制质量、SubAgentStop 自动验收汇总、frontmatter 精准配置避免漏触发、三维决策框架判断该配不该配6 个 Hook 串成完整防御链、5 条最佳实践沉淀团队资产。← 回到 本讲网页顶部