Claude Code 指南第 6 章进阶

Hooks 与自动化在它动手前后,自动跑该跑的事

Hooks 是在工具调用前后自动执行的脚本:改完文件自动格式化、碰到危险操作直接拦下、测试不过不许收尾。它把「每次都要提醒的事」变成不需要提醒。

更新于 2026年10月17日 · 依据 Claude Code 2.1.301 官方文档核对 · AGI Dawn 编辑部 · 审定 kk

全部章节
本页

先说结论

  • 把「每次都要说」的规矩写成 Hook:改完文件自动跑格式化和 lint,比在 CLAUDE.md 里写一百遍「记得格式化」可靠。
  • 用 PreToolUse 拦下你不想它碰的东西:改 .env、rm -rf、强推。规则写在脚本里,不靠它记住。
  • 配合 权限模式:权限决定它能不能不问就做,Hooks 决定做之前先过什么关、做完之后自动补什么。

Hooks 是什么

Claude Code 在几个固定时刻调用你配置的 shell 命令,并把当时的上下文(要调用哪个工具、参数是什么)以 JSON 通过标准输入传给它。命令退出码为 0 表示放行;为 2 表示阻止,并把你写到标准错误的内容交给模型看。常用的时刻:

时刻触发点典型用途
PreToolUse工具调用前拦截危险命令,检查要改的文件是否在允许范围内
PostToolUse工具调用后格式化刚改的文件,跑 lint 或受影响的测试
UserPromptSubmit你发出消息时自动附加上下文,比如当前分支、未提交的改动
Stop它准备结束本轮回复时检查测试是否通过,不达标就让它继续
Notification需要你注意时桌面通知、响铃

配置写在 .claude/settings.json(项目级,可以提交)或 ~/.claude/settings.json(个人级)。会话里输入 /hooks 可以查看已加载的 Hook 及其来源(只读),改配置要编辑上面这两个文件。

例一:改完就格式化

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write --ignore-unknown \"$(jq -r .tool_input.file_path)\""
          }
        ]
      }
    ]
  }
}

matcher 匹配工具名。每次 Edit 或 Write 之后,取出被改文件的路径交给 prettier,它写出来的代码永远是格式化过的;--ignore-unknown 让 prettier 跳过它不认识的文件类型,而不是报错。同样的位置可以接 eslint、gofmt、ruff。

例二:拦下不该碰的

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard.sh" }]
      }
    ]
  }
}

脚本放在项目的 .claude/hooks/ 下并提交进仓库,同事拉下代码护栏就生效;$CLAUDE_PROJECT_DIR 指向项目根目录。guard.sh 读出要执行的命令,命中规则就以退出码 2 结束:

bash
#!/usr/bin/env bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|> \.env'; then
  echo "这条命令被项目规则拦下了:$cmd。需要的话请人工执行。" >&2
  exit 2
fi
exit 0

模型会收到这段提示,通常会换一种做法或者来问你。和权限规则的区别:deny 规则按命令模式匹配;Hook 可以写任意复杂的判断,比如只在某个分支上禁止、只拦某些目录。

例三:测试不过不许收尾

json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-tests.sh" }]
      }
    ]
  }
}
bash
#!/usr/bin/env bash
# 已经因为本 Hook 继续过一次,就放行,避免在修不好的测试上反复打转
if [ "$(jq -r '.stop_hook_active')" = "true" ]; then exit 0; fi
if ! npm test --silent >/dev/null 2>&1; then
  echo "测试未通过,请修复后再结束。如果确实修不好,说明原因交给人处理。" >&2
  exit 2
fi
exit 0

它每次准备收尾时先跑测试,红了就回去继续修。Claude Code 传给 Stop Hook 的输入里带有 stop_hook_active,表示这一轮已经被 Hook 要求继续过;据此放行,就不会无限循环。对「改完就说做好了」这类问题,这一招比任何提示词都管用。

怎么写一个靠谱的 Hook

  • 快:Hook 在工具调用时同步执行,一个两秒的脚本会拖慢整次会话。格式化单个文件可以放在 PostToolUse,全量测试放在 Stop。
  • 只管一件事:一个 Hook 一个目的,方便开关和排错。
  • 失败要说人话:退出码 2 时写到标准错误的内容会原样交给模型,写清楚为什么、该怎么办。
  • 先在终端手工跑:用一段示例 JSON 喂给脚本,确认行为后再挂上去。
  • 提交进仓库:项目级 Hooks 和 CLAUDE.md 一样是团队资产。

常见问题

Hook 和 CLAUDE.md 里的规则重复了怎么办?

能用 Hook 强制的,就不要写进 CLAUDE.md;文档只写需要判断的事。

Hook 会不会被绕过?

PreToolUse 在工具层执行,模型跳不过去;但它可能换一个等价命令达到同样效果,所以规则要按意图写,别只匹配字面。

能用其它语言写吗?

能。任何可执行文件都行,只要读标准输入、按约定返回退出码。