Hooks 与自动化在它动手前后,自动跑该跑的事
Hooks 是在工具调用前后自动执行的脚本:改完文件自动格式化、碰到危险操作直接拦下、测试不过不许收尾。它把「每次都要提醒的事」变成不需要提醒。
全部章节
本页
先说结论
- 把「每次都要说」的规矩写成 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 及其来源(只读),改配置要编辑上面这两个文件。
例一:改完就格式化
{
"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。
例二:拦下不该碰的
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard.sh" }]
}
]
}
}脚本放在项目的 .claude/hooks/ 下并提交进仓库,同事拉下代码护栏就生效;$CLAUDE_PROJECT_DIR 指向项目根目录。guard.sh 读出要执行的命令,命中规则就以退出码 2 结束:
#!/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 可以写任意复杂的判断,比如只在某个分支上禁止、只拦某些目录。
例三:测试不过不许收尾
{
"hooks": {
"Stop": [
{
"hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-tests.sh" }]
}
]
}
}#!/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 在工具层执行,模型跳不过去;但它可能换一个等价命令达到同样效果,所以规则要按意图写,别只匹配字面。
能用其它语言写吗?
能。任何可执行文件都行,只要读标准输入、按约定返回退出码。