先给一个判断:Claude Code 的 hooks 是合同,prompt 只是建议。你在 prompt 里写「记得跑测试」,模型可以忘;你在 hooks 里挂一条 PostToolUse 跑测试,它每次写完文件都会执行,模型绕不过去。这就是区别。这篇讲清八种 hook 事件怎么用,以及 slash command 怎么把重复流程固化下来。

我把官方文档打开核了 1 遍,这八种事件覆盖了会话的整个生命周期。PreToolUse 在工具执行前触发,PostToolUse 在工具成功后触发,PermissionRequest 在弹权限框前触发,SessionStart 在会话开始时,Stop 在模型答完,SubagentStop 在子代理结束,UserPromptSubmit 在你提交 prompt 时,还有 PreCompact 在上下文压缩前。每个事件的时机不同,选错事件等于白挂。

退出码是唯一的硬拦截

hooks 跟模型的沟通就靠两样东西:stdin 收事件 JSON,退出码和 stdout 表态。我核了 1 遍这个机制:退出码 0 是放行,stdout 若是一段 JSON 会被应用;退出码 2 是拦截,stderr 就是给模型看的理由。其它退出码是非阻塞错误,工具照常跑。这条记牢,很多人以为脚本报错就等于拦截,其实不是。

PreToolUse 是最常用的。它在模型选中工具之后、真正执行之前触发,你的脚本能批准、能拦、能要求确认、能改参数。matcher 字段按工具名做子串匹配,写 "Bash" 就只拦 shell,写 "Edit|Write" 就只拦文件写入。

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "scripts/secret-guard.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "scripts/format.sh" }] }
    ]
  }
}

这段配置是我自己写的,挂在 .claude/settings.json 里。它的分工很明确:PreToolUse 在命令执行前拦下危险操作,比如 git push 时扫 staged diff 里有没有 API key;PostToolUse 在文件写完之后自动跑格式化。一个防在前面,一个收在后面。

一个拦截脚本长这样

拦截脚本从 stdin 读 JSON,用 jq 取命令,命中规则就 exit 2。我写了一个防泄密的最小版本:

#!/bin/bash
# scripts/secret-guard.sh —— 读 stdin 的命令,拦下带 API key 的 push
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
if echo "$COMMAND" | grep -q 'git push'; then
  if git diff --cached | grep -E 'sk-[A-Za-z0-9]{20,}' >/dev/null 2>&1; then
    echo '{"decision":"block","reason":"staged diff 里检出 API key"}' 
    exit 2
  fi
fi
exit 0

这段的思路来自我核过的几篇实践,代码是我重写的。它解决的事很实在:团队里总有人手滑把 key 提交上去,PreToolUse 挂在 push 前面,就挡在了事故发生之前。这是 hook 比 prompt 强的地方。

不止 shell,还有 prompt 和 agent 两类

hook 的类型不止 command。我核了 1 遍官方文档,还有三种:prompt 型不跑 shell,把事件数据和你的提示词一起丢给一个模型,让它回 {"ok": true} 或 {"ok": false, "reason": "..."};agent 型起一个子代理去读文件、查代码再决定,默认 60 秒超时、最多 50 次工具调用;还有 http 型,把事件 JSON POST 到你的端点,适合全公司统一策略。

我的判断是:能写成确定规则的用 command,需要判断力的才上 prompt 或 agent。command 便宜又快,prompt 每次要一次模型调用。别为了「聪明」把每条 hook 都换成模型。这条记牢。

slash command 管的是「人决定跑什么」

hooks 是自动的,slash command 是手动的。我核了 1 遍官方文档,自定义 slash command 放在 .claude/commands/ 目录,一个 markdown 文件一个命令。你输入 /test,Claude Code 就执行对应文件里的指令。它适合「人想跑的时候才跑」的流程,跟 hook 的「自动跑」正好互补。

跑完整测试套件,先跑单元测试,再跑集成测试,最后把失败的用例列出来。

这段是我自己写的。它解决的事很具体:一个团队约定好的「跑测试」动作,写成 slash command,新同事打 /test 就行,不用每次解释一遍该跑哪些命令。

我建议这样分工:hook 管每次编辑都会触发的自动检查,slash command 管按需执行的完整流程。比如格式化、防泄密放 hook,跑整套测试、发 PR 放 slash command。别把两者混起来,混起来你就分不清哪件事该在什么时候发生。这个判断我坚持。

怎么落,给个结论

落地上我给了硬分界。团队要共享同一套护栏,就写在 .claude/settings.json 提交进 Git,全组同一份规则;个人偏好写在 .claude/settings.local.json,它会被 gitignore。调试时在会话里跑 /hooks 看当前合并后的清单,disableAllHooks 可以整体关掉。我在本机的 ~/.claude/settings.json 里确实有配置,不过那是接模型用的,不是 hook。

一句结论。hooks 管「每次必须执行的约束」,slash command 管「人主动发起的流程」。两样都接上,重复操作才真正省掉,而不是写在 README 里让同事自觉。