1. Hooks到底是什么一次事件订阅机制的再发明如果你用过Git的Webhook、用过前端的生命周期函数那么Claude Code Hooks的定位你一猜就中它是在Claude Code运行的关键节点上插入你自己写的脚本让外部程序在特定时机被自动触发。说得再直白一点。Claude Code本质上是Anthropic的命令行编程代理它帮你读写文件、执行命令、调用各种工具。但你有没有遇到过这样的场景它刚改完代码你想让它自动跑一遍lint它准备执行一条危险命令你想在它动手之前拦下来检查一下上下文快满了要压缩你担心它忘掉关键约定。这些事靠在对话里打字叮嘱是很不靠谱的因为Claude不一定每次都会自觉地做而Hooks就是用来把这些规矩变成硬性机制的。我第一次接触这个功能是在一次团队内部讨论里。当时我们几个人都在用Claude Code写业务代码总有人抱怨说它把测试跑挂了它改了不该改的文件它快把上下文用完了还在聊废话。最初我们尝试用system prompt压规范但prompt这东西终究是软约束它有时候就是会忘。后来有人提了一句Claude Code支持Hooks可以在工具执行前后挂脚本。当天下午我们就试了试效果非常直接——代码提交前强制走检查、危险命令被自动拦截、上下文压缩前自动存档。从那时候起Hooks就成了我所有Claude Code工作流里最依赖的机制之一。这篇内容适合谁看正在用Claude Code做开发的人、想给团队定一套AI编码规范的人、以及对给编程代理加安全护栏这件事感兴趣的人。我下面会把这套机制的核心事件、配置语法、实际脚本、坑和排查方法完整过一遍争取你看完就能在自己的项目里搭起来。2. 设计思路解析为什么Hooks能把软提醒变成硬约束2.1 没有Hooks之前我们靠什么约束AI行为先说一个基础事实Claude Code在执行任务时本质上是模型在一个循环里自主决策——它决定下一步调用哪个工具、用什么参数、怎么处理返回结果。这个循环对你来说像黑盒你只能看到对话输出。想干预它的行为最土的办法是在prompt里写规则你执行任何删除操作之前必须确认你每次改完文件要自己跑一遍测试。问题在于模型对prompt的遵循是概率性的不是确定性的。状态差、上下文乱、指令被长对话稀释之后它就可能漏掉某条规矩。尤其危险的是涉及文件删除、批量修改、git强推这类不可逆操作漏一次就够你难受的。还有一类需求是提示词根本管不了的比如工具执行完之后我想自动把结果同步到外部系统上下文压缩之前我想把当前任务状态写进一个固定文件会话结束之后我想给监控平台上报一条记录。这些动作本来就不属于模型的能力边界它自己不会主动去做只能靠外部钩子。2.2 Hooks介入的是哪些关键节点Claude Code的Hooks把一次完整的对话/任务生命周期切成若干事件节点你在每个节点上都可以挂一个或多个命令。官方定义的事件主要包括这些事件名称触发时机典型用途PreToolUse工具调用执行之前拦截危险命令、校验参数、做权限审批PostToolUse工具调用完成之后自动跑测试、lint、同步结果UserPromptSubmit用户提交新提示词时检查输入内容、注入项目规范PreCompact上下文即将压缩之前保存关键状态、输出摘要、防止信息丢失NotificationClaude发送通知时把通知转给IM机器人或邮件Stop一轮生成结束时通知、记录、触发后续流水线SubagentStop子代理Subagent完成时汇总子任务结果、做质量检查SessionStart新会话开始注入团队规范、加载项目元信息SessionEnd会话结束清理临时文件、上报统计这些事件的粒度设计得很有意思。PreToolUse和PostToolUse是覆盖面最广的两个钩子几乎能覆盖所有工具调用SessionStart和SessionEnd则帮你把整个会话的生命周期管起来。它们合在一起等于给你提供了一整套可编程的代理运行时钩子。2.3 输入、输出和副作用Hooks的运行模型每一个Hook本质上就是你指定的一个外部命令Claude Code执行到对应事件时会把这个命令跑起来并且往它的标准输入stdin里塞一段JSON里面包含当前事件、上下文和工具调用信息。命令的stdout返回内容会被Claude Code读取并在PreToolUse等特定事件里作为额外上下文交给Claude模型。这个模型和前端的Webhook非常像事件源负责广播订阅者负责处理唯一的不同是它还允许订阅者的输出反作用于事件源。也正是这个设计让Hooks具备了软提醒变成硬约束的能力。后面我会详细写具体的JSON结构和返回格式。3. 核心细节解析事件类型、匹配规则与配置语法3.1 PreToolUse把能不能干变成可编程决策PreToolUse是我用得最多的钩子。它在工具被执行之前触发相当于一道门禁。它的设计目标是你可以编写任意检查逻辑然后输出一个JSON告诉Claude Code放行还是拒绝。最常见的用法是拦截Bash工具里的危险命令。你可能会问matcher能不能直接匹配命令内容答案是不能。matcher只能匹配工具名称比如Bash、Edit、Write命令具体内容要由你的脚本自己去看stdin里的JSON参数。所以在写检查脚本时解析tool_input里的命令字符串是重头戏。我一般会在脚本里维护一份危险命令正则清单比如rm -rf /、git push --force这类命中就直接拒绝并附上一段人话说明。PreToolUse返回阻断的JSON格式长这样{ hookSpecificOutput: { hookEventName: PreToolUse, permissionDecision: deny, permissionDecisionMessage: 被本机安全规则拦截禁止对根目录执行删除操作, permissionDecisionReason: matched_dangerous_command } }注意permissionDecision目前常用的值是allow和deny用途就是放行或拒绝permissionDecisionMessage会作为工具调用被拒绝的反馈给到Claude。也就是说Claude会知道自己做的事被拦了并且能看到你写的理由这个反馈质量直接影响它下一步的行动——它可能会换个安全的方式继续完成任务。一个需要特别提醒的细节PreToolUse的Hook如果进程退出码非零或者输出JSON无法解析Claude Code出于安全考虑通常也会中止这次工具调用。所以脚本自身一定要稳定别因为一个解析小bug把正常操作全拦了。3.2 PostToolUse工具执行后的自动质检与结果同步PostToolUse在工具调用完成后触发输入里除了基础信息还包含工具的执行结果。你可以在脚本里做质量检查、结果汇总、状态流转或者把结果转发给其他系统。举一个非常实际的例子团队里规定每次Claude修改了JavaScript文件必须自动跑一遍ESLint。配置好PostToolUse的Edit钩子后Claude每次改完文件lint脚本就会被自动执行根本不依赖Claude记得这件事。如果lint没过脚本往stdout输出错误摘要Claude会在下一步看到这些信息然后自己决定去修复。这就是硬约束的最好体现你不再需要苦口婆心地提醒它。PostToolUse的stdout写入内容会被Claude作为上下文读取所以在脚本里输出过多无关日志会导致上下文浪费。我见过有人把一堆调试日志都打到stdout上结果下一轮对话的上下文白白多了一大截。正确的做法是只在stdout输出需要让Claude知道的关键结论其他日志一律写到stderr或日志文件。stderr不会被当作上下文传给模型但会进入Claude Code的debug日志排查问题时再去看。3.3 PreCompact上下文压缩前的保命存档这是很多人忽略但价值极高的事件。Claude Code在上下文快要塞满的时候会自动执行压缩把历史对话做摘要归纳腾出空间。但是压缩本质上是遗忘的过程一些不明显的细节可能会在摘要里丢失。PreCompact钩子的作用就是给你一个机会在压缩发生前执行一段代码把当前任务的关键状态存下来。你可以把正在进行中的任务清单、已经完成的步骤、下一步计划、重要约定等写到本地文件同时把摘要输出到stdout。这样Claude在压缩之后仍然能读到这些关键信息相当于在压缩的悬崖边缘加了一道保险。这个钩子特别适合长任务场景。我自己在写大型重构任务时经常遇到的情况是做了很久上下文越长越糊涂有时候Claude自己都忘了最开始定的几个目标。后来我在PreCompact里写了个脚本自动把当前目录下的TODO状态、最近修改文件列表、以及一个固定格式的任务进度文本输出出来。效果非常明显压缩之后的对话还保持着不错的连贯性。3.4 其他重要事件SessionStart、Stop、SubagentStop、Notification这些事件各有各的用武之地。SessionStart新会话开始时触发。我习惯在这里挂一个脚本自动读取项目根目录的AGENTS.md或team-rules.json把团队编码规范注入到stdout里让Claude在会话一开始就明确规矩。这比在交互时靠人肉提醒靠谱太多而且坐在新环境里的人也不会忘记加载规范。Stop每一轮生成结束触发。可以用来发消息通知、记录执行日志。很多团队用它接IM机器人Claude一有阶段性输出群里就能看到进度。SubagentStopClaude Code在复杂任务中会创建子代理来并行处理子任务子代理结束时触发这个事件。可以在这里做结果汇总或者对子代理的输出做质量校验。Notification当Claude发送通知时触发比如错误通知。可以挂一个脚本把通知转发到飞书、钉钉、Slack之类的系统。每个事件都有自己的matcher语义。SessionStart可以匹配用户输入的提示词内容Notification匹配通知类型PreToolUse和PostToolUse匹配工具名称。理解matcher是配置好Hooks的前提。3.5 配置语法settings.json和claude hook命令Hooks的配置位置有用户级和项目级两档用户级全局配置在~/.claude/settings.json项目级配置在项目里的.claude/settings.json。项目级配置会被提交到版本库团队成员拉下来就自动生效这个特性非常方便团队统一规则。settings.json里Hooks的写法{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 scripts/hooks/guard.py } ] } ], PostToolUse: [ { matcher: Edit|MultiEdit|Write, hooks: [ { type: command, command: bash scripts/hooks/lint.sh } ] } ] } }也可以用命令行子命令来管理日常操作更顺手# 添加一个Hook claude hook add PreToolUse --matcher Bash --command python3 scripts/hooks/guard.py # 查看当前所有Hook claude hook list # 删除指定Hook claude hook remove PreToolUse --matcher Bash --hook-id 0这里有两个格式细节值得记一下。第一matcher支持正则表达式。比如Edit|MultiEdit|Write就能同时匹配三个写文件类工具。正则要写对写错了不会报错只会静默不触发。排查Hook不生效时第一件事就是回头检查matcher正则是否真的能匹配上。第二一个事件下可以配置多个命令它们会按顺序执行命令的编号就是hook-id。各个命令的输出都会合并进上下文中。如果只想让某一个命令生效可以在配置里给命令加hookId: 0之类的字段或者在删除时用--hook-id指定。4. 实操过程与核心环节实现从零搭一套防手滑钩子系统4.1 场景设定和方案规划我拿一个具体的团队场景来演示这样比空谈配置更有参考价值。假设业务是一个前端仓库团队用Claude Code辅助编码想要实现四条硬规矩任何rm -rf、git push --force、git reset --hard、生产环境部署命令在Bash执行前都要被拦截。Claude每次编辑或创建JS/TS文件之后自动跑一次ESLint和TypeScript检查失败的信息要反馈给Claude。上下文快压缩之前把当前任务进度存档到一个固定文件docs/session-state.md。每一轮生成结束后往终端打印一条耗时统计方便肉眼观察效率。这四条分别对应PreToolUse、PostToolUse、PreCompact、Stop四个事件。方案规划如下事件脚本职责PreToolUse(工具: Bash)scripts/hooks/guard_bash.py解析命令命中黑名单即拒绝PostToolUse(工具: Edit/Write/MultiEdit)scripts/hooks/run_quality_check.sh检测到前端源码变更执行lint和tscPreCompactscripts/hooks/save_state.py生成任务进度摘要写入文件并输出到stdoutStopscripts/hooks/trace_stop.sh读取时间戳输出本轮耗时4.2 第一步写PreToolUse的命令守卫脚本这个脚本要读取stdin里的JSON。Claude Code传给Hook的JSON结构大致如下{ session_id: abc123, transcript_path: /path/to/transcript.jsonl, cwd: /home/user/project, hook_event_name: PreToolUse, tool_name: Bash, tool_input: { command: rm -rf node_modules } }Python脚本可以用标准库直接解析#!/usr/bin/env python3 import json import re import sys DANGEROUS_PATTERNS [ r\brm\s-[a-zA-Z]*r[a-zA-Z]*f?\b, r\bgit\spush\s--force\b, r\bgit\sreset\s--hard\b, r\bkubectl\sdelete\b, r\bdocker\ssystem\sprune\b, ] def main(): raw sys.stdin.read() try: payload json.loads(raw) except json.JSONDecodeError: print(ERROR: unable to parse hook input, filesys.stderr) sys.exit(1) tool_input payload.get(tool_input, {}) command tool_input.get(command, ) allowed True deny_reason for pattern in DANGEROUS_PATTERNS: if re.search(pattern, command): allowed False deny_reason fmatched dangerous pattern: {pattern} break if allowed: # 放行的输出不需要额外写JSON正常退出即可 sys.exit(0) else: result { hookSpecificOutput: { hookEventName: PreToolUse, permissionDecision: deny, permissionDecisionMessage: 命令触发安全规则已拦截请改用更安全的方式完成如需删除请先列出明确文件清单, permissionDecisionReason: deny_reason } } print(json.dumps(result)) sys.exit(0) if __name__ __main__: main()几个容易踩的坑我在写这个脚本时都撞过这里一并说了。第一正则里的rm -rf匹配要留个心眼。命令可能是rm -rf也可能是rm -fr参数顺序不同。所以我的正则写了-[a-zA-Z]*r[a-zA-Z]*f?这种宽松匹配宁可多拦一点也不要放过去。第二判断为放行时进程退出码一定要是0不需要往stdout输出任何JSON。因为PreToolUse的Hook如果输出内容会被当作工具调用的附加上下文反而浪费。第三判断为拦截时我给的是deny而不是直接让进程非零退出。这样反馈信息更规范Claude也能清楚地看到被拒的原因从而自动调整策略。4.3 第二步配置PostToolUse自动质检脚本接下来配置PostToolUse。脚本的逻辑是如果本次工具调用涉及的文件路径里有.ts、.tsx、.js、.jsx后缀就执行npx eslint files和npx tsc --noEmit。这里有一个关键判断PostToolUse的JSON输入里tool_input包含文件路径信息。以Edit工具为例路径通过tool_input.file_path给出MultiEdit可能是tool_input.file_pathWrite则是tool_input.file_path。我建议脚本先做一次兜底不管工具名称如何先寻找输入JSON里所有像路径的字符串再判断后缀。这样即使工具字段有变动脚本也不容易失效。脚本写好后配置如下claude hook add PostToolUse --matcher Edit|Write|MultiEdit --command bash scripts/hooks/run_quality_check.sh脚本内部要控制输出的内容量。lint不过的时候输出摘要给Claude日志细节写到/tmp/hook-quality.log。Claude看到摘要后下一步很自然会去修复lint问题这就是一个闭环。4.4 第三步PreCompact存档脚本PreCompact的输入JSON里没有工具信息它只传递会话上下文快照的路径。脚本做的事情很简单读取当前工作目录下的关键状态文件生成一份人类可读的进度摘要写入docs/session-state.md同时把摘要打印到stdout。这个脚本不需要做很复杂的事把项目里约定的进度文件读出来稍作整理即可。实测下来只在压缩节点跑一次对性能的影响可以忽略。4.5 第四步Stop耗时统计Stop触发在每一轮生成结束时。我在脚本里维护一个临时文件记录上轮时间戳然后和当前时间做差输出本轮耗时。这个功能对日常观察Claude的工作节奏很有帮助尤其当它连续执行了长任务时耗时数据能帮你判断任务是否卡住。配置命令claude hook add Stop --command bash scripts/hooks/trace_stop.sh这里没有matcher表示所有Stop事件都触发。4.6 完整配置文件一览把上述四个事件汇总成一份项目级settings.json方便你整体复制修改{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 scripts/hooks/guard_bash.py } ] } ], PostToolUse: [ { matcher: Edit|Write|MultiEdit, hooks: [ { type: command, command: bash scripts/hooks/run_quality_check.sh } ] } ], PreCompact: [ { matcher: , hooks: [ { type: command, command: python3 scripts/hooks/save_state.py } ] } ], Stop: [ { matcher: , hooks: [ { type: command, command: bash scripts/hooks/trace_stop.sh } ] } ] } }注意PreCompact和Stop的matcher留空字符串时表示对该事件的所有触发都生效。如果你用的Claude Code版本较旧可能要求matcher字段必须存在但允许为空这个写法是兼容的。5. 常见问题与排查技巧实录5.1 加了Hook却不触发这是最让人头疼的问题。按照我踩坑的顺序建议按以下清单排查检查配置层级你在哪个目录执行的claude命令加载的就是哪个目录的项目配置。如果你在/home/user/project里配置了Hook却在/home/user目录启动Claude Code配置自然不生效。我建议优先使用项目级的.claude/settings.json提交到Git里成员在任何环境克隆后都生效。检查matcher正则matcher写错是最隐蔽的。matcher: Bash只能匹配工具名Bash不是命令内容。有些新手以为matcher是按命令内容匹配的怎么配都不触发就是这个原因。检查工具名拼写工具名称是大小写敏感的。Bash、Edit、Write、MultiEdit、Read这些都是固定名字不能自己发明。检查会话是否重启部分版本对配置变更的感知有延迟配置改了但当前会话没重载。确定了配置没错的话新开一个会话再试。5.2 Hook命令执行失败Claude的行为变得不可预测如果一个Hook脚本本身抛异常、进程非零退出、或者输出了一堆乱码JSONClaude的下一步行为会变得很奇怪。尤其是在PreToolUse里脚本崩溃可能导致所有工具调用都被拒绝整个会话寸步难行。建议处理策略脚本里对所有异常做兜底捕获try/except解析失败时打印一条清晰的错误信息到stderr并用退出码0正常结束。宁可这个Hook变成啥也没做也不要因为自己崩溃把会话搞挂。所有真正的错误一律写到/tmp/hook-debug.log排查时看这个文件。提示Hook自身的调试日志写在stderr里会进入Claude Code的debug日志。如果你需要查看Hook运行详情可以用claude --debug启动或者在脚本里把环境变量CLAUDE_CODE_DEBUG相关的输出打出来看看。5.3 stdout输出污染上下文PostToolUse和PreCompact的stdout内容会被当作上下文喂给Claude。如果你在脚本里不小心输出了大量噪数据上下文会被白白消耗。一个典型例子是脚本里用了某个框架的日志函数默认把日志打到stdout结果Claude下一轮就能看到一堆无关信息。我的经验是给脚本定一个铁律——stdout只输出明确需要让Claude知道的内容其他所有日志、调试信息、中间结果一律写stderr或者日志文件。在PostToolUse里如果lint结果为空脚本直接什么都不输出上下文干净利落。5.4 Windows环境下的编码和命令执行问题Windows上跑Hooks要额外注意编码问题。Claude Code传入的JSON里可能包含中文路径或中文命令如果脚本编码不是UTF-8解析会出乱码。我在Windows的PowerShell里跑Python脚本时就遇到过解释器默认编码和输入编码不一致导致的解析失败。解决方法是脚本开头统一sys.stdin.reconfigure(encodingutf-8)或者直接在chcp 65001切换到UTF-8代码页。命令执行也有个坑command字段里的命令是交给系统Shell执行的Windows下用的是默认Shell可能是PowerShell或cmd你在写命令时要考虑Shell语法差异。比如连接符在PowerShell和cmd里语义不同脚本里用到的管道、环境变量方式也要按目标Shell来。5.5 多命令顺序执行的结果合并同一事件下配置多个Hook命令时每个命令的输出都会按顺序累积。如果你想精细控制哪条输出被保留可以在配置中给命令设置hookId: 0之类的字段只有匹配的Hook输出才会进入上下文。这个特性在场景复杂时非常有用比如PreToolUse里既要跑文件安全检查又要跑命令黑名单你可以让安全脚本安静执行不输出让黑名单脚本最终输出决策。提示多个matcher在一个条目里配置时不同版本对它们是AND还是OR语义有过调整官方文档目前的表述是OR。为了少踩坑我习惯的做法是每个matcher单独一条配置不要在一个条目里塞多个matcher。逻辑清晰排查也方便。6. 最后分享几点实操体会这套Hooks机制我从接触到现在用了大半年最大的感受是它把AI编码从靠自觉变成了靠制度。以前跟团队成员强调一定要让Claude先跑测试再提交现在不需要唠叨了PostToolUse的钩子自动执行谁再用都能享受同样的保护。对于管理者来说这可能是Claude Code里最值得先投入研究的功能。我个人的建议是不要一上来就配置一大堆钩子。先从PreToolUse的Bash守卫开始这是最直接的安全收益然后加一个PostToolUse自动跑测试你会立刻感受到质量提升跑顺了之后再加PreCompact存档和Stop通知让长任务的连续性进一步改善。配置项不要追求多要让每一条都稳定、可靠、输出干净。如果你已经在自己项目里用了Hooks希望你的脚本别踩到stdout污染上下文和matcher拼错这两个最常见的坑。做AI自动化开发规矩最好写在机制里而不是写在提示词里。