Claude Code Hooks 该怎么用，用好了，事半功倍

Claude Code Hooks 该怎么用用好了事半功倍我一开始没太注意 Hooks。刚开始用 Claude Code注意力基本都在命令、subagent、skills 这些地方。Hooks 这个词很不起眼。后来用得多了才慢慢发现自己有一些场景改完文件我会想再跑一下格式化准备改.env、package-lock.json这种文件会下意识想先确认一下卡在权限确认那里时我又不想一直守着终端有时候一轮回复结束也会想让它再检查一遍不要太早停下来。Hooks 基本就是拿来处理这些事的。Claude Code 到了某些固定时机会把你提前挂上的动作跑一遍。这样很多原本要手动补的一步就不用反复做了。Hooks 是什么“Hook” 这个词其实不算新。很多人第一次接触它可能是在 React 里。像useEffect、useMemo、useRef这些 Hooks本质上都是在组件运行的某个时机把一段逻辑挂进去。别的地方也有类似的东西。比如 Git 里有pre-commit、pre-push你可以在提交前、推送前自动跑一些脚本。思路都差不多先约定一个时机再把动作挂上去。官方文档里的说法很简单Hooks 是在 Claude Code 生命周期特定节点自动执行的用户自定义命令。拆开看也就两层意思第一层你可以挑“什么时候触发”。比如会话开始时Claude 准备调用某个工具之前某个工具执行完成之后Claude 停止回复时Claude 发通知时工作目录变化时第二层你可以决定“触发后做什么”。最常见的是跑一个 shell command但官方也支持 HTTP hook、prompt hook、agent hook。放到 Claude Code 里看Hooks 就是在这些时机上挂动作。先配这 4 类就够了Claude Code 的 hook 事件现在已经很多了。官方 reference 里能看到二十多个事件包含PreToolUse、PostToolUse、Notification、Stop、SessionStart、PermissionRequest、CwdChanged、FileChanged等等。真正常用的先从这四类开始就够了。1.Notification让自己不用老盯着终端Claude Code 在需要你确认权限、等你输入或者有其他通知时可以直接走系统通知。官方 guide 里给了 macOS、Linux、Windows 的示例macOS 用osascript就能配。这类 hook 很实用因为你终于不用老盯着 terminal 了。一个最简单的配置大概长这样{hooks:{Notification:[{matcher:,hooks:[{type:command,command:osascript -e display notification \Claude Code needs your attention\ with title \Claude Code\}]}]}}如果你平时会切出去写文档、回消息、看 PR这个 hook 用起来会很顺。2.PostToolUse把格式化、轻量检查自动补上官方 guide 给的例子就是Claude 改完文件后自动跑 Prettier。触发点放在PostToolUsematcher 设成Edit|Write也就是只在 Claude 用编辑工具改完文件之后触发。{hooks:{PostToolUse:[{matcher:Edit|Write,hooks:[{type:command,command:jq -r .tool_input.file_path | xargs npx prettier --write}]}]}}这类 hook 最适合放“轻量、确定、不会拖慢太多”的动作比如prettier --writeruff formatbiome format针对单文件的 lint 或 fix社区里这类用法很多思路也很直接让 Claude 负责写最后那一下机械整理交给 hook。3.PreToolUse先把危险动作拦一下官方文档里有个例子很实用Claude 准备编辑文件前先检查目标路径是不是命中了受保护文件比如.env、package-lock.json、.git/。命中就直接 block。这类思路很适合放在团队项目里因为有些文件本来就不该让 agent 随便碰。Anthropic 自己在 repo 里还给了一个bash_command_validator_example.py。这个例子也很实用它拦截 Claude 准备执行的 Bash 命令如果发现用了grep或find -name这种你不想要的写法就直接阻止并给出更推荐的替代方式。PreToolUse不光能拦文件也能拿来拦命令习惯。4.Stop在 Claude 准备停下时再推它一把Stop会在 Claude 完成一轮回复、准备停下时触发。社区里不少人拿它做“最后一道检查”比如提醒 Claude再检查一下有没有测试没跑再看一眼改动范围是不是过大再确认一遍有没有漏掉 review comment修 bug、做重构、处理 PR 时这种 hook 会比较有用因为 Claude 常常在“看起来差不多”时就停下来。不过Stop也是最容易配出问题的一类。官方 guide 里专门写了一个坑Stop hook runs forever。如果你的 Stop hook 逻辑没有处理好就可能反复触发自己卡成循环。所以这一类要晚一点上而且脚本里最好带状态位判断。怎么配最基本的配置方式就是在 settings 里加一个hooks字段。官方 guide 的第一步写得很明确直接改~/.claude/settings.json项目级的配置也可以放在.claude/settings.json写完之后可以在 Claude Code 里输入/hooks去看当前有哪些事件、哪些 hook 已经生效。hooks 的基本结构长这样{hooks:{PostToolUse:[{matcher:Edit|Write,hooks:[{type:command,command:your-command-here}]}]}}这里最关键的几个点PostToolUse是事件名matcher用来过滤触发条件type决定 hook 怎么运行最常见是commandcommand就是实际执行的命令Claude Code 会把事件数据用 JSON 传到 hook 的 stdin 里。你的脚本可以读这个 JSON再决定做什么。从浅到深Hooks 大概可以分三层第一层提醒和善后这是最容易落地的。典型就是Notification做系统通知PostToolUse做格式化SessionStart注入一点上下文这一层基本不会改 Claude 的决策只是在补动作。第二层约束和保护到了这一层hook 已经会直接影响 Claude 的行为了。典型是PreToolUse拦受保护文件PreToolUse拦危险 Bash 命令PermissionRequest自动放行某些很窄的权限请求官方 guide 里给的PermissionRequest例子是自动批准ExitPlanMode。不过官方也专门提醒了一句matcher 要尽量窄别写成空或者.*否则等于把所有权限都自动放开了。第三层把 Hooks 用进工作流里再往上走Hooks 就不只是补几个小动作了会开始接进工作流本身。比如CwdChanged/FileChanged配direnv自动刷新环境变量ConfigChange记录设置或 skills 变更Stop做最终检查SubagentStart/SubagentStop做日志、通知或审计还有一个新方向是 async hooks。社区里已经有人把 voice hooks 改成 async在后台播放提示音不阻塞 Claude 正常继续工作。这类场景很适合放通知、日志、埋点一类动作。我的几条经验1. 先上轻的再上重的最容易失败的做法就是一上来把 hooks 配成“每改一次文件就跑全量检查”。这样当然也能工作但体感会很差。Claude 每走一步都被你拖住最后你会先把 hooks 关掉。更稳的做法是PostToolUse先放格式化、单文件检查全量 lint / test 放到Stop或者干脆放到你自己确认前再跑2. 复杂逻辑别硬塞一行 shell很多人会把命令直接写在 JSON 里。但真到了项目里只要逻辑稍微复杂一点最好单独放到脚本文件。比如.claude/hooks/protect-files.sh或者 Python 脚本。Anthropic 自己给的 Bash validator 示例就是 Python 文件没有把逻辑硬塞进一大串 shell。这样可读、可测试也更好维护。3. matcher 一定要尽量窄尤其是PermissionRequest这种 hookmatcher 写宽了后果会比普通通知 hook 大很多。能写到具体工具名就别写空。能写到具体事件值就别写全匹配。4. Hook 里要控制输出Claude Code 是通过 stdin / stdout / stderr / exit code 和 hook 通信的。这意味着脚本输出不能太随便。有一个很常见的坑你的 shell profile 里如果有无条件echohook 输出的 JSON 前面就会混进一段无关文本最后直接 JSON 解析失败。这类问题平时不太容易想到排查时要记得回头看看这里。5.Stophook 要防循环这一条值得单独记一下。很多人会很自然地想把更多检查塞到Stop里但Stop处理不好最容易出现“停不下来”的循环触发。官方 guide 已经把这个列成单独的 troubleshooting 条目了。所以Stop更适合做一个明确、可终止的收尾检查不要塞太长太重的一串流程。6. 先拿 Hooks 做“确定性动作”别拿它替代判断Hooks 最适合的是确定性规则改完就格式化动某类文件就拦某种通知就提醒目录变化就刷新环境而那种需要强判断、强上下文理解的事还是交给 Claude 本身、prompt hook、agent hook或者干脆让人来决定会更稳一点。Hooks 一旦承担了太多“判断”后面通常会越来越难维护。我会怎么开始配如果从零开始配 Claude Code Hooks我会按这个顺序来先上Notification再上PostToolUse的 formatter然后加一个PreToolUse的保护文件脚本用一段时间之后再考虑Stop或PermissionRequest这样上手比较快也不容易一开始就把体验配坏。最后如果你现在刚开始用 Claude Code其实不用急着把 Hooks 一次配很满。先上通知再上格式化再补一个保护文件的PreToolUse已经能解决不少实际问题。等你真的开始长时间用它写代码、改 PR、跑调试再慢慢加Stop、PermissionRequest、环境刷新这一类 hook会更顺一点。参考链接Claude Code Hooks 文档https://code.claude.com/docs/en/hooksClaude Code Hooks Guidehttps://code.claude.com/docs/en/hooks-guideAnthropic 官方示例Bash Command Validatorhttps://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py社区 Hooks 仓库含 voice hooks 与事件覆盖https://github.com/shanraisshan/claude-code-hooks社区最佳实践整理https://github.com/shanraisshan/claude-code-best-practice