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 支持管道符组合：

"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 官方文档

code.claude.com/docs/en/hoo...

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

Claude 官方 Blog

claude.com/blog/how-to...

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

awesome-claude-code

github.com/hesreallyhi...

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

---

最后

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

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

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

人会忘，Hook 不会。

---

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

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

应部分读者呼声，作者组建了 AI 编程交流群，感兴趣的朋友请扫码加入，一起交流学习～

如果二维码过期，请添加作者微信并备注"AI编程交流群"，作者会拉你进群。