指令管不住的AI，四个钩子能管住吗？

大多数团队调教 Claude Code，靠的是一份 CLAUDE.md：写上"跑一下格式化""别动锁文件""用我们的日志库"。多数时候管用。但指令只是模型选择去遵守的东西，长会话跑下来，或者赶上忙的一天，它有时就不遵守了。

钩子（hooks）补的就是这个缺口。钩子是一条 shell 命令，Claude Code 会在固定节点自动执行，比如每次文件编辑之后、每条命令执行之前。它每次都跑，不管模型还记不记得那条规则。

对团队来说，这改变的是你能承诺什么。"智能体应该格式化它的代码"，变成"智能体的代码永远是格式化过的"。

团队钩子放在哪

钩子和权限放在同一批设置文件里。对团队而言，关键的是仓库里的 .claude/settings.json，像其他配置一样提交进版本库，谁克隆了仓库，谁就拿到同一套钩子。

个人钩子放在 ~/.claude/settings.json，或者不提交的 .claude/settings.local.json。组织也可以通过托管设置集中下发钩子。

每个钩子的结构都一样：一个事件、一个可选匹配器（用来收窄适用的工具范围）、以及要执行的命令。

1. 格式化智能体编辑的每个文件

最简单的钩子，也是最能消掉评审噪音的一个。它在每次编辑后跑你的格式化工具，格式化从此不再出现在代码评审里。

官方文档给的例子用的是 Prettier：PostToolUse 事件在工具执行后触发，Edit|Write 匹配器把它限定在文件编辑上。钩子通过标准输入收到工具调用的 JSON 详情，jq 从里面读出文件路径。Prettier 可以换成团队在用的任何工具：ruff format、gofmt、rustfmt。

2. 保护不该被手改的文件

锁文件、生成代码、.env 文件、.git/ 目录里的东西，都不该由智能体来编辑。PreToolUse 钩子在工具执行前运行，脚本以退出码 2 结束时，Claude Code 会拦下这个动作。脚本写到标准错误里的消息会回传给 Claude，让它调整做法，而不是单纯失败。

把脚本存成 .claude/hooks/protect-files.sh 并赋予可执行权限，脚本里维护一份受保护模式清单（.env、package-lock.json、.git/），命中就输出提示并以退出码 2 结束。然后在设置里注册它，命令指向 "$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh。

因为脚本就提交在 .claude/hooks/ 里，受保护文件清单会像其他代码一样走拉取请求评审。

3. 用自己的逻辑检查高风险 shell 命令

设置里的权限规则能按模式拒绝命令，但它匹配的是命令文本，而同一条命令可以有很多种写法。在 Bash 工具上挂一个 PreToolUse 钩子，就能在命令执行前用真正的逻辑检查完整命令：拦掉构建目录之外的 rm -rf、阻止推送到主分支、拒绝任何触碰生产配置的操作。

机制和文件守卫一样：匹配 Bash，从 JSON 输入里读 .tool_input.command，以退出码 2 加一条理由来拦截。退出码 0 表示钩子没有异议，是否执行仍由常规权限规则决定。

有一点要提醒：检查命令文本的钩子是一道强护栏，不是安全边界。对于无论命令怎么写都必须成立的限制，要配合 Claude Code 的沙箱和访问控制一起用——机器上没有生产环境凭据，智能体就碰不到生产环境。

4. 压缩之后恢复关键上下文

会话的上下文塞满时，Claude Code 会做压缩：把对话总结一遍腾出空间。细节可能在总结里丢掉，包括你一小时前说过的规则。

带 compact 匹配器的 SessionStart 钩子在压缩后立即运行，命令打印出来的内容会被加进 Claude 的上下文。文档示例打印的是一句提醒：用 Bun 而不是 npm，提交前跑 bun test，当前冲刺是认证重构。

把 echo 换成能输出动态内容的命令，比如 git log --oneline -5 拿最近几次提交。始终成立的规则留在 CLAUDE.md 里，这个钩子只放长会话之后最要紧的那几条提醒。

要小心的一个钩子：Stop

给 Stop 钩子挂上测试套件、让 Claude 一直干到测试通过，这个想法很诱人。先知道两件事。Stop 在 Claude 每次结束回复时都会触发，不只是任务完成时，所以慢的测试套件会被反复执行。另外，Stop 钩子连续拦截八次后，Claude Code 会覆盖它，所以脚本应该读取输入里的 stop_hook_active 字段，为 true 时提前退出。

对多数团队来说，在 CI 和拉取请求检查里跑测试更简单。

在团队里推行钩子

• 从格式化钩子开始。风险低，第一个拉取请求就能看到好处。
• 接着加文件守卫，清单先短一点。有人发现智能体碰了不该碰的文件，再往里加。
• 脚本提交到 .claude/hooks/，在 .claude/settings.json 里注册，改动就能走评审。
• 确认每个人都装了钩子调用的工具（jq、格式化工具）。多数事件下，钩子找不到自己的命令会以非阻塞错误失败，规则就悄悄失效了。
• 钩子看起来没跑，用 claude --debug，它会记录每个钩子的执行情况。

指令和钩子各管一段

钩子管的是必须永远成立的规则。其余的东西，比如代码库怎么组织、遵循哪些模式、谁负责哪块，属于智能体每次会话开始时读到的指令。

这也是 AI Workspace Builder 的出发点：上传团队已有的文档，它用你自己的 Anthropic API 密钥，在 15 到 30 秒内生成 CLAUDE.md、每个角色的配置文件和安装脚本。有一个免费试用工作区，不需要绑卡。免费模板里包含一份共享设置文件，可以把这些钩子加进去。