Claude Code Hooks 用法详解：让 AI 编程智能体自动执行你的规则

Claude Code Hooks 用法：一句话讲清它解决什么问题

Claude Code Hooks 用法一句话概括：它是你在 settings.json 里注册的自定义 shell 命令，Claude Code 在生命周期的关键节点（写文件前、跑完命令后、会话结束时）自动执行，从而把「格式化、通知、拦截危险操作」这类规则变成确定性保障，而不是祈祷模型每次都记得。据 Anthropic 官方文档的说法，Hooks 的核心价值是「 deterministic control 」——某些动作一定会发生，不依赖 LLM 自觉。这和我们在 Claude Code 和 Cursor 区别里聊到的「工程化能力」一脉相承：终端智能体的可编程性，正是它和 IDE 型工具拉开差距的地方。

常用事件：PreToolUse 、 PostToolUse 、 Stop 、 UserPromptSubmit 各管一段

Claude Code 在会话的不同阶段触发不同事件，选对事件是写好 Hook 的第一步。最常用的四个如下：

• PreToolUse：工具执行前触发，可以审查甚至拦截这次调用，比如阻止 rm -rf 、保护 .env 文件不被读取或改写。
• PostToolUse：工具执行成功后触发，最适合做自动格式化、 lint 、记录变更日志。
• Stop：Claude 完成一轮响应时触发，常用来跑一遍测试、校验任务是否真的完成，或推送完成通知。
• UserPromptSubmit：你提交提示词后、 Claude 处理前触发，stdout 内容会注入上下文，适合自动附加项目约定、当前 git 分支等信息。

此外还有 SessionStart（会话启动注入环境）、 Notification（需要你确认时弹通知）、 PermissionRequest（自动批准重复性授权）等，完整列表可查官方 Hooks reference 。事件通过 stdin 收到一段 JSON（含 tool_name 、 tool_input 等字段），脚本用退出码反馈结果：0 表示放行，2 表示阻止并把 stderr 内容回传给 Claude 让它自行调整。

settings.json 配置示例：从格式化到拦截危险命令

配置写在 settings.json 的 hooks 字段下，结构是「事件名 → 数组 → matcher + 命令」。三个最实用的例子：

1. 编辑后自动格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

matcher 用 Edit|Write 限定只在编辑类工具调用后触发，不会在每次 Bash 调用后空跑。

2. 需要你确认时弹桌面通知

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Claude Code 需要你的输入\" with title \"Claude Code\"'" }
        ]
      }
    ]
  }
}

挂后台跑长任务时特别有用，Linux 换成 notify-send，Windows 用 PowerShell 弹窗即可。

3. 拦截危险命令（PreToolUse + 退出码 2）

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qE 'rm -rf|git push --force'; then
  echo "Blocked: 危险命令被拦截：$CMD" >&2
  exit 2
fi
exit 0

脚本里也可以直接展示这段短代码语法给同事参考，但注意方括号要转义写成 [jinyu_tip type="info]警示内容[/jinyu_tip] 的形式，否则会被解析掉——这是本站编辑器的一个小坑。

Claude Code Hooks 用法的配置步骤与踩坑提醒

进阶玩法是把 Hook 和 MCP 工具联动，比如用 matcher 匹配 mcp__github__.* 审计所有 GitHub 工具调用，MCP Server 的搭建可以参考我们的 MCP Server 自己搭建教程。如果要做「模型评审代码再决定放行」这类带判断力的规则，prompt 类型的 Hook 或结合多智能体编排（见 多智能体怎么编排）会更合适。

常见问题

把团队里反复口头强调的规矩下沉成一两条 Hook，是上手 Claude Code 之后性价比最高的工程化投资。