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 本身。给脚本留下清晰日志，会让后续排查轻松很多。
参考
最后一句
Claude Code Hooks 的价值，是把“希望 AI 每次都记住的规矩”变成真正会执行的流程。
如果你已经开始把 Claude Code 用在真实项目里，hooks 会是从“会聊天的编程助手”走向“可约束的工程协作者”的关键一步。