最近半年我花在Claude Code上的时间比IDE还多一开始只是图省事让它帮我写点重复代码、跑跑回归测试。用得越深越发现一个尴尬的问题它太“听话”了——你叫它改一个函数它顺手把测试文件也改了你说继续它一路往前冲遇到危险命令会问你要确认可问多了你手一滑就全批准了。有一天我盯着聊天记录里那二十多个“同意”按钮突然觉得这不是在用人这是在当陪聊。后来我把Hooks机制彻底吃透把那些机械化的确认、格式检查、文档同步全部交给脚本去接管才算真正体验到什么叫“自定义工作流自动化”。这篇东西就是把我从零摸索Hooks机制的过程中踩过的坑、读过的文档、写废又改好的脚本全部摊开来讲一遍。适合两类人一是已经被Claude Code各种确认动作烦到不行的老用户二是刚装好Claude Code、还没搞明白怎么优雅控制它的小白。哪怕你目前用的是接入第三方模型的方式Hooks这套配置逻辑基本不受影响照用就行。1. Hooks机制到底是什么从“每次都要盯”到“规则替你盯”1.1 没有Hooks时的日常痛点先复盘一下没有Hooks时的典型工作流。你和Claude Code说“帮我重构某个模块”它会自己列计划调工具读代码、改文件、跑测试。每一步它都可能停下来问你要不要读这个文件要不要用这个正则替换要不要执行这条命令这些确认动作本质上是安全措施防止AI乱来。但问题是当这个AI已经在你项目里泡了三个小时、你对它足够信任时这些确认就变成了纯噪音。还有一种更难忍的情况你让它“每次提交前跑一遍lint”它确实会跑但你要是忘了在提示词里说得足够明确它十次有八次直接跳过默认你不需要。这也是提示词工程的极限——你没法靠“在系统提示词里写规则”来强制一个对话式Agent稳定执行某种行为因为它本质上是概率模型不是规则引擎。Hooks要解决的正是“概率模型不稳定执行”和“人工确认太频繁”这两个核心矛盾。1.2 Hooks的两种工作模式阻断与非阻断Claude Code Hooks机制简单说就是一套事件回调系统。它在Agent的整个生命周期里埋了一系列事件点比如“准备调用某个工具之前”“调用完某个工具之后”“一轮对话结束之后”“会话刚刚启动的时候”。你可以为这些事件挂上自定义脚本脚本跑完后再把控制权交还给Claude。这里最关键的是区分两种工作模式。非阻断模式对应的事件是PostToolUse、Stop、SessionStart这类“事后通知”你可以在里面做日志、格式化、发通知但不能改变Claude已经做出的动作。阻断模式则主要围着PreToolUse打转它发生在工具实际执行之前如果你的脚本以特定退出码返回可以直接让Claude停掉连工具都不用碰。这个“阻断”语义是所有工作流安全管控的地基后面实战部分我会单独展开。1.3 为什么说是“工作流自动化”的关键拼图单纯把这些事件接出来就已经很有用了但Hooks真正厉害的是可以组合。比如你可以让PostToolUse里跑完lint后自动写一份报告文本再让Claude读这份报告修正代码也可以让PreToolUse检测到危险命令后直接进入一个“必须人工输入令牌才放行”的流程。这种方式跟传统CI里的Git钩子很像但它是专门为Agent行为设计的视角完全不一样——Git钩子是管“这个提交要不要发生”Claude Code的Hooks是管“让AI自主时约束哪些红线绝对不能越过”。我自己用下来最大的感受是Hooks让Claude Code从一个“聊天框里的智能体”变成了“一条产线上能自动流转的工序”。你人不在工位上它也照常按规则干活违规了它会停下来等——这才叫把自动化做扎实了。2. 反向工程Hooks的完整事件清单与触发时机2.1 决策型事件PreToolUse怎么做到“一票否决”PreToolUse是Hooks体系里权力最大的事件它在Claude Code准备执行任意工具前触发。这里的“工具”不只是读文件、写文件还包括Bash、WebSearch以及你通过MCP接入的所有外部工具。你的脚本能拿到本次要调用的工具名、传入参数、还有Claude的意图上下文。在这个事件里做决定不是靠“返回提示文本”而是靠退出码和decision字段。退出码为0等于放行退出码为2Claude会直接放弃这次工具调用。你还可以在stdout里输出一段理由这段理由会出现在对话流里让Claude知道为什么被拒。这个“reason”字段不是随便给你的它能让AI在下一次调用时调整参数——比如你禁止它用rm -rf它会立刻改成先移动到.trash目录再去删。这种闭环反馈是单纯拦截做不到的。2.2 事后通知型事件Stop、PostToolUse、SessionStart等非阻断事件里最常用的是PostToolUse和SessionStart。PostToolUse在每个工具执行完成后触发你能拿到退出码、标准输出、标准错误、执行时长这些元数据。我通常用它跑lint、测速、记录变更痕迹这些活干完不需要打断主流程。SessionStart则是每次启动新会话时触发一次非常适合做环境初始化——把当前分支名、最近变更文件、项目规范文件内容一股脑喂给Claude让它开局就带着上下文干活不用每次靠提示词重复灌输。Stop事件则是Claude完成一轮完整响应、把主控权交还给你时触发这时候适合做“阶段汇报”把这一轮改过的文件列表、执行过的命令汇总成一条信息推给你。2.3 事件执行的顺序与嵌套关系理解事件顺序很重要否则你会写出互相打架的脚本。一个典型的完整响应周期是你先发出一条人类消息触发UserPromptSubmitClaude开始响应期间可能会依次调用多个工具每个工具调用前后分别触发PreToolUse和PostToolUse如果Claude中途进入子Agent还会触发SubagentStop响应结束触发Stop。会话太长被压缩时会先触发PreCompact这时候你可以把关键状态存到外部文件免得压缩后失忆。嵌套关系的坑在于如果你的Hooks脚本内部又调用了Claude Code的命令行界面极容易造成递归触发。比如PostToolUse里你执行claude -p 整理这段代码”这个子进程又会触发PostToolUse直接导致事件风暴。我在早期脚本里就吃过这个亏稍后章节详细说解决方案。3. 从零配置Hooks的配置文件结构与快速上手3.1 配置写在哪个文件里Claude Code的Hooks配置放在.claude/settings.json项目级文件里也可以放到用户级配置文件前者随仓库走、适合团队共享规则后者绑在你个人环境上、适合个人习惯。无论放哪一级结构完全一致。{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 scripts/guard_bash.py, timeout: 10 } ] } ], Stop: [ { hooks: [ { type: command, command: node scripts/report_stop.js } ] } ] } }matcher只有部分事件需要它是用来按工具名做精准匹配的。比如Bash、Edit、Write都是工具名你不设置matcher就代表拦截全部工具调用实际操作中会造成很多误伤所以建议能加就加。3.2 第一个必会案例每次写完代码自动做静态检查先用一个最实用的案例感受整个链路。我要求“Claude每次写完文件后自动对该文件跑ESLint”配置如下{ hooks: { PostToolUse: [ { matcher: Write|Edit|MultiEdit, hooks: [ { type: command, command: node scripts/lint_after_edit.js } ] } ] } }lint_after_edit.js里做的事情很简单从标准输入读取JSON事件对象拿到tool_input.file_path字段然后调ESLint的Node API跑一遍。这里有个关键细节Claude Code通过stdin把事件数据以JSON格式传给脚本不是你脚本里自己去找文件路径。很多新手脚本写不对就是因为完全没读stdin以为环境变量里有这些信息。const fs require(fs); const { ESLint } require(eslint); let input ; process.stdin.on(data, chunk input chunk); process.stdin.on(end, async () { const event JSON.parse(input); const filePath event.tool_input.file_path; if (!filePath || !filePath.endsWith(.js)) process.exit(0); const eslint new ESLint({ fix: false }); const results await eslint.lintFiles([filePath]); const errors results.flatMap(r r.messages.filter(m m.severity 2)); if (errors.length 0) { console.error([lint] ${filePath} 有 ${errors.length} 个错误请修复后再继续); // 这里故意不exit非0因为PostToolUse的失败不会阻断Claude // 但我把错误信息打到stderrClaude能看到并主动修复 } });注意PostToolUse里脚本退出码非0只会记录错误不会终止Claude。它就是“通知”语义。如果你真的想“代码不合格就不许继续”那得把检查放到PreToolUse里拦截下一个Write动作或者放到Stop事件里判断“如果你这轮改完还有错误下一轮我不放行”。这个思路差异特别重要。3.3 自己动手验证Hooks是否生效的快速路径配置写好后怎么知道有没有生效最直接的办法是在事件脚本第一行加个日志落盘#!/bin/bash echo $(date) $0 received /tmp/claude_hooks.log cat /tmp/last_event.json配合cat /tmp/last_event.json把stdin的完整事件数据存下来然后随便让Claude执行一个工具操作再去看这两个文件。如果文件没生成说明配置压根没加载多半是settings.json路径错了或者JSON语法有误。如果文件生成了但内容不对说明你的事件理解有偏差再看matcher匹配对不对。这一步搞定了Hooks的基础功力就有了后面所有复杂玩法都是在这个链路上加逻辑。4. 自定义工作流自动化实操三个完整的场景打磨4.1 场景一自动化更新Changelog与版本发布记录这个场景适合团队协作或者长期维护的开源项目。痛点很常见AI改了一堆代码提交信息写得飞起但CHANGELOG.md永远忘记更新发版前只能人工回忆两周之内干了啥。用Hooks可以在每个Stop事件里自动收集本轮变更。我的做法是写一个update_changelog.py在Stop触发时读取上一个git tag之后的提交记录结合Claude写入的变更描述文件自动整理成今天的更新条目插入到CHANGELOG.md头部。关键点在于不要让脚本直接改写文件——我让脚本生成一份CHANGELOG.tmp.md然后通过llm提示Claude去整合格式。这样既保持了可读性又避免了“脚本直接改文档Claude不知道下次又乱改”的信息割裂。完整思路Stop事件 → 执行git log收集提交 → 生成新增内容 → 写进临时文件 → stdout里提示“已生成新的changelog草案是否需要合并进CHANGELOG.md”。由于Stop事件不会阻断Claude所以这个提示会作为上下文给到Claude它下一轮就能主动执行合并操作。一个人机协作的闭环就出来了。4.2 场景二危险命令的“双人复核”闸门这个是我认为Hooks最能体现价值的地方。Claude Code在执行Bash命令时会询问你是否允许但当你选择--dangerously-skip-permissions模式时这个确认就没了。你可以用PreToolUse把它找补回来。我的实现是在PreToolUse里匹配Bash然后正则检查命令内容。命中危险模式rm -rf、git push --force、DROP TABLE等就输出一个封禁提示并退出码2直接拒绝执行。import json, re, sys danger_patterns [ r\brm\s-rf\b, r\bgit\spush\s.*--force\b, r\bdrop\stable\b, ] data json.load(sys.stdin) cmd data.get(tool_input, {}).get(command, ) reason 命中危险命令规则已阻止。请使用更安全的替代操作。 if any(re.search(p, cmd, re.IGNORECASE) for p in danger_patterns): # stdout的内容会作为reason展示给Claude print(reason) sys.exit(2) sys.exit(0)还有个进阶玩法不直接无条件冻结而是“先冻结再放行”。我在脚本里对命中规则的危险命令生成一个一次性授权码同时通过企业微信机器人把“有人请求执行危险命令授权码是XXXX”推给指定负责人。负责人确认后把授权码告诉ClaudeClaude在下一次重试时把授权码作为环境变量传入命令脚本检测到配套授权码才放行。这就等于把一个纯AI的工作流硬化成了“双人复核”的合规流程。虽然这套实现复杂度高但对金融、运维场景来说它是实实在在能过审计的方案。4.3 场景三让Claude Code的阶段性结论主动“汇报”出来这个场景适合挂机跑长任务的人。以前我让它跑测试人只能守在那里刷新终端。用Hooks之后每轮Stop事件里我能拿到Claude刚刚的回复内容直接交给脚本解析出关键结论然后通过飞书/钉钉/微信机器人的Webhook推送到手机。脚本里只需要处理stdin里的stop_hook_active标志和response字段。因为Stop事件传进来的JSON里response是一段文本直接把这个文本Post到Webhook就是一个最朴素的“AI进度播报”。如果想做结构化就让Claude在回复里约定输出进度: 30% | 当前任务: 重构登录模块 | 阻塞: 无这种固定格式脚本再用正则提取。这个场景做完之后我实际使用体验变化非常大。原本干完活才发现出错的“事后沮丧”变成了每三分钟看一次手机就知道进度的“实时掌控”。特别是长夜挂机的批量任务早上起来翻推送记录就能完成工作总结不用再翻终端日志。4.4 把事件脚本本身纳入版本管理很多人会忽略这一点Hooks脚本是项目的一部分逻辑不是临时工具。我强烈建议把.claude/settings.json和所有hooks_scripts/目录纳入Git版本管理。一旦团队成员clone仓库Hooks规则自动生效不再需要口头传达“你记得跑lint啊”这种话。但这里也引出一个问题团队里不是所有人都信任AI自动改代码。所以我在仓库里额外写了一个HOOKS.md说明每个钩子是干什么的、如果觉得误拦截了可以怎么临时豁免。比如我的危险命令脚本里支持一个ALLOWLIST_FILE环境变量里面写可放行的命令正则清单。这样有不同风险偏好的同事可以自己维护自己的豁免规则不影响公共安全底线。5. 非对称问题手册Hooks落地过程中的那些坑5.1 问题速查表以下是我实际踩过、也在社区里见过的高频问题整理成速查表方便直接查。现象根因解决方案配置写了但事件不触发settings.json路径不对或JSON解析失败在脚本首行加日志落盘验证stdin是否收到数据脚本能跑但Claude看不到提示输出打到了stdout但没带Claude Code上下文标记确认输出的是纯文本reason或错误信息不要用console.log输出无关调试内容事件风暴、CPU暴涨Hooks脚本内调用了claude命令递归触发同一事件脚本里用环境变量CLAUDE_HOOK_RUNNING做开关已运行则直接退出中文路径或UTF-8内容乱码Windows下编码问题脚本统一用utf-8模式读写Bash脚本不要用系统默认GBK命令执行超时被kill默认timeout不足给每类hook显式设置timeout比如lint类给60秒PreToolUse想拦截但拦不住matcher写错或用了退出码1而非2PreToolUse阻断必须退出码2退出码1只代表“出错”而非“拒绝”5.2 环境变量、幂等性和超时这三个教训展开说说我觉得最重要的三个教训。第一环境变量的传递链。Hooks脚本执行环境是独立子进程它拿不到你shell里那些自定义别名和函数。我刚开始写脚本时在里面用了一个Shell别名结果跑得好好的脚本在Hooks里直接command not found。后来所有的PATH依赖都改成绝对路径或者在脚本开头source指定的环境文件。还有一个细节UserPromptSubmit事件触发时用户刚输入的那条消息不是通过argv传进去的而是从stdin的JSON里拿这个位置搞错就会导致你永远拿不到用户输入。第二幂等性设计。Hooks脚本被触发的频率比你想的高得多它必须能重复执行且不产生副作用。有一次我在PostToolUse里写了“每次改完文件就append一行时间戳到日志”看起来没问题但Claude喜欢连续多次写入同一文件导致日志里全是重复行。后来所有日志都改成基于“事件唯一ID”去重脚本执行前先检查ID是否存在存在就直接跳过。第三超时时间的艺术。默认超时是60秒但lint大项目时不够用。我一开始把超时设到300秒发现一个问题Claude执行Bash命令本身也有一套内部超时逻辑如果我的hook在那边等待太久Claude会认为工具执行失败并自行处理反而触发误判。最后我把耗时操作拆成两个阶段hook先快速落一个“开始处理”的标记文件真正的重活放到PostToolUse里异步执行hook本体只做通知不等待。这样既拿到了完整结果又不会拖垮主流程。5.3 不要让Hooks变成新的“确认地狱”顺带说个理念层面的问题。Hooks可以拦截很多危险动作但这不代表你应该拦截一切。我看过有些团队把PreToolUse写得密密麻麻读文件要拦、写文件要拦、跑命令更要拦最后Claude Code每走一步都被自己的约束脚本打回来使用体验跟手动敲确认没什么两样甚至更糟——因为手动确认至少还有上下文脚本拦截时Claude常常一头雾水。我的原则是只拦截“不可逆”和“高成本”的动作。删文件、强推代码、清空数据库这种必须拦写普通源文件、跑一次测试这种就让AI放手去做出了问题用PostToolUse追踪和提示。自动化是为了提高信任度不是用一堆规则把Agent锁死这个边界得靠每个用户根据自己的场景拿捏没有放之四海皆准的配置。回过头来看Hooks机制是整个Agent化工作流里最容易被低估的一部分。大家习惯把注意力放在模型多强、提示词多妙上但真正让AI从“玩具”变成“工具”的恰恰是这些不起眼的、能定规矩的脚本接口。我现在跑项目的时候Claude Code是一个可以在安全边界内自主决策的执行单元而Hooks就是那张写着边界在哪里的图纸。你把它画清楚AI放心干你也能安心放手。这就是我为什么愿意花这么多篇幅写它——不是因为它新而是因为它真的改变了人跟AI协作的方式。
从“陪聊”到“产线”：Claude Code Hooks机制实现自定义工作流自动化
最近半年我花在Claude Code上的时间比IDE还多一开始只是图省事让它帮我写点重复代码、跑跑回归测试。用得越深越发现一个尴尬的问题它太“听话”了——你叫它改一个函数它顺手把测试文件也改了你说继续它一路往前冲遇到危险命令会问你要确认可问多了你手一滑就全批准了。有一天我盯着聊天记录里那二十多个“同意”按钮突然觉得这不是在用人这是在当陪聊。后来我把Hooks机制彻底吃透把那些机械化的确认、格式检查、文档同步全部交给脚本去接管才算真正体验到什么叫“自定义工作流自动化”。这篇东西就是把我从零摸索Hooks机制的过程中踩过的坑、读过的文档、写废又改好的脚本全部摊开来讲一遍。适合两类人一是已经被Claude Code各种确认动作烦到不行的老用户二是刚装好Claude Code、还没搞明白怎么优雅控制它的小白。哪怕你目前用的是接入第三方模型的方式Hooks这套配置逻辑基本不受影响照用就行。1. Hooks机制到底是什么从“每次都要盯”到“规则替你盯”1.1 没有Hooks时的日常痛点先复盘一下没有Hooks时的典型工作流。你和Claude Code说“帮我重构某个模块”它会自己列计划调工具读代码、改文件、跑测试。每一步它都可能停下来问你要不要读这个文件要不要用这个正则替换要不要执行这条命令这些确认动作本质上是安全措施防止AI乱来。但问题是当这个AI已经在你项目里泡了三个小时、你对它足够信任时这些确认就变成了纯噪音。还有一种更难忍的情况你让它“每次提交前跑一遍lint”它确实会跑但你要是忘了在提示词里说得足够明确它十次有八次直接跳过默认你不需要。这也是提示词工程的极限——你没法靠“在系统提示词里写规则”来强制一个对话式Agent稳定执行某种行为因为它本质上是概率模型不是规则引擎。Hooks要解决的正是“概率模型不稳定执行”和“人工确认太频繁”这两个核心矛盾。1.2 Hooks的两种工作模式阻断与非阻断Claude Code Hooks机制简单说就是一套事件回调系统。它在Agent的整个生命周期里埋了一系列事件点比如“准备调用某个工具之前”“调用完某个工具之后”“一轮对话结束之后”“会话刚刚启动的时候”。你可以为这些事件挂上自定义脚本脚本跑完后再把控制权交还给Claude。这里最关键的是区分两种工作模式。非阻断模式对应的事件是PostToolUse、Stop、SessionStart这类“事后通知”你可以在里面做日志、格式化、发通知但不能改变Claude已经做出的动作。阻断模式则主要围着PreToolUse打转它发生在工具实际执行之前如果你的脚本以特定退出码返回可以直接让Claude停掉连工具都不用碰。这个“阻断”语义是所有工作流安全管控的地基后面实战部分我会单独展开。1.3 为什么说是“工作流自动化”的关键拼图单纯把这些事件接出来就已经很有用了但Hooks真正厉害的是可以组合。比如你可以让PostToolUse里跑完lint后自动写一份报告文本再让Claude读这份报告修正代码也可以让PreToolUse检测到危险命令后直接进入一个“必须人工输入令牌才放行”的流程。这种方式跟传统CI里的Git钩子很像但它是专门为Agent行为设计的视角完全不一样——Git钩子是管“这个提交要不要发生”Claude Code的Hooks是管“让AI自主时约束哪些红线绝对不能越过”。我自己用下来最大的感受是Hooks让Claude Code从一个“聊天框里的智能体”变成了“一条产线上能自动流转的工序”。你人不在工位上它也照常按规则干活违规了它会停下来等——这才叫把自动化做扎实了。2. 反向工程Hooks的完整事件清单与触发时机2.1 决策型事件PreToolUse怎么做到“一票否决”PreToolUse是Hooks体系里权力最大的事件它在Claude Code准备执行任意工具前触发。这里的“工具”不只是读文件、写文件还包括Bash、WebSearch以及你通过MCP接入的所有外部工具。你的脚本能拿到本次要调用的工具名、传入参数、还有Claude的意图上下文。在这个事件里做决定不是靠“返回提示文本”而是靠退出码和decision字段。退出码为0等于放行退出码为2Claude会直接放弃这次工具调用。你还可以在stdout里输出一段理由这段理由会出现在对话流里让Claude知道为什么被拒。这个“reason”字段不是随便给你的它能让AI在下一次调用时调整参数——比如你禁止它用rm -rf它会立刻改成先移动到.trash目录再去删。这种闭环反馈是单纯拦截做不到的。2.2 事后通知型事件Stop、PostToolUse、SessionStart等非阻断事件里最常用的是PostToolUse和SessionStart。PostToolUse在每个工具执行完成后触发你能拿到退出码、标准输出、标准错误、执行时长这些元数据。我通常用它跑lint、测速、记录变更痕迹这些活干完不需要打断主流程。SessionStart则是每次启动新会话时触发一次非常适合做环境初始化——把当前分支名、最近变更文件、项目规范文件内容一股脑喂给Claude让它开局就带着上下文干活不用每次靠提示词重复灌输。Stop事件则是Claude完成一轮完整响应、把主控权交还给你时触发这时候适合做“阶段汇报”把这一轮改过的文件列表、执行过的命令汇总成一条信息推给你。2.3 事件执行的顺序与嵌套关系理解事件顺序很重要否则你会写出互相打架的脚本。一个典型的完整响应周期是你先发出一条人类消息触发UserPromptSubmitClaude开始响应期间可能会依次调用多个工具每个工具调用前后分别触发PreToolUse和PostToolUse如果Claude中途进入子Agent还会触发SubagentStop响应结束触发Stop。会话太长被压缩时会先触发PreCompact这时候你可以把关键状态存到外部文件免得压缩后失忆。嵌套关系的坑在于如果你的Hooks脚本内部又调用了Claude Code的命令行界面极容易造成递归触发。比如PostToolUse里你执行claude -p 整理这段代码”这个子进程又会触发PostToolUse直接导致事件风暴。我在早期脚本里就吃过这个亏稍后章节详细说解决方案。3. 从零配置Hooks的配置文件结构与快速上手3.1 配置写在哪个文件里Claude Code的Hooks配置放在.claude/settings.json项目级文件里也可以放到用户级配置文件前者随仓库走、适合团队共享规则后者绑在你个人环境上、适合个人习惯。无论放哪一级结构完全一致。{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 scripts/guard_bash.py, timeout: 10 } ] } ], Stop: [ { hooks: [ { type: command, command: node scripts/report_stop.js } ] } ] } }matcher只有部分事件需要它是用来按工具名做精准匹配的。比如Bash、Edit、Write都是工具名你不设置matcher就代表拦截全部工具调用实际操作中会造成很多误伤所以建议能加就加。3.2 第一个必会案例每次写完代码自动做静态检查先用一个最实用的案例感受整个链路。我要求“Claude每次写完文件后自动对该文件跑ESLint”配置如下{ hooks: { PostToolUse: [ { matcher: Write|Edit|MultiEdit, hooks: [ { type: command, command: node scripts/lint_after_edit.js } ] } ] } }lint_after_edit.js里做的事情很简单从标准输入读取JSON事件对象拿到tool_input.file_path字段然后调ESLint的Node API跑一遍。这里有个关键细节Claude Code通过stdin把事件数据以JSON格式传给脚本不是你脚本里自己去找文件路径。很多新手脚本写不对就是因为完全没读stdin以为环境变量里有这些信息。const fs require(fs); const { ESLint } require(eslint); let input ; process.stdin.on(data, chunk input chunk); process.stdin.on(end, async () { const event JSON.parse(input); const filePath event.tool_input.file_path; if (!filePath || !filePath.endsWith(.js)) process.exit(0); const eslint new ESLint({ fix: false }); const results await eslint.lintFiles([filePath]); const errors results.flatMap(r r.messages.filter(m m.severity 2)); if (errors.length 0) { console.error([lint] ${filePath} 有 ${errors.length} 个错误请修复后再继续); // 这里故意不exit非0因为PostToolUse的失败不会阻断Claude // 但我把错误信息打到stderrClaude能看到并主动修复 } });注意PostToolUse里脚本退出码非0只会记录错误不会终止Claude。它就是“通知”语义。如果你真的想“代码不合格就不许继续”那得把检查放到PreToolUse里拦截下一个Write动作或者放到Stop事件里判断“如果你这轮改完还有错误下一轮我不放行”。这个思路差异特别重要。3.3 自己动手验证Hooks是否生效的快速路径配置写好后怎么知道有没有生效最直接的办法是在事件脚本第一行加个日志落盘#!/bin/bash echo $(date) $0 received /tmp/claude_hooks.log cat /tmp/last_event.json配合cat /tmp/last_event.json把stdin的完整事件数据存下来然后随便让Claude执行一个工具操作再去看这两个文件。如果文件没生成说明配置压根没加载多半是settings.json路径错了或者JSON语法有误。如果文件生成了但内容不对说明你的事件理解有偏差再看matcher匹配对不对。这一步搞定了Hooks的基础功力就有了后面所有复杂玩法都是在这个链路上加逻辑。4. 自定义工作流自动化实操三个完整的场景打磨4.1 场景一自动化更新Changelog与版本发布记录这个场景适合团队协作或者长期维护的开源项目。痛点很常见AI改了一堆代码提交信息写得飞起但CHANGELOG.md永远忘记更新发版前只能人工回忆两周之内干了啥。用Hooks可以在每个Stop事件里自动收集本轮变更。我的做法是写一个update_changelog.py在Stop触发时读取上一个git tag之后的提交记录结合Claude写入的变更描述文件自动整理成今天的更新条目插入到CHANGELOG.md头部。关键点在于不要让脚本直接改写文件——我让脚本生成一份CHANGELOG.tmp.md然后通过llm提示Claude去整合格式。这样既保持了可读性又避免了“脚本直接改文档Claude不知道下次又乱改”的信息割裂。完整思路Stop事件 → 执行git log收集提交 → 生成新增内容 → 写进临时文件 → stdout里提示“已生成新的changelog草案是否需要合并进CHANGELOG.md”。由于Stop事件不会阻断Claude所以这个提示会作为上下文给到Claude它下一轮就能主动执行合并操作。一个人机协作的闭环就出来了。4.2 场景二危险命令的“双人复核”闸门这个是我认为Hooks最能体现价值的地方。Claude Code在执行Bash命令时会询问你是否允许但当你选择--dangerously-skip-permissions模式时这个确认就没了。你可以用PreToolUse把它找补回来。我的实现是在PreToolUse里匹配Bash然后正则检查命令内容。命中危险模式rm -rf、git push --force、DROP TABLE等就输出一个封禁提示并退出码2直接拒绝执行。import json, re, sys danger_patterns [ r\brm\s-rf\b, r\bgit\spush\s.*--force\b, r\bdrop\stable\b, ] data json.load(sys.stdin) cmd data.get(tool_input, {}).get(command, ) reason 命中危险命令规则已阻止。请使用更安全的替代操作。 if any(re.search(p, cmd, re.IGNORECASE) for p in danger_patterns): # stdout的内容会作为reason展示给Claude print(reason) sys.exit(2) sys.exit(0)还有个进阶玩法不直接无条件冻结而是“先冻结再放行”。我在脚本里对命中规则的危险命令生成一个一次性授权码同时通过企业微信机器人把“有人请求执行危险命令授权码是XXXX”推给指定负责人。负责人确认后把授权码告诉ClaudeClaude在下一次重试时把授权码作为环境变量传入命令脚本检测到配套授权码才放行。这就等于把一个纯AI的工作流硬化成了“双人复核”的合规流程。虽然这套实现复杂度高但对金融、运维场景来说它是实实在在能过审计的方案。4.3 场景三让Claude Code的阶段性结论主动“汇报”出来这个场景适合挂机跑长任务的人。以前我让它跑测试人只能守在那里刷新终端。用Hooks之后每轮Stop事件里我能拿到Claude刚刚的回复内容直接交给脚本解析出关键结论然后通过飞书/钉钉/微信机器人的Webhook推送到手机。脚本里只需要处理stdin里的stop_hook_active标志和response字段。因为Stop事件传进来的JSON里response是一段文本直接把这个文本Post到Webhook就是一个最朴素的“AI进度播报”。如果想做结构化就让Claude在回复里约定输出进度: 30% | 当前任务: 重构登录模块 | 阻塞: 无这种固定格式脚本再用正则提取。这个场景做完之后我实际使用体验变化非常大。原本干完活才发现出错的“事后沮丧”变成了每三分钟看一次手机就知道进度的“实时掌控”。特别是长夜挂机的批量任务早上起来翻推送记录就能完成工作总结不用再翻终端日志。4.4 把事件脚本本身纳入版本管理很多人会忽略这一点Hooks脚本是项目的一部分逻辑不是临时工具。我强烈建议把.claude/settings.json和所有hooks_scripts/目录纳入Git版本管理。一旦团队成员clone仓库Hooks规则自动生效不再需要口头传达“你记得跑lint啊”这种话。但这里也引出一个问题团队里不是所有人都信任AI自动改代码。所以我在仓库里额外写了一个HOOKS.md说明每个钩子是干什么的、如果觉得误拦截了可以怎么临时豁免。比如我的危险命令脚本里支持一个ALLOWLIST_FILE环境变量里面写可放行的命令正则清单。这样有不同风险偏好的同事可以自己维护自己的豁免规则不影响公共安全底线。5. 非对称问题手册Hooks落地过程中的那些坑5.1 问题速查表以下是我实际踩过、也在社区里见过的高频问题整理成速查表方便直接查。现象根因解决方案配置写了但事件不触发settings.json路径不对或JSON解析失败在脚本首行加日志落盘验证stdin是否收到数据脚本能跑但Claude看不到提示输出打到了stdout但没带Claude Code上下文标记确认输出的是纯文本reason或错误信息不要用console.log输出无关调试内容事件风暴、CPU暴涨Hooks脚本内调用了claude命令递归触发同一事件脚本里用环境变量CLAUDE_HOOK_RUNNING做开关已运行则直接退出中文路径或UTF-8内容乱码Windows下编码问题脚本统一用utf-8模式读写Bash脚本不要用系统默认GBK命令执行超时被kill默认timeout不足给每类hook显式设置timeout比如lint类给60秒PreToolUse想拦截但拦不住matcher写错或用了退出码1而非2PreToolUse阻断必须退出码2退出码1只代表“出错”而非“拒绝”5.2 环境变量、幂等性和超时这三个教训展开说说我觉得最重要的三个教训。第一环境变量的传递链。Hooks脚本执行环境是独立子进程它拿不到你shell里那些自定义别名和函数。我刚开始写脚本时在里面用了一个Shell别名结果跑得好好的脚本在Hooks里直接command not found。后来所有的PATH依赖都改成绝对路径或者在脚本开头source指定的环境文件。还有一个细节UserPromptSubmit事件触发时用户刚输入的那条消息不是通过argv传进去的而是从stdin的JSON里拿这个位置搞错就会导致你永远拿不到用户输入。第二幂等性设计。Hooks脚本被触发的频率比你想的高得多它必须能重复执行且不产生副作用。有一次我在PostToolUse里写了“每次改完文件就append一行时间戳到日志”看起来没问题但Claude喜欢连续多次写入同一文件导致日志里全是重复行。后来所有日志都改成基于“事件唯一ID”去重脚本执行前先检查ID是否存在存在就直接跳过。第三超时时间的艺术。默认超时是60秒但lint大项目时不够用。我一开始把超时设到300秒发现一个问题Claude执行Bash命令本身也有一套内部超时逻辑如果我的hook在那边等待太久Claude会认为工具执行失败并自行处理反而触发误判。最后我把耗时操作拆成两个阶段hook先快速落一个“开始处理”的标记文件真正的重活放到PostToolUse里异步执行hook本体只做通知不等待。这样既拿到了完整结果又不会拖垮主流程。5.3 不要让Hooks变成新的“确认地狱”顺带说个理念层面的问题。Hooks可以拦截很多危险动作但这不代表你应该拦截一切。我看过有些团队把PreToolUse写得密密麻麻读文件要拦、写文件要拦、跑命令更要拦最后Claude Code每走一步都被自己的约束脚本打回来使用体验跟手动敲确认没什么两样甚至更糟——因为手动确认至少还有上下文脚本拦截时Claude常常一头雾水。我的原则是只拦截“不可逆”和“高成本”的动作。删文件、强推代码、清空数据库这种必须拦写普通源文件、跑一次测试这种就让AI放手去做出了问题用PostToolUse追踪和提示。自动化是为了提高信任度不是用一堆规则把Agent锁死这个边界得靠每个用户根据自己的场景拿捏没有放之四海皆准的配置。回过头来看Hooks机制是整个Agent化工作流里最容易被低估的一部分。大家习惯把注意力放在模型多强、提示词多妙上但真正让AI从“玩具”变成“工具”的恰恰是这些不起眼的、能定规矩的脚本接口。我现在跑项目的时候Claude Code是一个可以在安全边界内自主决策的执行单元而Hooks就是那张写着边界在哪里的图纸。你把它画清楚AI放心干你也能安心放手。这就是我为什么愿意花这么多篇幅写它——不是因为它新而是因为它真的改变了人跟AI协作的方式。
初始注册信令流程详解：从RRC连接到NAS鉴权的完整交互与排查)
