Claude Code Hooks 实操：13 个钩子事件让 AI 编码行为可控可审计

Claude Code Hooks 实操13 个钩子事件让 AI 编码行为可控可审计【免费下载链接】claude-code-hooks-masteryMaster Claude Code Hooks项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery你盯着屏幕让 AI 跑一遍清理临时目录它反手就是一个rm -rf——这是很多用过 Claude Code 的人真实经历过的惊吓。Claude Code Hooks 是内置于 Claude Code 生命周期的 13 个确定性拦截点在用户提交输入前、工具调用前后、会话与子代理启停时触发让你用自己的代码而不是模型的自觉来接管关键动作。本文基于 claude-code-hooks-mastery 这个仓库它把这 13 个钩子全部实现了一遍顺带示范了子代理、团队化校验、状态栏等配套玩法是学习 Claude Code Hooks 机制的完整样本。它替你想好了哪几件烦心事以前你得手动盯着 AI 写的每一行代码、逐条确认危险命令现在 PreToolUse 钩子直接拦截rm -rf和.env访问PostToolUse 钩子写完文件立刻跑 Ruff 和 Ty 校验。以前任务完成只是模型的一句话没有凭证现在 Stop 钩子可以校验完成条件不达标就强制 AI 继续干。以前会话上下文丢失就找不回来了现在 SessionStart / PreCompact 钩子负责注入开发上下文、在压缩前备份转录。以前多代理协作要自己写脚本协调现在 builder 与 validator 两个代理靠任务系统并行开工钩子在每个环节做质量门禁。从 clone 到看到第一次拦截装两个前置工具Astral 的 UV快速 Python 脚本运行器负责跑每个钩子和 Claude Code 本体。用文末的git clone命令克隆 claude-code-hooks-mastery进入项目目录。启动claude随便提交一个正常提示词——UserPromptSubmit 钩子立刻把它记进logs/目录。接着试着让它执行rm -rf类命令PreToolUse 钩子当场拦下你在对话里会看到 BLOCKED 提示。不用任何额外配置仓库自带的.claude/settings.json已经注册了全部 13 个钩子跑起来即生效。核心机制拆解13 个钩子事件每个都是一个确定性拦截点钩子的本质是在固定时机执行你的命令而不是把决定权交给模型。13 个实现全部位于.claude/hooks/每个都是独立 Python 脚本文件头内嵌依赖声明靠 UV 单文件脚本机制直接运行不碰项目依赖树。流程控制靠两样东西退出码 2 表示拦截stderr 内容会自动反馈给 Claude 让它自行调整退出码 0 加 stdout 输出则把你写的内容作为上下文注入拼在用户提示词前面。README 里有一张完整的退出码 × 各钩子能力对照表值得先翻一遍。PreToolUse 拦截危险命令根本执行不到这是防御层里最硬的一环。.claude/hooks/pre_tool_use.py里用一组正则匹配rm -rf的各种变体并拦截对.env的读取和改写.env.sample除外命中就退出码 2 直接阻断if is_dangerous_rm_command(command): print(BLOCKED: Dangerous rm command detected, filesys.stderr) sys.exit(2)对 AI 来说这不是被拒绝了而是收到了一条必须处理并绕开的路由——拦截之后它通常会换一个安全方案继续。团队校验流builder 写代码validator 只读验收.claude/agents/team/下两个代理构成用算力换信任的配对builder 负责实现它的 PostToolUse 钩子绑定了 Ruff 和 Ty 两个校验器每次 Write/Edit 之后自动检查不过就回滚重来validator 只有读权限专门验收 builder 的产出。两者由任务系统调度可并行、可挂依赖不需要 bash sleep 轮询。实战三个典型卡点的解法当 AI 要删你不敢删的东西时什么都不用做——pre_tool_use.py已经替你把关。想加自己的规则把正则加进拦截列表即可例如封掉某个目录的写操作。当 AI 报完成但测试还红着时Stop 钩子就是那道门禁。输出{decision: block, reason: ...}这样的 JSON 并返回 0Claude 会收到 reason 继续干活而不是提前收工。当任务大到需要分工时在 Claude Code 里输入/plan_w_team 更新钩子文档并补齐缺失的状态栏 为每个 hook 建一组 builder validator它会生成一份带团队编排和依赖关系的计划文档存入specs/然后 builder 与 validator 按计划并行推进。进阶规则、校验器与自己的代理拦截规则改.claude/hooks/pre_tool_use.py里的正则列表加一条、验证一次。代码质量标准ruff.toml与ty.toml决定 Ruff、Ty 校验的严格程度团队里可以按项目调。自定义子代理在.claude/agents/新建 markdownYAML 头写name、description告诉主代理何时委派、tools、model正文写清角色和汇报格式。钩子开关与参数全部注册在.claude/settings.json命令尾部的--log-only、--notify、--validate等标志位控制行为另附 9 版状态栏.claude/status_lines/和 8 种输出风格.claude/output-styles/开箱即用。高频问题与避坑Q钩子注册了为什么没触发A按顺序查三处——.claude/settings.json的hooks里是否注册了该事件命令路径是否用了$CLAUDE_PROJECT_DIR前缀裸相对路径在不同工作目录下会解析失败UV 是否已安装uv --version验证。Q钩子跑起来了但就是拦不住A大概率是退出码没给对。返回 0 只会被当作通过拦截必须返回 2stderr 反馈给 Claude或输出带decision字段的 JSON。另外注意时机PostToolUse 触发时工具已经执行完它只能反馈和校验无法撤销真正想防要用 PreToolUse。QTTS 提示音没声音A.env里没配 ElevenLabs 等服务的 API key通知类钩子会静默降级但logs/里的日志依然正常写入。不想听声音可以不加--notify标志。QStop 钩子会不会把 AI 锁死A会如果无条件 block 就是死循环。判断输入里的stop_hook_active标志避免二次拦截样本代码里就是这么写的。一小时上手路径把盯屏幕变成定规则回到开头那个场景AI 依然会想跑危险命令但它跑不到——规则已经写在钩子里。这套仓库的价值在于把钩子注册、退出码语义、团队化校验这几个最容易踩坑的地方全部铺成了可运行的示例你照着改就能长出自己的版本。下一步可以这样做先 clone 仓库提交一个普通提示词确认logs/里开始产生记录。挑一个钩子建议从pre_tool_use.py入手加一条只属于你项目的拦截规则。跑一次/plan_w_team观察 builder 与 validator 的协作节奏。git clone https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery【免费下载链接】claude-code-hooks-masteryMaster Claude Code Hooks项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考