Claude Code Hooks 实战：事件驱动自动化工作流

前几篇文章讲完 Claude Code 的基础用法和 Agent 控制不少读者已经在自己的项目里跑起来了。但多数人用着用着会卡在一个坎上它改完代码你不会立刻知道它自己跑出来的报错不会触发修复它准备执行一条危险命令你也只能干瞪眼。整个工作流依然是“你不停确认、它不停等”的聊天模式谈不上真正嵌入你的开发流程。Hooks 就是专门来解决这一层的。它是 Claude Code 暴露出来的一组事件钩子可以在模型调用工具之前、之后、会话启停、上下文压缩这些关键节点上让你用自己的脚本插一脚。今天这篇我打算把 Hooks 从配置模型到执行协议再到我实际搭过的几个生产级脚本完整拆一遍读完你就能自己接一套自动化质量门禁和上下文注入。1. Hooks 到底在解决什么问题1.1 Agent 工作流里的“盲区”要理解 Hooks 的价值得先看清楚 Claude Code 内部的运行闭环。模型在没有工具的情况下本质上只能基于上下文做推理真正让它可以“动手改代码”的是工具调用循环——模型决定调用哪个工具比如 Read、Edit、Bash、工具执行、执行结果作为 observation 喂回上下文模型再继续生成下一步。问题在于这个闭环的观测手段非常单一。Claude Code 能拿到的只有工具本身的返回值比如 Edit 返回“文件已修改diff 如下”、Bash 返回 stdout 和 stderr。但真实工程里你关心的信息往往不在这层。文件确实被改成了需要的逻辑可它没通过项目的 lint 规则命令返回了但后台进程被遗留测试跑完了可全是失败用例。这些外部质量信号模型根本看不见。所以传统用法下你得手动把这些信息粘贴到对话里或者一边盯终端一边反复问“现在什么状态”。一次两次能忍等你开始让 Agent 连续改十几个文件、跑几轮测试的时候这种人工观测就成了最大的瓶颈。Hooks 就是在这些节奏点上给你开的“后门”。你在 settings.json 里注册一个脚本Claude Code 就会在指定事件触发时调用它并且把脚本输出注入回 Agent 的上下文。这相当于给你的 Agent 装上了一个可编程的眼睛和一只可编程的手。1.2 事件驱动、外部命令为什么是这种设计我最初接触 Hooks 时最大的疑惑是为什么不让 Claude Code 直接内置一套插件 API看到完整设计之后我觉得这个取舍非常清醒。首先外部命令方案的接入成本极低。不管你的技术栈是 Node、Python、Shell 还是 Go只要能产出可执行文件就能当 Hook 用。你不需要理解 Claude Code 内部的数据结构也不需要跟随它的 SDK 升级本质上就是读写 JSON 控制退出码。对项目里已有的脚本生态来说几乎零迁移成本。其次安全边界很干净。Hook 脚本运行在独立的子进程跟 Claude Code 主进程隔离。哪怕脚本写崩了最坏的结果是超时被杀或被忽略不会拖垮对话主体。这比加载一个可能影响模型行为的插件安全得多。最后透明的执行协议让调试变得直接。你可以在终端手动跑一遍 Hook 脚本传入 mock 的 JSON 输入观察输出再推断 Claude Code 会怎么反应。这种简单粗暴的验证方式在生产环境里非常珍贵。后面我会专门写调试手段你会发现所有坑最后都落在“输入输出协议没遵守”这一点上。2. 配置模型与事件图谱2.1 settings.json 的层级与合并规则Hooks 的配置统一放在 settings.json 里但区分三个层级。用户级配置在~/.claude/settings.json作用于这台机器上所有项目适合放一些通用规范比如禁止执行危险命令。项目级配置在.claude/settings.json跟随仓库走一般提交到版本控制适合放该项目的专属规则比如代码风格检查。还有一个是本地级.claude/settings.local.json也是项目级别但通常写进 .gitignore用来保存个人偏好。这三层配置会按特定顺序合并本地级优先级最高其次是项目级最后才是用户级。我的习惯是项目级放必须执行的 Hook本地级放只有我自己需要的调试 Hook。避免把个人脚本带进共享仓库省得队友 clone 下来跑出一个奇怪的报错。配置结构本身是嵌套的。外层 keys 是事件名称每个事件下面可以挂多个规则每个规则通过 matcher 匹配工具再在 hooks 数组里定义实际要执行的命令。看一段示例{ hooks: { PostToolUse: [ { matcher: Edit|Write|MultiEdit, hooks: [ { type: command, command: sh .claude/hooks/post-edit.sh, timeout: 30 } ] } ] } }这里 matcher 是规则匹配的工具范围hooks 数组里可以挂多个命令。同一个事件下多个规则、同一条规则下多个命令会按照它们在 JSON 里的顺序依次执行。这意味着你可以把不同职责拆到不同脚本里比如一个跑格式检查、另一个发通知互不干扰。2.2 八种事件类型与匹配规则Claude Code 的 Hooks 覆盖了 Agent 生命周期的主要节点。我整理了下表事件名触发时机典型用途PreToolUse模型调用工具之前拦截危险命令、注入工具调用参数PostToolUse工具执行完成之后质量检查、收集结果、触发下游动作UserPromptSubmit用户消息提交、模型处理之前注入项目上下文、改写用户请求NotificationClaude Code 需要发送通知时任务完成提醒、发到外部通知服务Stop一次响应生成完毕、等待用户输入前生成提交信息、记录会话摘要PreCompact上下文压缩发生之前保留关键状态、提前做摘要存储SessionStart新会话启动时初始化环境、注入项目规范SessionEnd会话关闭或结束时清理临时文件、汇总会话产出matcher 的匹配规则我建议从简单开始。最直接的是精确匹配工具名比如matcher: Bash。如果你希望覆盖多个工具可以用|分隔或者使用通配符匹配到这个事件下的全部工具。我实际用得最多的是精确匹配和通配符两种方案里按需选。这里有个容易被忽略的点matcher 针对的是工具名不是工具参数。你想拦截“所有包含 rm -rf 的 Bash 命令”正则应该写在 Hook 脚本内部而不是靠 matcher。刚开始我搞反了以为写Bash.*rm.*rf就能匹配结果脚本压根没触发花了半天才回过神来。2.3 stdin 输入与 stdout 输出协议每个 Hook 被调用时Claude Code 会往进程的 stdin 写入一段 JSON这是你获取上下文的唯一入口。标准结构长这样{ hook_event_name: PostToolUse, tool_name: Edit, tool_input: { file_path: src/index.ts, new_content: ... }, session_id: session-uuid-xxx, cwd: /home/user/project }session_id 和 cwd 通常免费送给你的很多脚本需要靠它们判断上下文。比如 SessionStart 的 Hook 可以根据 cwd 找到项目根目录再读取对应的项目文档。Hook 脚本的 stdout 有特定含义它必须输出一个 JSON 数组数组里每一个元素代表一条指令。最常用的字段有decision取值block、allow、ask、deny在 PreToolUse 里控制工具是否继续执行。permissionDecision取值allow、deny用于直接代用户批准或拒绝某个工具的权限申请。continue布尔值false 时会中断当前 Agent 循环。observations数组里面放你想喂回给模型的文本类型通常是note或error。stdout 里的内容会作为 observation 注入上下文所以你要把能给模型带来增量信息的文本放进这里。与之相对脚本的 stderr 则会被当作错误信息处理在特定场景下成为模型重试的参考。退出码同样携带语义。0 表示一切正常1 表示失败反馈给模型2 是“工具执行失败请重试”的强信号Claude 会停下来看你的 stderr 内容后重跑3 则比较特殊它会中断当前循环把脚本输出带给用户做确认适合做危险操作的人工闸门。提示不同版本在协议细节上可能会有演进写脚本之前先看一眼你所用版本的官方文档约定避免因为字段名变化导致联动失效。3. 从 0 到 1 的四个实战 Hook3.1 SessionStart 注入项目上下文先从一个门槛最低、回报最快的场景开始。默认情况下Claude Code 每次新会话都不知道你的项目约定你得反复粘贴项目说明、技术栈清单、目录结构、特殊规范特别浪费 token 也特别容易漏。SessionStart Hook 的思路很简单会话建立时读取指定文件把项目摘要输出到 stdoutClaude Code 会把这段文本作为初始 observation 注入上下文。这样模型从一开始就“带着记忆”工作。我常用的脚本实现思路如下#!/bin/bash PROJECT_DIR$(echo $1 | jq -r .cwd) CONTEXT_FILE$PROJECT_DIR/PROJECT_CONTEXT.md if [ -f $CONTEXT_FILE ]; then echo [{\observation\: \以下是项目的完整背景文档请先阅读再回答用户问题\\n\ $(jq -Rs . $CONTEXT_FILE)}] else echo [] fi注意两点。第一stdout 必须是 JSON 数组格式所以读取文件内容之后要用 jq 的-Rs转成合法 JSON 字符串直接拼会导致转义灾难。第二SessionStart 的 stdout 会直接进模型上下文文件别塞太大的东西超过几万字符的内容模型读了也只会稀释注意力。我的经验是只摘取项目目标、技术栈、核心目录、开发命令、代码规范重点五六十行足够。为了让这个方案更通用我把上下文文件拆成可继承结构PROJECT_CONTEXT.md放项目不可变信息另外再支持一个个人私有文件放个人偏好用 Hook 里的判断合并输出。这样团队成员共享一份规范个人也可以叠加自己的习惯。3.2 PostToolUse 自动化质量门禁这个场景我强烈建议每个工程化项目都接。原理是在模型写完代码后立刻触发静态检查把结果作为 observation 喂回去让模型自己看到并修复。我的做法是监听Edit|Write|MultiEdit三个工具脚本拿到tool_input.file_path后根据文件后缀选择检查器。前端项目跑 ESLint后端项目跑 tscPython 项目跑 ruff。输出时把所有问题打包成一条 observation[ { observation: ESLint 检测到 3 个错误文件 src/utils.ts:\n1. line 18: no-unused-vars\n2. line 42: no-console\n请修复这些错误, type: note } ]模型拿到这个反馈之后通常会主动把错误消化掉进入下一轮修复。如果你更激进可以让脚本在发现问题时返回退出码 2强制 Claude 认为“工具执行失败”重试直到通过检查。我实际测试下来退出码 0 错误 observation 的策略更柔顺模型不会死磕一个文件而是会结合整体任务判断退出码 2 适合那种“不修就不准继续”的硬性门禁比如提交规范。这里要小心死循环。之前我写过一个脚本在 PostToolUse 里跑 eslint一旦发现问题就返回 2。结果模型修完一个错再次触发 Hook又发现另一个错又返回 2……反复拉扯好几轮直到 token 烧掉不少。后来加了条保护在同一次任务里同一个 Hook 连续触发超过三个轮回就不再强制重试只输出 note 让模型自行决定。3.3 PreToolUse 拦截危险命令PreToolUse 是安全最后一道闸门。我在这个 Hook 里拦截的是那些模型“不该擅自决定”的命令递归删文件、强制推送、生产环境操作、curl 脚本直接管道给 sh。脚本逻辑并不复杂关键在于策略。第一层策略是直接 block。凡是命中白名单外的破坏性命令直接输出decision: block同时把原因写进 observation。模型会看到“该操作已被拦截”的解释然后自己调整方案。第二层策略是 exit code 3请求用户确认。有些命令不一定非法但风险足够高我不希望模型擅自跳过也不想直接禁掉。比如git push --force某些场景下是必要操作但它对仓库历史有不可逆影响。这种情况下 Hook 输出 JSON 让 Claude 暂停把决策权交还给你。[ { decision: block, observations: [ { type: error, text: 检测到强制推送命令已拦截。如需执行请用户手动确认并在 tool_input 中注明 --force-ok } ] } ]实际跑下来发现一个设计要点拦截信息别只给模型还要尽量写在用户能立刻看到的地方。因为用户可能正切在别的窗口完全没看到 Claude 被拦了。我在脚本里会让 stderr 输出一句人话比如“已阻止危险的 git 强制推送”这样终端界面会有明显提示。模型那边虽然拿不到 stderr 内容但这个行为会被记录下来。3.4 Stop 节点完成提交信息生成Stop 事件的节拍是“模型生成完毕等待用户输入”非常适合做那些不需要打扰用户的操作。我接的最顺手的是 commit message 自动生成。思路是让 Claude 自己先构思改动在 Stop 触发时脚本去 git status 和 git diff 里捞数据把它整理成一份标准 commit 草稿写到项目根目录的临时文件。然后我在代码编辑器里一键读取那份文件改改就能提交。整个过程模型没有被额外提示词干扰用户也无需在终端里复制粘贴。脚本核心就两步。第一步读出 diff 概要统计改了哪些文件、增删行数、涉及的函数名。第二步把内容压缩成一个短小的 JSON输出到git_commit_message.txt同时把“已生成提交信息草稿请查收”作为 observation 返回。这里我不建议让模型直接生产完整消息。模型在 Stop 事件里已经结束了当前 context你再塞 stdin 进去它只会做一次新的生成反而容易延长响应时间。让我脚本自己从 git 数据里提取反而更可控。3.5 SessionEnd 汇总会话产出Session 结束时信息最容易流失。Claude Code 默认会记录这次对话但都是聊天式的记录不好检索。SessionEnd Hook 可以实现一个小档案机制脚本读取会话内被修改的文件列表生成一份session-summary.json里面包含修改时间、文件路径、简要变更类型。我在实践里把它跟 git 分支关联起来——每次会话建一个独立分支SessionEnd 时把这个分支上的改动清单输出成一份 commit-ready 的note。等代码 review 时整个分支的改动历史一目了然。4. 调试、权限与避坑清单4.1 调试 Hooks 的标准动作Hooks 接入失败最让人烦躁的一点是“明明配置了但像没生效一样”。我的排查顺序是先确认事件有没有触发再确认脚本本身有没有问题。事件没触发多半是 matcher 写错或者 settings.json 所在层级没对上。项目级配置只对当前目录下的会话生效如果你是cd到子目录里启动的 Claude Code记得检查配置是不是在正确的项目根目录。脚本本身的问题最直接的调试方法是绕过 Claude Code手动模拟 stdin。你可以复制一份真实的 JSON 输入然后直接跑echo {hook_event_name:PostToolUse,tool_name:Edit,tool_input:{file_path:src/a.ts},cwd:/path/to/project,session_id:xxx} | sh .claude/hooks/post-edit.sh看它的 stdout 输出是否符合协议。大多数问题在这里都能暴露出来比如 JSON 解析失败、脚本路径不对、依赖的命令找不到。如果脚本单独跑没问题但接进 Claude Code 就没反应再开一个claude --debug的会话实测日志里会记录每次 Hook 的调用和输出。4.2 权限控制的几个微妙点Hooks 的权限能力很容易被高估。PreToolUse 里输出permissionDecision: allow可以替用户批准某个工具调用但它绕过了用户本来想手动确认的环节。我的态度是能不用就不用特别是对 Bash 这种影响面大的工具。一旦误放行代价远高于便利。如果你确实需要建议在配置上做范围收缩。比如只在 matcher 精确匹配Read的 Hook 里自动 allow把 Bash 的自动批准排除在外。另外注意,权限决策是一次性的它的作用范围只针对本次工具调用不会让你一劳永逸地对某类命令全部放行。这种设计虽然啰嗦但其实是安全底线。还有个跟权限合作的细节如果 Hook 脚本自身没有执行权限Claude Code 调用时会直接被拒绝。我犯过这个错写完脚本忘了chmod x结果所有 Hook 都静默失败排了半天才发现命令压根没跑起来。4.3 常见问题速查表症状可能原因排查建议Hook 完全没有触发matcher 写错、配置层级不对检查 settings 文件路径、事件拼写Hook 触发了但模型没反应stdout 没有按 JSON 数组输出手动跑脚本看 stdout 原始内容exit code 2 但模型没有重试stderr 为空或模型认为无新信息在 stderr 中描述失败原因脚本导致会话卡住命令执行时间过长设置 timeout 属性、检查脚本是否有等待输入JSON 解析失败脚本里 echo 了非 JSON 内容把所有日志输出到文件stdout 只留协议内容环境变量找不到 node/pythonPATH 在 GUI 环境里不完整在脚本开头显式导出 PATH这里面我最想强调的是最后一行。如果你是从集成开发环境的终端启动 Claude CodePATH 很可能跟你 shell 下不一样脚本里直接用node、python这类命令很可能失败。我的脚本开头都会写死关键解释器路径或者用一个包装器把 PATH 补全从根源上杜绝这类环境问题。4.4 我踩过的几个实打实的坑第一个坑是污染 stdout。写 PostToolUse 排错的时候我在脚本里加了不少echo debug ...结果这些内容全被当成了 JSON 数组的一部分模型直接读到废文本行为错乱。后来我强制自己打日志一律进 stderr 或日志文件stdout 里只允许出现协议 JSON。第二个坑是引号嵌套炸裂。脚本里拼 JSON 时我直接用双引号包内容遇到文本里本来就有引号就崩了。现在构建 stdout 我全部用 jq 的-c和--arg来构造 JSON 对象彻底告别手工拼接字符串。第三个坑是大文件上下文注入。SessionStart 的脚本读了一个 300KB 的项目说明文档直接把整个文档塞进 observation模型响应速度肉眼可见变慢而且后续还出现注意力漂移。后来我改成先提取目录结构、README 前 80 行、Makefile 里的常用命令体积控制在几 KB效果好很多。第四个坑是循环触发。PostToolUse 的检查脚本自己如果会写文件就会再次触发 PostToolUse 事件形成无限循环。我在脚本里增加了一个判断如果tool_input.file_path是脚本自身生成的临时文件就直接跳过检查。5. 顺手可做的进阶玩法如果你已经把基础四个玩熟可以试试给 Hook 加状态。Claude Code 的 Hook 是无状态的每次调用都是独立进程但你可以利用文件系统让脚本之间共享上下文。我在一个长期维护的项目里让 SessionStart 写一个临时状态目录各个 Hook 往里面放中间产物SessionEnd 统一清理。这个设计让多个 Hook 之间可以协作也能实现跨会话的状态保留代价是注意清理别把仓库搞乱。另一个方向是结合外部通知。Notification 事件在你需要知道“任务是否跑完”时非常有用。我自己在跑长任务的 CI 场景里让 Claude 结束 Stop 时触发一个通知脚本把改动摘要发到团队 IM 的 webhook。技术栈不限Shell 加 curl 就够。这个玩法会显著提高你对异步 Agent 任务的掌控感。最后提一嘴CLAUDE.md 的内容也可以利用 Hooks 做动态生成。Dont 把项目规范全写进静态文件而是 SessionStart 时根据当前 git 分支、环境变量生成一个精简版的上下文注入。这让同一个仓库在不同环境下的表现可以联动变化。我从开始实验的两个 Hook 到现在项目里跑着八九个最大的感受是Hooks 把 Claude Code 从一个“会聊天的代码生成器”变成了一套可以编程控制的工作流基础设施。你不再需要手动喂上下文不再担心 Agent 乱跑危险命令质量检查也能自动拉进循环里。如果你还在观望我建议从 SessionStart 开始接——它改动最小、收益最直观接上之后你再回头看之前那种每次都手动粘贴项目说明的日子是真的回不去了。