Hooks 事件

这一课你将能做到

1. 说出 PreToolUse / PostToolUse / UserPromptSubmit / Stop 等核心事件的触发时机与用途
2. 在 settings.json 中配置带 matcher 的 Hook，实现「编辑后自动格式化」「危险命令硬拦截」
3. 遵守退出码协议（0 放行 / 2 阻止）编写跨平台的检查脚本，并用 /hooks 验证加载

为什么要学

CLAUDE.md 是「拜托它记住」，Hooks 是「制度上必须」。模型有概率忘记规范，但 Hook 是外挂的 shell 脚本，100% 确定：编辑器保存后自动跑格式化，就算模型忘了也给你补上；它想执行 rm -rf，PreToolUse 直接把工具调用掐断。官方定位很明确——凡是「必须发生 / 必须不发生」的规则，都该用 Hooks 落地而不是靠提示词。这是把 Claude Code 接入工程化团队的关键一环，也是面试里区分「用过」和「用透」的考点。

人话：Hooks 是给 agent 装的门禁和流水线质检仪。它每做一个动作（跑命令、改文件），先过你设的卡口；卡口放行才继续，卡口喊停它就得停下听原因。

先建立图像

一次 Edit 操作的完整过卡流程：

Claude 决定调用 Edit(order.java)
      ↓
PreToolUse (matcher: Edit)     ← 执行前：可拦截、可放行
      ↓ 放行
Edit 真正执行，文件被修改
      ↓
PostToolUse (matcher: Edit)    ← 执行后：可格式化、可提醒
      ↓
Claude 看到工具结果，继续思考

其他事件：
UserPromptSubmit ← 你提交输入时（可注入上下文/拦截）
Stop             ← Claude 完成回答时（可触发通知/收尾检查）
PreCompact       ← 上下文压缩前
SessionStart/End ← 会话开始/结束

配置结构：

{
  "hooks": {
    "事件名": [
      { "matcher": "工具名1|工具名2",
        "hooks": [ { "type": "command", "command": "你的脚本" } ] }
    ]
  }
}

跟着做

步骤 1：用 /hooks 认识配置入口

/hooks

交互菜单按事件分组展示当前配置，也能安全地新增（改完需确认，防恶意配置注入）。先只读一遍，理解「事件 → matcher → 命令」三层结构。

步骤 2：实现「编辑后自动格式化」（PostToolUse）

编辑 .claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null || true" }
        ]
      }
    ]
  }
}

此后每次 Claude 保存文件，prettier 自动跟进。脚本通过 stdin 收到 JSON（含 tool_name、tool_input 等），文件路径也可从 $CLAUDE_FILE_PATHS 读取。

步骤 3：实现「危险命令硬拦截」（PreToolUse）

写一个跨平台检查脚本 scripts/guard.sh：

#!/bin/bash
input=$(cat)                     # 从 stdin 读取 JSON
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
if echo "$cmd" | grep -qE 'rm -rf|git push --force|drop database'; then
  echo "拦截：包含高危命令 [$cmd]" >&2   # stderr 在 exit 2 时反馈给模型
  exit 2                                # 非零且为 2：阻止本次工具调用
fi
exit 0                                  # 放行