Everything Claude Code 钩子（Hooks）机制深度指南：如何编写自定义 Hook 实现全自动化

Everything Claude Code 钩子Hooks机制深度指南如何编写自定义 Hook 实现全自动化【免费下载链接】everything-claude-code-zheverything-claude-code 中文翻译项目完整的 Claude Code 配置集合agents, skills, hooks, commands, rules, MCPs。源自 Anthropic 黑客松获胜者的实战配置助力中文工程师高效理解与使用 Claude Code。项目地址: https://gitcode.com/gh_mirrors/ev/everything-claude-code-zhEverything Claude Code 中文翻译项目收录了完整的 Claude Code 配置集合其中**钩子Hooks**是最具实战价值的自动化机制它能在 Claude 执行工具前后自动触发检查、拦截与格式化全程无需人工干预。本文带你读懂 Everything Claude Code 的钩子原理并手把手教你编写自定义 Hook把重复性检查变成全自动化工作流。什么是 Claude Code 钩子为什么它值得你花 10 分钟了解钩子Hooks是事件驱动的自动化命令当 Claude Code 触发特定事件执行工具前、工具完成后、会话开始/结束、上下文压缩前时自动运行你预设的 Shell 命令。它用来强制执行代码质量、及早发现错误、自动执行重复性检查。触发流程非常简单用户请求 → Claude 选择工具 → PreToolUse 钩子 → 工具执行 → PostToolUse 钩子各类钩子事件一览事件触发时机能力PreToolUse工具执行前可拦截退出码 2或仅警告PostToolUse工具完成后可分析输出无法拦截Stop每次 Claude 响应后最终验证、审计SessionStart / SessionEnd会话生命周期边界加载 / 持久化状态PreCompact上下文压缩前保存状态防止压缩丢信息完整事件定义见 schemas/hooks.schema.json。仓库内置的 10 个钩子都在做什么钩子配置文件 展示了黑客松获胜者每天真实在用的钩子组合钩子事件匹配器行为开发服务器拦截器PreToolUseBash在 tmux 外拦截npm run dev退出码 2Tmux 提醒PreToolUseBash长时间命令test/build/docker建议使用 tmuxGit push 提醒PreToolUseBashpush 前提醒审阅更改文档文件警告PreToolUseWrite警告非标准文档文件允许 README 等白名单策略性压缩PreToolUseEdit|Write约每 50 次工具调用建议执行/compactPR 日志记录器PostToolUseBashgh pr create后记录 PR URL 与审阅命令构建分析PostToolUseBash构建完成后后台异步分析不阻塞Prettier 格式化PostToolUseEdit编辑后自动格式化 JS/TS自动识别 Biome/PrettierTypeScript 检查PostToolUseEdit编辑.ts/.tsx后运行tsc --noEmitconsole.log 审计Stop*每次响应后检查修改文件的残留调试语句会话持久化SessionStart/End*加载上次上下文 / 持久化会话状态以开发服务器拦截器为例hooks/hooks.json当 Claude 尝试在 tmux 之外运行npm run dev时钩子直接拦截并给出正确命令提示确保日志始终可访问——这正是 tmux 双终端场景下钩子发挥的典型作用。如何编写自定义 Hook三步配置流程第一步在 hooks.json 中添加 matcher 条目钩子按事件分组用matcher匹配工具名Bash、Edit、Write或*{ matcher: Edit, hooks: [{ type: command, command: node -e \...\ }], description: Warn when adding TODO/FIXME comments }第二步读懂输入与输出协议钩子本质是 Shell 命令通过stdin 接收 JSON包含tool_name、tool_inputPostToolUse 还有tool_output执行完后必须把原始 JSON 原样输出到stdout否则流程会中断。第三步用退出码控制行为退出码行为0成功继续执行警告信息写 stderr2拦截工具调用仅限 PreToolUse其他非零记录日志但不拦截想让钩子在后台运行、不阻塞主流程加上async: true和timeout即可。完整的输入 Schema 与异步钩子说明见 hooks/README.md。配好钩子后Claude 在执行长任务时会顺手完成格式化、类型检查与调试语句清理全程无人值守。4 个实用钩子配方警告 TODO、拦截大文件、ruff 格式化仓库自带可以直接抄的配方⚠️警告 TODO 注释— Edit 后检测TODO|FIXME|HACK提醒及时创建 issue拦截大文件创建— Write 超过 800 行直接退出码 2强制拆分为小模块ruff 自动格式化— 编辑.py文件后自动执行ruff format测试伴随提醒— 新建src/源文件时检查是否存在同名.test.文件完整 JSON 示例见 hooks/README.md配合 rules/common/hooks.md 的架构指南可以快速落地到自己的项目。自定义 Hook 最佳实践清单✅跨平台优先用 Node.jsnode -e或独立脚本编写避免 bash 专属语法✅静默失败格式化、检查类钩子失败时不应阻塞主流程参考 scripts/hooks/post-edit-format.js 的容错写法✅警告优先能用 stderr 提醒解决的不用退出码 2 硬拦截⚠️谨慎放行自动接受权限只用于受信任、定义明确的任务探索性工作请保持手动确认随时可关在~/.claude/settings.json中用空hooks: []覆盖条目即可禁用指定钩子下一步深入钩子脚本源码钩子总览、协议与配方大全hooks/README.md全部钩子脚本实现scripts/hooks/策略性压缩技能建议式钩子的完整实现skills/strategic-compact/SKILL.md钩子配置校验 Schemaschemas/hooks.schema.json把钩子当成你的质量守门员——配置一次之后的每一次编辑、执行与提交都会被自动守护。【免费下载链接】everything-claude-code-zheverything-claude-code 中文翻译项目完整的 Claude Code 配置集合agents, skills, hooks, commands, rules, MCPs。源自 Anthropic 黑客松获胜者的实战配置助力中文工程师高效理解与使用 Claude Code。项目地址: https://gitcode.com/gh_mirrors/ev/everything-claude-code-zh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考