让 Claude”记得每次改完都跑 lint”,靠提示词总有忘的一天。Hooks 把这类要求从”请求”升级成”机制”:在固定生命周期事件上,Claude Code 自动执行你指定的本地命令,不经模型自由发挥——该拦的拦、该跑的跑。这篇用三个实战钩子讲清配置结构与退出码语义。
解决什么问题
三类典型需求,提示词都靠不住:
- 必须执行:改完 .py 自动 lint、改完前端文件自动格式化——模型会忘,钩子不会;
- 必须拦截:
git push --force、删库删目录这类危险命令——与其事后补救,不如在工具调用前拦下; - 必须注入:会话开始时把分支名、环境信息带进上下文——靠模型自己跑
git branch就慢一步。
共同点是”100% 发生”。钩子是 Claude Code 进程在事件点直接启动的本地命令,模型插不上手,这才靠得住。
环境与版本
- Claude Code 已安装,实测版本【待补:claude —version 输出】。
- 钩子配置写在 settings.json,三个层级:
~/.claude/settings.json(用户全局)、.claude/settings.json(项目,随 git 共享)、.claude/settings.local.json(项目个人,进 .gitignore)。 - 生命周期事件共 9 个:
| 事件 | 触发时机 | 典型用途 |
|---|---|---|
| PreToolUse | 工具调用前 | 拦截危险命令 |
| PostToolUse | 工具调用后 | 自动格式化、lint |
| UserPromptSubmit | 用户提交提示词后 | 注入上下文、输入过滤 |
| Notification | 发通知时 | 桌面提醒 |
| Stop | 主代理响应结束 | 完成提醒 |
| SubagentStop | 子代理结束 | 子任务完成提醒 |
| PreCompact | 上下文压缩前 | 压缩前备份 |
| SessionStart | 会话启动 | 注入环境信息 |
| SessionEnd | 会话结束 | 清理、日志 |
- 每个钩子默认超时 60 秒,可在配置里用
timeout字段覆盖。 - 脚本语言随意,本文用 Python 3.8 语法,bash 同理。
分步骤:三个实战钩子
步骤 1:PostToolUse——Python 文件改完自动 lint
.claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{ "type": "command", "command": "python3 .claude/hooks/lint_py.py" }
]
}
]
}
}
脚本从 stdin 读事件 JSON,拿到刚被改的文件路径:
#!/usr/bin/env python3
"""PostToolUse: 对刚写入/编辑的 .py 文件执行 ruff。"""
import json, sys, subprocess
data = json.load(sys.stdin)
path = (data.get("tool_input") or {}).get("file_path", "")
if path.endswith(".py"):
r = subprocess.run(
["ruff", "check", "--fix", path],
capture_output=True, text=True,
)
if r.returncode != 0:
# 自动修复失败的问题:stderr + 退出码 2,把失败原因喂回给模型
print(r.stdout + r.stderr, file=sys.stderr)
sys.exit(2)
sys.exit(0)
要点两条:PostToolUse 事件的 stdin JSON 里,tool_input.file_path 是刚被操作的目标文件;退出码 0 表示正常放行,退出码 2 会把 stderr 反馈给模型——正好把 lint 失败塞回给它自己修。若只想格式化、不想打扰模型,把失败也按 exit 0 处理即可,stdout 会留在转录记录里备查。除了退出码,钩子还可以向 stdout 输出 JSON 做更细的控制,例如 PreToolUse 返回 {"decision": "block", "reason": "原因"},与 exit 2 同效但文案可控。
另外算一笔账:钩子是本地进程,不消耗 token——“让模型每次自己跑 lint”则要把命令输出读进上下文再处理一遍。护栏类逻辑放进钩子,既是可靠性问题,也是成本问题。
步骤 2:PreToolUse——拦下 force push
脚本 .claude/hooks/block_force_push.py:
#!/usr/bin/env python3
"""PreToolUse: 阻断 git push --force。"""
import json, sys
data = json.load(sys.stdin)
cmd = (data.get("tool_input") or {}).get("command", "")
if "push --force" in cmd or "push -f " in cmd:
print("禁止 force push:先用 git pull --rebase 解决分叉;确有必要请人工执行。",
file=sys.stderr)
sys.exit(2) # 阻断,stderr 会反馈给模型,让它换方案
sys.exit(0)
配置结构同上,把事件名换成 PreToolUse、matcher 换成 Bash。退出码语义必须记牢:
- 0:放行,一切正常;
- 2:阻断,stderr 内容反馈给模型,让它调整方案;
- 其他非零:仅算非阻断错误,命令照常执行,stderr 只展示给人看。
步骤 3:SessionStart——开会话自动注入环境信息
#!/usr/bin/env python3
"""SessionStart: 把仓库关键信息注入会话上下文。"""
import subprocess, sys
branch = subprocess.run(
["git", "rev-parse", "--abbrev-ref", "HEAD"],
capture_output=True, text=True,
).stdout.strip()
# SessionStart 的 stdout 会进入上下文,模型开场就能看到
print(f"当前分支:{branch}。提交前先跑 pytest -x -q tests/。")
sys.exit(0)
配置里事件名换成 SessionStart,不需要 matcher——matcher 只对按工具名触发的 PreToolUse/PostToolUse 有意义。
步骤 4:核对与排查
会话内输入 /hooks 打开钩子管理界面,确认配置被识别、matcher 拼写无误。配置里的命令路径建议用 $CLAUDE_PROJECT_DIR 前缀(Claude Code 执行钩子时会注入该环境变量),例如 python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/lint_py.py",换个目录启动也不会找不到脚本。
钩子不工作时的排查顺序:先在 /hooks 里看配置识别了没有;再把事件 JSON 手动喂给脚本单独跑:
echo '{"hook_event_name":"PostToolUse","tool_input":{"file_path":"app/main.py"}}' | python3 .claude/hooks/lint_py.py
单跑没问题还不触发,就用 claude --debug 启动会话,实时看钩子执行日志。
常见坑
坑一:改了 settings.json 当场没生效。 钩子配置在会话启动时被快照,会话中途直接改文件行为可能不变——改完重启会话,或在 /hooks 菜单里审查确认【待补:当前版本对运行中会话配置变更的实际处理】。团队共享的钩子进 .claude/settings.json 并提交 git,同事 pull 下来即用。
坑二:退出码用反。 想阻断却写了 sys.exit(1)——1 只是非阻断错误,命令照常执行,模型最多看到一条报错。要拦必须 exit 2。
坑三:matcher 匹配不上。 matcher 是对工具名做的正则匹配,注意大小写,多工具用 | 连接(Write|Edit)。写成小写 write,钩子永远不触发,表现为”时灵时不灵”的错觉。
坑四:Windows 下 command 直接写 shell 语法。 跨平台钩子统一 python3 脚本.py,把逻辑收进脚本里,绕开各 shell 的语法差异。
最终效果
改任何 .py 文件,lint 自动执行,修不掉的问题直接回到模型手里让它修;任何 force push 尝试,当场被拦并给出替代方案;新会话一打开,分支与规矩已在上下文里。整个过程不消耗注意力,也不会忘。钩子把”团队规范”从口头约定升级为进程级强制:CLAUDE.md 负责告诉模型规矩,hooks 保证规矩一定被执行【待补:PostToolUse 从工具结束到脚本跑完的耗时实测】。

相关阅读
- 规矩写在哪:CLAUDE.md 怎么写:项目记忆配置实践。
- 钩子配置文件与斜杠命令速查:Claude Code 常用命令速查:日常高频用法。
- Claude Code 安装教程。
- 子任务完成提醒离不开它:Claude Code 子代理:任务拆分与并行实战。