Claude Code Hooks完全指南：自动化机制原理与实战配置

为什么需要 Hooks？CLAUDE.md 的局限

很多人用 Claude Code 时都会遇到一个困扰：明明在 CLAUDE.md 里写清楚了「改完代码一定要跑测试」「执行危险 Git 指令前要停下来」，但 Claude 却常常「忘记」照做。

原因在于，CLAUDE.md 本质上只是给 AI 的一张「提醒纸条」。它提供的指示，模型会尽力遵守，却不保证每次都乖乖照办。因为 CLAUDE.md 是让模型自己去读、自己去判断什么时候该遵守——这中间存在随机性。

技术上来说，CLAUDE.md 是 Claude Code 的项目级配置文件，本质上是一段会被注入到模型上下文窗口（Context Window）中的系统提示词。大语言模型的推理过程基于概率采样——即便指令明确写在上下文中，模型在每一步生成时仍然根据 token 概率分布做选择，这意味着它可能在复杂推理链中「遗忘」或「跳过」某些指令。这种现象在学术上被称为指令遵循的不稳定性（Instruction Following Instability），尤其在上下文变长、任务变复杂时更为明显。

如果你希望有一套更强制、更稳定的机制，这就是 Hooks 发挥作用的地方。这篇教程将系统拆解 Hooks 的运作原理、种类，并通过实际案例带你建立第一个 Hook。不论你是 Claude Code 还是 Codex 用户，Hook 的原理都是通用的。

什么是 Hook？确定性的自动化机制

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

Hook 与 CLAUDE.md 最关键的差别在于**「谁来负责启动」**：

• CLAUDE.md：让模型自己去看，依赖 AI 判断何时遵守
• Hook：是 Deterministic（确定性的），由 Claude Code 软件在背后强制掌控。只要设定的时间点一到，软件就会直接介入执行，不靠模型判断

在计算机科学中，确定性系统是指给定相同输入必然产生相同输出的系统，与之对应的是随机性或概率性系统。大语言模型的推理本质上是非确定性的（即使温度设为 0 也可能因浮点运算差异产生微小变化），而 Hook 的执行逻辑是写死在 Claude Code 客户端软件中的传统程序代码——if-then 逻辑、事件监听器、脚本调用——这些都是确定性的。这也是为什么 Hook 能保证「100% 会执行」而 CLAUDE.md 做不到。

因此可以这样归纳三种指令方式的适用场景：

• 一次性任务：对话时直接讲就好
• 专案通用规则、大方向：写进 CLAUDE.md，让模型参考
• 特定时机必须严格执行、且不能承担被遗忘风险的动作：做成 Hook

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

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

以「检查程式码有没有语法错误」的 Hook 为例：

第一层：Event（什么时候触发）

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

现代 AI 编程助手采用的是 ReAct（Reasoning + Acting）架构：模型先推理需要做什么，再通过「工具调用」（Tool Call / Function Call）与外部环境交互。在 Claude Code 中，工具包括读取文件、写入文件、执行 Bash 命令、搜索代码等。每次工具调用都有明确的生命周期——准备调用（Pre）、执行中、执行完成（Post）——Hook 正是利用这些生命周期节点来插入自动化逻辑，类似于软件开发中的「中间件」或「生命周期钩子」概念。

第二层：Matcher（拦截哪个操作）

Claude 工作时会调用非常多种工具，不可能每次都触发 Hook。Matcher 的作用就是筛选——在这个例子中，会锁定「修改程式码」这个动作。

第三层：Handler（执行什么动作）

当条件都符合后，由 Handler 决定接下来调谁做事。语法检查的例子里，Handler 就是去把电脑里的语法检查脚本叫出来，自动抓错误。

一句话总结：Event 决定什么时候，Matcher 决定拦哪个操作，Handler 决定做什么。

十个核心 Event：按工作阶段分类

Claude Code 目前多达 31 种 Event，但按系统工作阶段分类，抓住核心的几个就够了。

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

• SessionStart：开启对话的瞬间触发（新对话、接续记录、Clear 都算）。热门专案 Superpowers 就用它强制 AI 每次对话都载入 Skill，对付 AI 载入的随机性。
• UserPromptSubmit：按下 Enter 送出 Prompt 时触发。开源专案 Claudeman（帮 Claude 建立长期记忆）就用它拦截提问，先从背景资料库捞出相关记忆再塞给 Claude，解决跨对话失忆问题。

阶段二：准备使用工具前（安全防呆）

• PreToolUse：工具准备被调用前触发，非常适合安全防呆。有些 Skill 用它挡掉危险的 Git 指令——只要发现 git reset --hard 这类会洗掉代码的操作，或危险的 git push，就立刻拦截中断。

阶段三：工具执行完成后（快速验收）

• PostToolUse：Claude 顺利执行完 Tool Call 后触发，适合快速验收。前端设计 Skill Impeccable 就在这里把关：Claude 一改完 UI 档案，就扫描代码抓出空的图片连结、计算文字与背景的对比值，发现问题自动修正。

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

• Stop：这一回合对话完全结束时触发。Impeccable 刻意把排版、配色和谐度这类深度美感检查留到 Stop 阶段，把整个工作阶段改过的档案统整做一次总体检，避免拖慢开发速度。
• Notification：桌面通知提醒，Claude 需要确认权限时叫你回来。
• SubagentStart / SubagentStop：控管 Subagent 工作品质。Subagent 是指主 Agent 在执行任务过程中派生出的独立 AI 实例，它拥有自己的上下文窗口，可以独立执行文件读取、代码搜索、命令执行等操作，完成后将结果汇报给主 Agent。这种架构类似于软件工程中的「微服务」思想——将复杂任务分解为多个独立子任务并行或串行处理。
• PreCompact：对话太长自动浓缩前，先把关键决策、进度、规则保存下来，避免浓缩后遗漏重要信息。大语言模型的上下文窗口有长度限制（如 Claude 的 200K tokens），当对话过长接近上限时，Claude Code 会自动执行「Compact」操作——将之前的对话内容进行摘要压缩，保留关键信息的同时释放上下文空间。PreCompact 事件让你能在压缩发生前保存重要决策和规则，防止压缩算法在摘要时丢失对后续工作至关重要的信息，这对长时间编程会话尤为关键。

新手只需记住四个：SessionStart（对话开始）、PreToolUse（用工具前）、PostToolUse（工具执行后）、Stop（工作结束时）。

Matcher 与五种 Handler 类型详解

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

Handler 决定条件符合后实际做什么，目前有五种类型：

• Command（最常用）：直接执行电脑上的指令或脚本，如自动跑 lint、用 Prettier 整理格式
• HTTP：把资料传到外部服务，如失败时自动送错误到 Slack
• MCP Tool：使用已连线的 MCP 工具，如自动从 Jira 抓回今日任务。MCP（Model Context Protocol）是 Anthropic 推出的开放协议，旨在标准化 AI 模型与外部工具、数据源之间的连接方式。你可以把它理解为 AI 世界的「USB 接口」——只要工具提供方实现了 MCP 协议，任何支持 MCP 的 AI 客户端都能直接调用，无需为每个工具写专门的集成代码。
• Prompt：呼叫 AI，根据收到的资料直接回答（不会开档案或搜寻），如检查 Commit 讯息格式
• Agent：叫起 Subagent，可先读档案、搜寻代码、执行测试后再回传验收结果

简单说，Prompt 是拿现有资料直接回答，Agent 可以先查清楚再回答。要注意每个 Event 支援的 Handler 类型不同，实际设定前建议请 AI 查一下官方文件。

实战案例：建立你的第一个 Hook

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

案例一：Git 提交前检查敏感资料（Command Handler）

直接对 Claude Code 说：

请帮我在全域设定里建立一个 Hook。每当准备执行 git commit 时，先检查提交内容。如果包含 .env 档案或疑似 API 金钥的，就挡下提交并告诉我是哪个档案；没发现就正常继续。完成后请测试两种情况。

Claude 建立的 Hook 使用 PreToolUse Event、Matcher 锁定 Bash，Handler 叫起名为 git-commit-secret-guard 的检查程式。实测中，包含 .env 的提交在 git commit 真正执行前就被拦截，移除敏感资料后再试则顺利通过。

这个案例解决的是一个常见的安全问题——意外将 API 密钥、数据库密码等敏感信息提交到版本控制系统中。一旦这些信息被推送到 GitHub 等公开仓库，即使事后删除，也可能已经被爬虫抓取。传统做法是依赖 .gitignore 和 pre-commit hooks，但当 AI 自动操作 Git 时，这层人工检查就容易被跳过——Hook 在这里提供了一道确定性的安全网。

案例二：文章完成后检查 AI 味（Agent Handler）

第二个例子需要更「智能」的判断。作者希望 Claude 写完文章后，Hook 能检查里面还有没有「AI 味」：

请建立一个 Hook。每当写完一篇 Blog 文章准备结束工作时，启动一个 Agent 读取刚产出的文章，呼叫 Humanizer Skill 检查有没有 AI 味。发现问题就把段落和原因交回来请你修改，检查通过才能结束工作。

这个 Hook 使用 Stop Event，Handler 执行 humanizer-gate 检查程式：先找出改过且未通过检查的文章，再要求 Claude 开 Agent 审查。修改完成后再检查一次，确认通过才结束。

让 Hook 长期稳定运行的两个关键

建立第一版 Hook 后，还要再检查两件事，才能长期放进工作流程：

第一，触发范围够不够精确。 范围设太大就会在无关操作中被反复叫起，浪费时间又打断工作。正确做法是 Matcher 先缩小范围（如锁定 Bash），Handler 里再检查更细的条件（判断是否为 git commit）。这种「粗筛 + 细筛」的两阶段过滤设计，类似于搜索引擎的 Recall-Precision 策略：第一层快速缩小候选范围，第二层精确判断是否真正需要处理，兼顾效率与准确性。

第二，Stop Hook 有没有设结束条件。 Stop Hook 每次阻止结束都会要求继续工作，若没有明确通过条件，可能陷入「退回、修改、再检查」的死循环。所以 humanizer-gate 会记录当前版本是否已通过，通过后只要文章没改就直接放行；连续检查三轮仍不通过就停止，交给人工确认。

Codex 用户的两个差异

如果你用 Codex，判断方式完全通用，但设定不能直接复制：

• Event 数量：Claude Code 有 31 种，Codex 有 11 种。但 PreToolUse 和 Stop 两边都支援，所以基本做法都能实现。
• Handler 类型：Claude Code 支援五种，Codex 目前真正会执行的只有 Command。不过这不代表 Codex 做不了 AI 判断的流程——像 humanizer-gate 本身就是 Command Handler，先执行检查程式再要求主 Agent 呼叫 Skill。

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

结语：把重复提醒交给 Hook

Hooks 能在固定时机自动替你执行检查、通知或防呆——Event 决定何时启动，Matcher 决定处理哪些情况，Handler 负责启动后做什么。

实际建立时不需要背设定或手写程式，先找出一件你经常提醒 AI、且总在固定时机发生的事，从很小的问题开始（比如提交前检查金钥），把「何时启动」和「启动后做什么」讲清楚，让 AI 建立第一版，再确认触发范围和结束条件。

当你一个个把重复提醒交给 Hook，原本需要自己记得、反复确认的事情会慢慢变成工作流程里自动发生的一部分，你也能把注意力留给真正需要判断的事情。

核心要点