让 Claude”记得每次改完都跑 lint”,靠提示词总有忘的一天。Hooks 把这类要求从”请求”升级成”机制”:在固定生命周期事件上,Claude Code 自动执行你指定的本地命令,不经模型自由发挥——该拦的拦、该跑的跑。这篇用三个实战钩子讲清配置结构与退出码语义。

解决什么问题

三类典型需求,提示词都靠不住:

  1. 必须执行:改完 .py 自动 lint、改完前端文件自动格式化——模型会忘,钩子不会;
  2. 必须拦截:git push --force、删库删目录这类危险命令——与其事后补救,不如在工具调用前拦下;
  3. 必须注入:会话开始时把分支名、环境信息带进上下文——靠模型自己跑 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 Code Hooks 事件流与拦截示意

相关阅读