Hooks on KnightLi的博客

Claude Code Hooks Mastery：13 个 Hooks 生命周期与自动化控制入门

Fri, 01 May 2026 03:11:27 +0800

claude-code-hooks-mastery 是一个围绕 Claude Code Hooks 的学习项目。

它不是只给几个零散脚本，而是把 Claude Code 的 hooks 生命周期、配置方式、脚本写法和常见自动化场景放在一起讲清楚。对于想让 Claude Code 更可控、更像工程化助手的人来说，这类资料很值得看。

Claude Code 默认已经能读代码、改文件、跑命令。但如果你想让它在特定时机自动检查权限、拦截危险操作、注入项目规范、运行测试、提醒团队规则，单靠聊天指令就不够稳定。Hooks 的价值就在这里：把“每次都要提醒 AI 的规则”变成可执行的流程。

Hooks 解决什么问题

使用 Claude Code 一段时间后，常见痛点大概有这些：

每次新会话都要重复告诉它项目规则
担心它执行不该执行的命令
希望文件修改前后自动做检查
想在提交前自动跑格式化、测试或安全扫描
想把团队规范写成固定流程，而不是靠口头提醒
想在工具调用前后拿到上下文，做记录或拦截
希望复杂任务可以触发子代理或专门脚本处理

Hooks 就是为这些“固定时机的自动动作”准备的。

你可以把它理解成 Claude Code 工作流里的事件钩子：当会话开始、用户提交提示词、模型准备调用工具、工具调用完成、代理即将结束等节点发生时，Claude Code 可以执行你配置的脚本。

13 个 Hooks 生命周期

项目 README 的重点之一，是系统整理了 Claude Code 的 13 个 hook 事件。

这些事件覆盖了从会话开始到工具调用、从用户输入到代理结束的多个节点。按用途可以粗略分成几类：

会话启动相关：用于初始化环境、注入项目上下文
用户输入相关：用于检查提示词、补充规则、做审计
工具调用前相关：用于权限判断、命令拦截、安全检查
工具调用后相关：用于记录结果、触发格式化、运行验证
任务结束相关：用于总结、清理、通知或保存状态

这种生命周期设计让你不必把所有规则都写进一个超长提示词里。

比如，权限控制应该发生在工具调用前；格式化检查更适合发生在文件修改后；项目规范注入适合发生在会话开始或用户输入后。把规则放到正确的 hook 节点，通常比把所有内容塞进 system prompt 更可靠。

配置文件在哪里

Claude Code 的 hooks 通常通过设置文件配置。

常见位置包括：

用户级配置：~/.claude/settings.json
项目级配置：.claude/settings.json

用户级配置适合放个人偏好，比如通用安全规则、命令拦截、日志路径。

项目级配置适合放仓库相关规则，比如这个项目必须跑什么测试、哪些目录不能改、生成文件怎么处理、提交前要做哪些检查。

如果你在团队里使用 Claude Code，更推荐把项目级配置放进仓库。这样每个人打开项目时，拿到的是同一套 AI 协作约束，而不是各自凭记忆提醒。

单文件脚本为什么重要

项目里强调了 UV 单文件脚本的写法。

这类脚本的好处是部署简单。一个 Python 文件就可以声明依赖并运行，不必为了一个 hook 单独维护复杂环境。对 hooks 来说，这很合适，因为很多 hook 只是做一件小事：

检查命令是否允许执行
判断文件路径是否安全
读取项目规范并返回给 Claude
扫描输出中是否包含敏感信息
在修改后运行格式化或测试
把事件写入日志

Hook 脚本越小，越容易维护，也越不容易变成新的复杂系统。

可以做哪些自动化

claude-code-hooks-mastery 展示的方向比较多，实际工作中最常见的是下面几类。

1. 权限和安全控制

这是 hooks 最直接的用途。

比如在 Claude Code 准备执行命令之前，先检查命令内容。如果命令包含删除、重置、清空、覆盖等高风险动作，就阻止执行或要求人工确认。

类似规则还可以用于文件路径：

不允许修改生产配置
不允许写入密钥文件
不允许删除迁移脚本
不允许触碰指定目录
不允许执行未批准的网络命令

这类保护放在工具调用前，比写一句“不要做危险操作”更可靠。

2. 上下文注入

很多项目都有固定背景：

技术栈
编码规范
测试命令
分支策略
目录结构
禁止事项
生成文件处理规则

这些内容每次手动告诉 Claude Code 很麻烦，也容易漏。Hooks 可以在会话开始或用户提交提示词后，把必要上下文自动注入进去。

这相当于给 Claude Code 配一个项目级的工作说明书。它不会替代 README 或开发文档，但能让 AI 在执行任务前更快进入正确状态。

3. 修改后的验证

当 Claude Code 修改文件后，可以通过 hook 自动触发检查。

常见动作包括：

运行格式化
运行 lint
运行单元测试
检查类型错误
扫描生成文件
校验 Markdown 或 JSON 格式

这对减少低级错误很有帮助。尤其是 AI 改动多个文件时，修改后自动跑一轮轻量验证，可以更早发现问题。

不过也要注意，hook 里不适合默认塞太重的任务。每次文件改动都跑完整测试套件，可能会让体验变得很慢。更实用的做法是按文件类型、目录和任务风险选择检查范围。

4. 团队规则验证

如果团队已经有明确约定，可以把一部分约定放进 hooks。

比如：

提交信息格式
代码风格规则
禁止直接修改某些生成文件
文档必须同步更新
API 变更必须改测试
某些目录只能用指定工具生成

这会让 Claude Code 更像团队流程的一部分，而不是一个不受约束的外部助手。

当然，hooks 不应该替代 CI。它更适合做本地快速提醒和前置拦截，真正的最终验证仍然应该交给 CI、review 和测试系统。

5. 子代理和专门任务

README 里还提到子代理相关内容。

这类用法适合把复杂任务拆给更专门的流程处理。比如主会话负责理解需求，hook 或配置触发专门的检查、审计、总结、文档整理任务。

对个人用户来说，最先值得做的不是复杂代理编排，而是把重复、明确、低风险的动作交给 hooks。等规则稳定后，再考虑更复杂的自动化。

Statusline 和输出样式

项目还覆盖了状态栏和输出样式。

这部分看起来像体验细节，但对长期使用 Claude Code 很有意义。状态栏可以展示当前上下文、任务状态、环境信息或提示信息；输出样式则可以让 Claude Code 的回答更符合你的工作习惯。

如果你每天都在同一个终端里和 AI 协作，这些细节会影响效率。好的状态提示能减少误操作，也能让你更快判断当前会话是否处在正确项目、正确分支、正确环境里。

不要把 hooks 写得过重

Hooks 很强，但不适合什么都往里面塞。

比较好的规则是：

高频动作要快
安全拦截要明确
输出要短
失败原因要可读
脚本尽量单一职责
重型检查交给显式命令或 CI

如果一个 hook 每次都执行十几秒，用户很快就会想关掉它。如果一个 hook 拦截规则含糊不清，Claude Code 和用户都会难以理解下一步该怎么做。

Hooks 最适合处理那些边界清楚的事情：允许或拒绝、补充上下文、记录日志、运行轻量检查、提示下一步。

适合怎样的使用者

如果你只是偶尔让 Claude Code 改一小段代码，可能暂时不需要深入 hooks。

但如果你符合下面几种情况，就很适合研究这个项目：

高频使用 Claude Code
经常让 AI 修改真实项目代码
担心 AI 执行危险命令
想把团队规范自动注入 AI 工作流
希望修改后自动跑检查
想把重复提醒变成配置
正在搭建更稳定的 AI 编程流程

尤其是多人协作项目，hooks 的意义会更明显。它可以把一部分团队经验沉淀成脚本，而不是靠每个人临时提醒 AI。

使用时要注意

第一，先从安全类 hook 开始。

相比复杂自动化，命令拦截、路径保护、敏感文件检查更容易落地，也更能立刻降低风险。

第二，项目级规则要谨慎提交。

.claude/settings.json 会影响所有使用这个仓库的人。把规则提交前，最好确认它不会过度限制正常开发，也不会依赖只有你本机才存在的路径。

第三，hook 输出要简洁。

Claude Code 会消费这些输出。输出太长，会污染上下文；输出太模糊，又起不到指导作用。最好只返回必要判断和下一步建议。

第四，保持可调试。

Hooks 一旦变多，问题可能出在配置、脚本、权限、路径、依赖或 Claude Code 本身。给脚本留下清晰日志，会让后续排查轻松很多。

参考

disler/claude-code-hooks-mastery

最后一句

Claude Code Hooks 的价值，是把“希望 AI 每次都记住的规矩”变成真正会执行的流程。

如果你已经开始把 Claude Code 用在真实项目里，hooks 会是从“会聊天的编程助手”走向“可约束的工程协作者”的关键一步。

Claude Code 环境配置四件套：CLAUDE.md、Rules、Memory、Hooks 一次讲清

Thu, 23 Apr 2026 10:35:00 +0800

如果你用 Claude Code 一段时间，就会很快发现一件事：模型本身当然重要，但给它什么环境、什么边界、什么规则，同样重要。

很多人刚开始会把注意力放在“我这次 prompt 怎么写”，但真正把 Claude Code 用成熟之后，你会更关心另一件事：

它知不知道你是谁
它知不知道你怎么工作
它知不知道哪些规则不能违反
它知不知道什么事情必须先确认
它能不能长期记住这些边界

Claude Code 之所以能变成一个成熟工具，不只是因为模型强，而是因为它有一整套机制，帮你把这些工作方式沉淀下来。核心上可以拆成四层：

CLAUDE.md
Rules
Memory
Hooks

这篇文章就把这四个部分一次讲清楚。

为什么环境配置比单次提示词更重要

你可以把 Claude Code 想成你请来的一个助理。

第一天上岗时，你不会只跟他说一句“帮我做事”，而是会给他一份说明书，告诉他：

你的身份是什么
你的沟通语气偏好是什么
哪些操作必须先确认
哪些错误之前犯过，未来不能再犯
这个项目最重要的文档放在哪里

这就是为什么，长期来看，环境配置往往比单次 prompt 更重要。

因为 prompt 解决的是“这一次要做什么”，而环境配置解决的是“以后每次都要怎么做”。

第一层：`CLAUDE.md`

先从最基础的开始，CLAUDE.md 本质上就是一个文字文件。

你可以在里面写给 Claude 的说明，例如：

你是谁
你在做什么
你的沟通偏好
需要遵守的规则
当前项目的特殊背景
重要文档或目录的位置

每次 Claude Code 启动时，这份文档都会被自动送进上下文里，所以模型一定会读到。

我通常把它叫做“默契档”，因为它本质上就是你和模型之间长期协作的默契。

`CLAUDE.md` 适合写什么

最适合写进 CLAUDE.md 的，大致有这几类：

身份与工作背景
沟通语气和输出偏好
全局性的行为规则
经常会用到的重要项目背景
常见错误与避免方式

比如：

你所在的时区
你是否接受模型直接发送邮件或消息
哪些操作属于不可逆行为
处理文档和文件时的习惯
安全规范和敏感信息边界

一个很重要的原则：尽量精简

CLAUDE.md 有一个很重要的原则，就是一定要尽量精简。

原因很简单：它每次都会被强制注入上下文。

如果你写得太长，就会占掉大量上下文空间，导致真正重要的信息被稀释。模型不是不读，而是注意力会分散，最后更容易漏掉你最在意的规则。

官方建议通常是最好不要超过 400 行。

我自己的习惯会更保守一些，尽量控制在 200 行以内。

`CLAUDE.md` 的常见作用范围

CLAUDE.md 实际上有不同的放置层级，对应不同的作用范围。最常用的是两个：

1. User Level

这是全局层级。

它放在你电脑环境里，对你本机操作的所有项目都有效。

这个位置适合放：

你的身份信息
通用的沟通偏好
你跨项目都适用的做事习惯
全局性的安全规则

比如，如果你的时区不是默认常见值，而是曼谷时间，那这类信息就很适合放在 user level，这样模型以后帮你安排时间时就不容易出错。

2. Project Level

这是项目层级。

它放在具体项目目录下面，只对那个项目有效。

这个位置适合放：

项目专属背景
只在这个项目里成立的规则
项目的目录结构说明
这个项目的重要文档入口

举个例子，如果一个项目处理财务，另一个项目处理人事，那两边的背景和约束显然不同，就不应该混在同一个全局说明里。

怎么判断该放哪一层

判断方式其实很简单：

你写进去的东西，如果换到另一个项目里还成立，那就放 user level。

如果一换项目就不成立，那就放 project level。

怎么开始写第一版

最常见的起手方式有两种：

1. 用 `/init`

你可以直接在终端里运行斜线命令 /init，让 Claude 扫描当前项目，自动帮你生成一份基础版 CLAUDE.md。

2. 让 Claude 帮你整理

你也可以直接让 Claude 去搜索别人是怎么写 CLAUDE.md 的，再结合你的情况问你问题，最后帮你整理成适合你自己的版本。

很多时候，这比自己从零开始写更轻松。

一个很实用的习惯

在你和 Claude 长期协作的过程中，只要你发现某件事情属于“未来一定要记住、不要再犯”的内容，就可以直接让它写进 CLAUDE.md。

不过写之前还是要判断一下：

这是全局规则
还是当前项目规则

别把所有东西都塞进一个文件里。

第二层：`Rules`

接下来是 Rules。

它和 CLAUDE.md 最大的差别，不是文件形式，而是加载方式。

CLAUDE.md 是无论你做什么，模型都会读到。

而 Rules 的优势在于：可以条件加载。

也就是说，只有在某些路径、某些文件、某些工具或某些场景下，这条规则才会被读到。

为什么条件加载很重要

因为上下文空间永远是稀缺资源。

如果所有规则都无差别地塞进上下文里，就会发生两件事：

模型负担变重
真正关键的规则反而被淹没

按需加载的价值就在这里：让模型在刚好的时候读到刚好的信息。

什么时候该把规则从 `CLAUDE.md` 挪到 `Rules`

通常有两种情况：

1. `CLAUDE.md` 太长了

如果你的 CLAUDE.md 开始超过 200 行，规则越来越多，重要内容被稀释，那就该考虑把一部分规则拆出去。

2. 某些规则只和特定路径相关

如果你已经明显知道某些规则只在某类文件里才有意义，比如：

只对 Python 脚本有效
只对某个 hooks 目录有效
只对某个子项目有效

那这些规则就更适合移到 Rules。

`Rules` 最适合的场景

最典型的就是“特定情境、特定路径、特定文件类型”。

比如：

只在处理 hooks 文件时触发的规范
只在某类脚本中要遵守的编码规则
只在某个目录下适用的工作方式

这些内容如果继续塞在 CLAUDE.md 里，其实是不划算的。

第三层：`Memory`

第三个层面是 Memory。

它和 CLAUDE.md、Rules 一样，也会进入模型上下文，但它最核心的区别是：

CLAUDE.md 是你主动设定的。

Memory 则更像是 Claude 在协作过程中，写给自己的笔记。

`Memory` 记的是什么

当 Claude 判断某件事值得记住，或者需要短期保留，它就会把这些内容写进 Memory。

常见内容包括：

你纠正过它的某个做法
你最近新增的偏好
当前项目的临时状态
你今天没做完、明天还要继续的事
你最近在跟哪些人合作
某些最近才提到的个人信息或上下文

换句话说，Memory 更像动态知识，而不是长期制度。

`Memory` 和前两者的区别

一个简单的区分方式是：

CLAUDE.md / Rules：偏长期、偏制度、偏明确规则
Memory：偏临时、偏动态、偏工作过程中的新理解

如果某件事只是最近几天有效，或者项目状态在持续变化，那它通常更适合放进 Memory，而不是写成长期规则。

`Memory` 也可以手动写

虽然 Memory 有自动整理能力，但你也可以主动告诉 Claude：

请记下来我明天要做什么
请记下来我要追踪谁的状态
请记下来这个月某个项目的关键节点

它也可以帮你写进 Memory。

你还可以通过斜线命令 /memory 查看当前有哪些记忆，并手动编辑或删除。

不过很多时候，我自己不会频繁手动维护，因为 Claude 本身也会定期整理这些记忆，把已经过时的部分清掉。

第四层：`Hooks`

最后也是最重要、最进阶的一层，就是 Hooks。

前面讲到的 CLAUDE.md、Rules、Memory，本质上都还是自然语言说明。

你写了规则，模型通常会遵守，但它仍然是在“理解之后执行”。

只要还是自然语言，就会存在几个问题：

模型偶尔会漏掉
规则太多时，注意力会分散
某些情境下它会自行判断这条规则不重要

这不是你写得不够认真，而是自然语言规则本来就很难做到 100% 强制。

`Hooks` 的本质是什么

Hooks 不再是自然语言说明，而是一段脚本。

它是事件触发的、程序级别的强制逻辑。

只要某个事件发生，这段逻辑就一定会执行，不会被模型“自己判断后略过”。

这就是 Hooks 最关键的价值：

把“建议遵守”变成“必须执行”。

什么时候该上 `Hooks`

当你发现某条规则已经写进了 CLAUDE.md 或 Rules，但 Claude 偶尔还是不执行，而且这件事一旦漏掉，风险就比较大，那就应该考虑改成 Hooks。

简单说：

低风险的，写规则
高风险的，写 Hooks

最典型的 `Hooks` 场景

最典型的，就是那些你绝对不希望出错的动作，比如：

发邮件前必须确认
发 Slack、Outlook、Gmail 消息前必须确认
删除危险文件前必须拦截
检测到要外发密码或 API Key 时必须阻止

如果这些要求只是写成一句自然语言规则，模型有可能哪天忙中出错，真的就发出去了。

但如果写成 Hooks，只要事件发生，就会被强制拦截。

这才是程序层面的硬防线。

`Hooks` 常见的触发时机

Hooks 可以设置在很多不同阶段，例如：

对话刚开始时注入提醒
某个工具执行前进行检查
某个工具执行后做结果校验

你不一定需要自己知道专业术语。

很多时候，只要你能清楚描述需求，让 Claude 帮你判断“这条规则适不适合改成 hook”，它就能帮你一起设计。

你也可以通过斜线命令 /hook 去查看系统当前已经设置了哪些 hooks。

一套更实用的上手顺序

如果你想把这四层串起来，我自己更推荐下面这条路径：

第一步：先用 `/init` 生成基础版 `CLAUDE.md`

不要一开始就手写一份特别完整的规则文档。

先让 Claude 帮你扫描项目，生成一个起点版本，再慢慢迭代。

第二步：边用边补

在协作过程中，只要你发现：

这件事以后一定要记得
这个错误以后不能再犯
这个偏好以后每次都适用

就让 Claude 帮你写进 CLAUDE.md。

第三步：当 `CLAUDE.md` 变长时，拆到 `Rules`

一旦你发现 CLAUDE.md 越来越长，模型开始不一定遵守每一条规则，就该考虑拆分：

哪些是全局规则
哪些只和某些路径相关

把后者移到 Rules，改成条件加载。

第四步：再把高风险规则升级成 `Hooks`

如果某些规则即使写了，模型还是偶尔会漏，而且漏掉代价很高，那就不要再停留在自然语言层面，直接升级成 Hooks。

也就是把“提醒”变成“强制”。

第五步：把临时状态交给 `Memory`

对于那些会过期、会变化、不是长期制度的内容，不要一股脑写进 CLAUDE.md。

更合适的做法是交给 Memory：

当前项目进度
最近合作对象
最近新增偏好
近期计划和待办

这样上下文会更清爽，模型也更容易保持稳定表现。

这四层分别该记什么

如果你想快速记住，可以直接用下面这个区分：

CLAUDE.md：长期默契、全局说明、项目基础背景
Rules：按路径或场景加载的专项规则
Memory：动态知识、临时状态、最近学到的东西
Hooks：高风险操作的程序级强制拦截

结语

很多人把 Claude Code 当成“会写代码的聊天界面”，但真正用深之后，你会发现它更像一个长期协作的智能工作台。

关键不只是你每次怎么下指令，而是你有没有给它一套稳定、清晰、可长期积累的环境。

一旦你把这四层搭起来：

CLAUDE.md
Rules
Memory
Hooks

你和模型之间的协作质量，通常会有非常明显的提升。

因为你终于不是每次都从零开始解释自己是谁、怎么工作、什么事不能做，而是把这些真正沉淀成了环境。

这才是把一个强模型，真正用成成熟工具的关键一步。