Claude Code Hooks完整教学：Event、Matcher、Handler三层架构详解

为什么你需要Hooks：从提醒纸条到强制机制

如果你用过Claude Code，一定有过这样的挫折：明明在CLAUDE.md里白纸黑字写了「改完代码一定要跑测试」，或者「执行危险的Git指令前要先停下来确认」，但AI还是时不时忘记照做。

这不是你的错，也不是AI偷懒。问题的根源在于CLAUDE.md的本质——它更像是给AI的一张提醒纸条。它提供指示，模型会「尽力」遵守，却不保证每一次都乖乖执行。因为CLAUDE.md的生效方式是让模型自己去读、自己去判断什么时候该遵守，这中间存在天然的随机性。

如果你希望有一套更强制、更稳定的机制，那就是Hooks登场的时候了。Hooks是Claude Code里一套由软体层面掌控的确定性（Deterministic）机制：只要设定的时间点一到，软体就会直接介入强制执行，而不是靠模型自己判断要不要做。

可以把Hook想象成便利商店的自动门——背后有一套绝对会执行的死板规则，只要有人走到感应区，门就立刻打开，没有任何商量空间。

三种工作该放在哪：对话、CLAUDE.md还是Hook

理解Hook的价值，关键是知道它和其他机制的分工。原视频给出了一个清晰的判断框架：

• 一次性任务：直接在对话里讲就好，不需要任何配置。
• 专案通用的规则和大方向：适合写在CLAUDE.md里，让模型当作参考。
• 特定时机一到就绝对必须严格执行、且你一点都不想承担被AI忘记风险的动作：这时候就该做成Hook。

Hook与CLAUDE.md最关键的差别在于「谁来负责启动」。CLAUDE.md依赖模型自己判断，而Hook是由Claude Code这套软体在背后强制触发。这个差异决定了二者的可靠性等级完全不同。

Hook的三层架构：Event、Matcher、Handler

一份真正的Hook设定档其实只是用JSON格式写的指令，通常放在专案资料夹里的.claude/settings.json档案中。看起来密密麻麻，但你不需要死背，也不用一行一行手打，只要搞懂三层架构就够了。

以一个「检查程式码有没有语法错误」的Hook为例，它的分工非常明确：

Event：什么时候发生

第一层叫Event，决定这个Hook在什么时候启动。在语法检查这个例子里，Event会设定成PostToolUse，意思是在Claude刚调用完工具的那个瞬间启动。

Matcher：拦截哪个操作

第二层叫Matcher，用来设定筛选条件。Claude工作时会调用非常多种工具，不可能每次都把Hook叫出来。Matcher的作用就是告诉系统，在这么多操作里要筛选、拦截哪些具体动作。语法检查的例子中，Matcher会锁定「修改程式码」这个动作。

Handler：最后做什么

第三层叫Handler，是真正采取行动的地方。当前面条件都符合，就由它来决定调谁出来做事。这个例子里，Handler会把你电脑里的语法检查脚本叫出来，自动把错误抓出来。

总结成三个问题：Event决定什么时候发生，Matcher决定拦截哪个操作，Handler决定最后做什么动作。这就是Hook最核心的运作逻辑。

Hook的设定档存放在专案的 .claude/settings.json 中，这个档案采用标准 JSON 格式，可以手动编辑，也可以直接要求 Claude Code 帮你生成。JSON（JavaScript Object Notation）是一种轻量级的资料交换格式，用大括号 {} 包裹键值对、用中括号 [] 表示阵列，人类可读性高，也便于程式解析。一个专案可以定义多个 Hook，彼此独立运作，互不干扰。值得注意的是，Hook 设定有专案层级（project-level）与使用者层级（user-level）之分：放在专案资料夹里的设定只影响该专案，而放在使用者主目录下的全局设定则对所有专案生效，适合那些无论在哪个专案都需要执行的安全防呆规则，例如永远不提交包含 API 金钥的档案。

十个核心Event：按工作阶段理解

Claude Code里目前有多达31种Event，听起来吓人，但按系统工作阶段分类，抓住最核心的几个就够了。

第一阶段：系统启动与接收指令

SessionStart在你开启对话的瞬间触发，无论是开新对话、接续记录还是输入clear清空画面都会启动。GitHub上热门专案Superpowers就利用它，强制AI在用户一开启对话时就载入Superpowers这项Skill，专门对付AI载入Skill的随机性。

UserPromptSubmit在你按下Enter送出Prompt时触发。开源专案Claudemem用它解决AI跨对话失忆的问题——拦截你送出的提问，在背后呼叫Worker Service程式，先从资料库捞出相关记忆再塞给Claude Code，确保每次对话前都带上相关记忆。

第二阶段：准备修改前的安全防呆

PreToolUse在工具准备被调用前、还没真的执行的空档触发，非常适合做安全防呆。有专案用它挡掉危险指令——检查Claude的Tool Call内容，一旦发现git reset --hard这种会洗掉代码的指令，或危险的git push，就立刻拦截、当场中断，并告诉Claude没有权限执行。

第三阶段：执行完成后的快速验收

PostToolUse在工具成功执行之后触发，适合快速验收。前端设计Skill「Impeccable」就在这里把关：Claude一改完UI档案就立刻启动纠错。比如发现图片标签的连结是空的，或字体颜色对比值不符合标准，它都会扫描出来并要求Claude修好。

第四阶段：任务结束与特殊状况

Stop在这一回合对话完全结束时触发。Impeccable把排版、节奏、配色这种比较深度的美感检查刻意留到Stop阶段，因为它会把整个工作阶段改过的所有档案统整起来做一次总体检，避免每改一行就跑一次拖慢开发速度。Cross Model Review的做法也类似——利用Stop Event让Claude写完Plan后呼叫Codex进行Peer Review。

这个阶段还有几个处理特殊状况的Event：

• Notification：通知提醒，可设成桌面通知或提示音，让你在Claude背景工作时去忙别的事，需要确认时再被叫回来。
• SubagentStart / SubagentStop：控管Sub-Agent工作品质，开始前补上规则要求，做完后检查产出有没有达标。
• PreCompact：对话太长时Claude会自动浓缩内容，如果每次浓缩都漏掉关键决策或进度，可以用它在浓缩前先把重要资讯保存下来。

新手只要先记住四个最常见的Event：SessionStart（对话开始/恢复）、PreToolUse（准备用工具前）、PostToolUse（工具执行后）、Stop（这一轮工作结束时）。

Matcher与五种Handler类型

Matcher的工作很简单：从所有可能的动作里挑出这个Hook真正需要处理的目标。比如Matcher设成Edit|Write，就代表只关心修改档案的动作；还能再加if条件细化，例如只检查副档名是.ts的代码。

Handler目前有五种类型，分别适合不同场景：

• Command：最常用。让Hook直接执行电脑上的指令或脚本，比如改完代码自动跑lint检查、用Prettier整理格式，或在执行指令前先跑检查挡下危险操作。
• HTTP：把Hook收到的资料传到外部服务，比如工具执行失败时自动把错误讯息送到Slack。
• MCP Tool：直接使用已连线的MCP工具，比如每次开工自动从Jira抓回今天的任务。
• Prompt：呼叫另一个AI，把事件资料连同检查条件交给它。这个AI只根据收到的资料回答，不会自己打开档案或搜寻。适合检查Commit讯息格式是否符合团队规范。
• Agent：运作更完整，叫起一个Subagent，它可以先读档案、搜寻代码、执行测试，查清实际状况后再回传验收结果。

简单区分：Prompt是拿着现有资料直接回答，Agent可以先调查再回答。

要注意，每个Event支援的Handler类型不同，有些可用Prompt和Agent，有些只能用Command、HTTP。实际设定前，记得请AI查一下官方文件确认搭配。

Prompt Handler 与 Agent Handler 的核心差别值得进一步说明。Prompt Handler 本质上是一次「无工具的 LLM 呼叫」：系统把事件资料（例如 Tool Call 的参数）组成提示词，直接送给模型，模型只能根据收到的文字内容回答，无法主动读取档案或执行指令。这使它速度快、成本低，适合格式验证这类纯文字判断任务。Agent Handler 则会启动一个完整的 Subagent，它拥有自己的工具调用能力，可以读档、搜寻、执行测试，用真实调查结果作为判断依据，更适合「检查 UI 渲染是否符合设计稿」或「验证测试是否全数通过」这类需要实际操作才能下结论的场景。选择哪种 Handler，关键问题是：「只看现有资料就够做判断，还是需要主动去查？」

实战：让AI帮你建立第一个Hook

要请AI建立Hook，只要讲清楚两件事：什么时候启动，以及启动后做什么。

案例一：Git提交前检查敏感资料

可以直接对Claude Code说：「请帮我在专案设定里建立一个Hook，每当准备执行git commit时，先检查这次要提交的内容。如果包含.env档案或疑似API金钥，就把提交挡下来并告诉我是哪个档案有问题；没发现就正常继续。」

Claude建立的这个Hook使用PreToolUse Event，Matcher锁定Bash，Handler叫起一支名为Git Commit Secret Guard的检查程式。虽然每个Bash指令执行前都会叫起它，但程式会先判断是不是git commit，无关就安静结束。实测时，包含.env档案的提交会被当场拦下，移除敏感资料后再提交就正常通过。

案例二：文章完稿后检查AI味

这个案例需要「直觉判断」。作者希望每次Claude写完文章，Hook都能检查里面还有没有AI味。他对Claude说：「每当你写完一篇Blog文章准备结束工作时，启动一个Agent读取刚产出的文章，呼叫用来去除AI写作痕迹的Humanizer Skill检查有没有AI味。有问题就把段落和原因交回来请你修改，检查通过才能结束工作。」

这个Hook使用Stop Event，用Command Handler执行一支Humanizer Gate程式。程式本身不判断AI味，而是找出修改过且还没通过检查的文章，要求Claude开Agent审查。

建立后必须检查两件事

第一，触发范围够不够精确。范围设太大会在很多无关操作中被叫起，浪费时间也打断工作。所以Matcher要先缩小范围，Handler里再检查更细的条件——这就是为什么Git Hook先用Matcher锁定Bash，再由程式判断是不是git commit。

第二，Stop Hook有没有设定结束条件。Stop Hook每次阻止Claude结束都会要求它继续工作，如果没有明确的通过条件，就可能一直退回、修改、重新检查陷入死循环。Humanizer Gate的做法是记录当前版本是否已通过，通过后只要文章没再改动下次就直接放行；连续三轮没通过就停止退回，交给人工确认。

Stop Hook 的死循环风险是实务中最常踩到的坑，值得多加说明。当 Stop Hook 判断工作不符合要求时，它会阻止 Claude 结束这一轮对话，并要求继续修改。如果检查逻辑本身有缺陷——例如判断条件过于严格、或没有记录「已通过」状态——Claude 可能进入「修改 → 检查未通过 → 再修改 → 再检查未通过」的无限循环，持续消耗 token 与 API 费用。因此，一个健壮的 Stop Hook 应至少具备三个保障：（1）明确的通过条件，让系统知道什么状态下可以真正放行；（2）状态记忆机制，避免重复检查已通过的版本；（3）最大重试次数上限，超过阈值后停止退回并转交人工处理，防止无止尽的自动循环。

Codex用户的两个关键差异

Hook的判断方式对Codex用户同样适用，但两边支援的Event和Handler不完全相同，所以Claude Code的设定不能直接复制到Codex。

第一个差异是Event数量：Claude Code有31种，Codex只有11种。不过PreToolUse和Stop两边都支援，所以上面两个案例的基本做法都能搬到Codex。

第二个差异是Handler：Claude Code支援Command、HTTP、MCP Tool、Prompt、Agent五种，Codex目前真正会执行的只有Command。但这不代表Codex做不了需要AI判断的流程——像Humanizer Gate本身就是Command Handler先执行检查程式，再要求主Agent呼叫Skill完成审查，同一需求通常还是做得到，只是串接方式不同。

最简单的做法：把想解决的问题直接告诉Codex，请它按目前支援的格式重新建立，不要直接复制Claude Code的设定。

从一个小问题开始

到这里，你应该对Hooks有了完整理解：它能在固定时机自动替你执行检查、通知或防呆。Event决定什么时候启动，Matcher决定哪些情况需要处理，Handler负责启动后做什么。

实际建立时不需要自己备设定或手写程式。先找出一件你经常提醒AI、而且每次都发生在固定时机的事情，把「什么时候启动」和「启动后做什么」讲清楚，让AI帮你建立第一版，再确认触发范围和结束条件。

可以从一个很小的问题开始，比如提交代码前检查金钥。只要这件事会重复发生、适合在固定时机自动处理，它就值得做成Hook。把这些重复提醒一个个交给Hook，你会发现很多原本需要自己记得、反复确认的事情，慢慢变成工作流程里自动发生的一部分——而你可以把注意力留给真正需要自己判断的事情。