AI 编程工程化：Hook——AI 每次操作前后的自动检查站

上一篇我们讲了 Skill——给 AI 装上专业技能包

这篇讲 Hook，也是我觉得配置之后最有「踏实感」的一个东西。

说两件让我印象深刻的事

第一件。

AI 帮我改完一个模块，逻辑没问题，看起来挺好，我直接 commit 推上去了。

结果 CI 挂了。

原来几个文件改完没跑类型检查，导致 CI 的 build 出现几个 Error。每次手动补这一步，不是什么大事，但确实烦。

第二件更有意思。

有一次让 AI 整理项目里的临时文件。它跑了一段时间，然后告诉我：

「已清理无用文件，项目结构更整洁了。」

听起来挺好。但我根本不知道它删了什么，什么时候删的，也没任何提示让我确认。

后来查了 git 记录，那几个文件确实可以删，但当时真的出了一身冷汗。

两件事，一个根子：AI 干活，没有检查站。

改完代码没人盯着格式化。执行操作没人记录日志。你不知道它干了什么，也不知道该检查哪里。

配好 Hook，这两件事都不会再发生。

什么是 Hook

说白了，Hook 就是在 AI 调用工具前后，自动执行的一段 Shell 脚本。

你告诉 Claude Code：每次它写文件之后，跑一下 ESLint。每次它执行 Bash 命令之前，先记一条日志。

配好后，再也不用手动盯着了。

把它理解成机场的安检通道更直观。

旅客要登机，得先过安检。安检不是为了刁难你，是为了保证每个人都按规矩来。AI 每次写代码、执行命令，也需要这个机制——操作之前检查一遍，操作之后验证一遍。

Hook 就是这个检查站。

这里有个很关键的区别——Hook 和 Rule 不一样。

Rule 是写在 CLAUDE.md 里的说明，AI 会尽量遵守，但本质上是「建议」。有时候会被忘掉。

Hook 是代码。你配了，它每次都执行。没有例外。

Hook 有哪几个时机

Claude Code 的 Hook 支持 4 种主要触发时机：

PreToolUse — 工具调用之前

AI 准备动手，还没执行。

最适合做拦截。脚本返回退出码 2，Claude Code 取消这次操作，同时把脚本输出反馈给 AI，让它知道为什么被挡，重新调整方案。

PostToolUse — 工具调用之后

AI 刚完成一次操作。

格式化、跑测试、触发构建——都放这里。用得最多的时机。

Notification — Claude 等你的时候

Claude Code 需要你输入或确认时触发。

最常见用途：发一条桌面通知，不用一直盯着屏幕等。

Stop — AI 停下来的时候

AI 完成整个任务、响应结束时触发。

适合跑完整测试、写汇总日志、发「干完了」的通知。

5 个实际场景

① 写完代码自动格式化

最高频的用法。

AI 改了文件，格式对不对？有没有 warning？不配 Hook 就得手动检查。配上 PostToolUse，AI 每次写文件之后自动跑一遍 ESLint 和 StyleLint。

你拿到的永远是干净的代码。不用叮嘱，不用手动触发。

② 保护不能动的文件

.env 文件、密钥文件、package-lock.json——这些东西 AI 不应该碰。但没人明说，它不知道。

PreToolUse Hook 拦截对这些文件的写操作，脚本返回退出码 2，操作直接取消，AI 收到提示。再也不用担心它手滑。

③ 记录所有 Bash 命令

AI 执行的每一条命令，你能追溯吗？

用 PreToolUse 勾住 Bash 工具，把命令和时间戳写到日志文件里。出了问题翻日志，AI 的每一步都清清楚楚。就是开头说的「悄悄删文件」那种情况，有了日志就不用出冷汗了。

④ 长任务完成后发通知

跑一个大型重构，可能要好几十分钟。你不可能一直盯着屏幕。

配 Notification Hook，Claude 等你确认的时候弹系统通知。或者配 Stop Hook，AI 干完了停下来的时候提醒你。

去倒杯水，回来看结果。

⑤ 自动跑测试

AI 改完代码，测试跑了没有？

PostToolUse 或者 Stop Hook 里触发 pnpm test，失败了 AI 直接看到输出，接着修。不用你每次手动说「跑一下测试」。

怎么配置

方式一：用 `/hooks` 菜单

最简单。在 Claude Code 里输 /hooks，打开交互式菜单。

选触发时机 → 设置 matcher → 填写命令 → 选保存位置。全程图形化，不用手写 JSON。刚上手的时候推荐这个方式。

方式二：直接编辑配置文件

配置文件有三个位置：

文件路径	作用域
`~/.claude/settings.json`	全局，所有项目生效
`.claude/settings.json`	项目级，可提交 git，团队共享
`.claude/settings.local.json`	项目本地，gitignore，不共享

基本结构：

{
  "hooks": {
    "触发时机": [
      {
        "matcher": "匹配哪些工具",
        "hooks": [
          {
            "type": "command",
            "command": "要执行的 Shell 命令"
          }
        ]
      }
    ]
  }
}

matcher 支持管道符组合：

1
2
3

"Edit|Write"   —— 文件编辑操作
"Bash"         —— 执行命令
""             —— 空字符串，匹配所有工具

三个直接可用的配置

写完文件自动 Prettier（官方示例）

先装 jq（brew install jq），用来解析 Hook 接收到的 JSON 输入：

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

保护 .env 等敏感文件

先建一个脚本 .claude/hooks/protect-files.sh：

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "已阻止：$FILE_PATH 是受保护文件" >&2
    exit 2
  fi
done

然后在配置里引用：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

任务需要确认时发 macOS 桌面通知

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

注意事项

Hook 是同步的，别让它跑太慢。

AI 操作 → Hook 跑完 → AI 继续。Hook 卡了，整个流程就卡着。格式化、日志、通知这类轻操作没问题。真要跑完整测试套件，考虑放在 Stop 时机，或者后台异步（命令末尾加 &）。

PreToolUse 的拦截退出码是 2，不是其他非零值。

exit 2 才会让 Claude Code 取消操作并把原因反馈给 AI。其他非零值行为不一样，写拦截脚本的时候别搞混。

Hook 触发的操作不会再触发 Hook。

不用担心死循环：PostToolUse Hook 里写了文件，不会再触发一次 PostToolUse。官方处理好了。

个人配置和团队配置分开放。

桌面通知、个人日志，放 ~/.claude/settings.json 或 settings.local.json。格式化、保护文件这类团队都要用的，放 .claude/settings.json 并提交 git——大家拉项目就自动生效。

Hook 和 Rule 配合用，效果最好。

Rule 里定了「提交前必须通过 ESLint」，Hook 负责每次改完文件就自动执行这件事。规矩和执行，两手都要有。

去哪找参考配置

Hook 目前没有独立市场，但有几个好地方：

Claude Code 官方文档

https://code.claude.com/docs/en/hooks-guide

最全的来源。常用配置示例、字段说明、技术细节都在这里。建议精读一遍，半小时够了。

Claude 官方 Blog

https://claude.com/blog/how-to-configure-hooks

Anthropic 自己写的上手指南，从零开始配，步骤很清楚。

awesome-claude-code

https://github.com/hesreallyhim/awesome-claude-code

26,000+ Stars 的 Claude Code 资源合集，有专门的 Hook 配置分类。社区维护，质量有保证。

最后

Rule 让 AI 知道规矩。Command 封装你的操作流程。Skill 给 AI 装上专业能力。

Hook 做的是另一件事：让这些规矩在每次操作的时候真正被执行到。

AI 改完代码就格式化，碰敏感文件就拦截，任务完成就通知你——这些事不用叮嘱，配好就一直在。

人会忘，Hook 不会。

下一篇讲 Subagent：AI 学会拆任务之后，复杂项目可以怎么分工，效率能快多少。

欢迎感兴趣的朋友继续保持关注~

应部分读者呼声，作者组建了 AI 编程交流群，感兴趣的朋友请扫码加入，一起交流学习～
如果二维码过期，请添加作者微信并备注“AI 编程交流群”，作者会拉你进群。