Claude Code Hooks 实战指南用 5 类触发点把开发规则变成自动执行的代码【免费下载链接】claude-code-hooks-masteryMaster Claude Code Hooks项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-masteryClaude Code Hooks 是 Claude Code 的官方扩展机制允许你在会话运行的固定节点挂上自己的脚本把靠模型自觉的规则变成每次都一定执行的代码。本文结合示例项目 claude-code-hooks-mastery带你按场景走完一次完整的钩子配置。先说清楚它解决什么问题你总可以反复叮嘱 Claude改完代码要跑格式化别碰 .env 文件但提示词本质是概率性的偶尔就会失守。钩子则不同——它由 Claude Code 运行时在特定时机强制触发无论模型想不想都会执行。这就是官方文档里说的 deterministic control确定性控制。触发点全景钩子到底什么时候触发Claude Code 在会话生命周期的多个位置埋了触发点。做配置之前先在心里画一张地图知道我想拦的事发生在哪个阶段选型就成功了一半。触发时机事件名拿到的关键数据能不能拦用户提交提示词后、Claude 处理前UserPromptSubmitprompt文本、session_id能还能往上下文里注入内容工具调用执行前PreToolUsetool_name、tool_input能是安全拦截的主战场工具调用成功后PostToolUsetool_name、tool_input、tool_response不能回滚但可反馈给 Claude 修正Claude 发出通知等输入、等授权等Notificationmessage内容不能纯信息类Claude 准备结束回复Stopstop_hook_active标志能可以强制它继续干活子代理Task 工具结束SubagentStopstop_hook_active标志能可拦截子代理提前收工会话启动或恢复时SessionStartsourcestartup/resume/clear不能适合做环境准备此外还有SessionEnd会话结束、PreCompact压缩上下文前、PermissionRequest弹出授权对话框时等触发点覆盖更细的环节配置方式完全相同。完整清单可以对照仓库里的 官方文档镜像。记住一个核心规律想阻止某事就选执行前的触发点想善后就选执行后的触发点。场景化实战按目的挑钩子下面把常见需求分成 4 组。每组的讲法都是先说场景再给配置最后说清效果。你可以只挑自己需要的场景抄。编辑后自动格式化PostToolUse 守住代码风格场景Claude 写完或改完代码后经常留下一堆风格不一致的地方——缩进、分号、引号风格全靠模型当下的心情。你不想每次手动跑prettier。配置在.claude/settings.json项目级或~/.claude/settings.json全局里加一段{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: jq -r .tool_input.file_path | { read f; if echo \$f\ | grep -q \\.ts$; then npx prettier --write \$f\; fi; } } ] } ] } }白话拆解这条命令钩子会收到一段 JSON 输入通过 stdin 传入jq从中取出文件路径如果以.ts结尾就交给prettier原地格式化。效果以后凡是 Claude 编辑或新建 TypeScript 文件格式都会被自动捋平。matcher里的Edit|Write表示这两个工具名任一命中就触发其他文件类型不受影响。如果项目文档也要求规范同一个触发点还可以挂一个 Markdown 整理脚本思路完全一样{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: \$CLAUDE_PROJECT_DIR\/.claude/hooks/markdown_formatter.py } ] } ] } }这里的markdown_formatter.py是你自己写的脚本负责给没有语言标签的代码块补上标签、压缩多余空行。$CLAUDE_PROJECT_DIR是 Claude Code 注入的环境变量指向项目根目录能保证钩子在不同工作目录下都能找到脚本——写钩子路径时请永远带上这个前缀。效果模型输出的 Markdown 每次落盘前都过一遍排版工位代码块语言、空行问题不用你人工挑。更进一步把 Ruff 这类 linter 也挂到PostToolUse上让写完必查质量成为流程而不是习惯。文件保护钩子怎么配PreToolUse 提前锁死敏感文件场景你肯定不希望 Claude 手滑改了.env里的密钥或动了package-lock.json破坏依赖树。提示词约束不可靠要在执行前硬拦。配置{ hooks: { PreToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: python3 -c \import json,sys; djson.load(sys.stdin); pd.get(tool_input,{}).get(file_path,); sys.exit(2 if any(x in p for x in [.env,package-lock.json,.git/]) else 0)\ } ] } ] } }这条命令很短但藏着钩子机制里最关键的一个知识点退出码 2 拦截。脚本从 stdin 读入的 JSON 里取出目标文件路径命中黑名单就sys.exit(2)Claude Code 会直接取消这次工具调用并把 stderr 内容反馈给 Claude让它换个做法。退出码 0 则放行。效果敏感文件在模型动手之前就上了锁而且模型能听懂为什么被拦——它会主动避开这些路径。同样的机制也适用于拦截危险命令比如检测到rm -rf模式就 exit 2。顺手的审计方案PreToolUse还能只记不拦。下面这段配置把每条 Bash 命令连同描述追加到日志文件{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: jq -r \\(.tool_input.command) - \(.tool_input.description // \No description\)\ ~/.claude/bash-command-log.txt } ] } ] } }效果Claude 执行过的每条命令都有据可查出问题时翻~/.claude/bash-command-log.txt就行。matcher设为Bash保证只记 shell 命令*则可匹配所有工具。环境与流程配置SessionStart 自动备料Notification 桌面提醒场景每次开会话都要手动激活虚拟环境、导出环境变量烦Claude 在后台等着输入时你没盯着终端任务就干等着。配置一会话启动自动备环境{ hooks: { SessionStart: [ { hooks: [ { type: command, command: \$CLAUDE_PROJECT_DIR\/.claude/hooks/setup_env.sh } ] } ] } }setup_env.sh里放你的备料逻辑激活 venv、装依赖、git 状态检查什么都行。效果新会话一开环境就是就绪的团队每个人拿到的初始状态都一致。配置二等输入时弹桌面通知{ hooks: { Notification: [ { matcher: , hooks: [ { type: command, command: notify-send Claude Code Awaiting your input } ] } ] } }notify-send是 Linux 桌面通知工具macOS 可换成osascript。效果Claude 等你确认的那一刻桌面就会弹窗你可以放心切去干别的不用守着终端刷新。AI 智能决策Stop 与 SubagentStop 的 prompt 型钩子场景Claude 说完成了的时候你真的信吗测试跑过了吗边界情况处理了吗再派出去的子代理是不是干到一半就收工了这类判断题不适合写死规则可以让模型自己评。配置{ hooks: { Stop: [ { hooks: [ { type: prompt, prompt: 评估 $ARGUMENTS所有任务是否真正完成完成则回答 {\ok\: true}未完成回答 {\ok\: false, \reason\: \缺什么\} } ] } ] } }注意type: prompt这不是跑你的脚本而是把钩子输入 JSON$ARGUMENTS占位符交给一次 LLM 调用做评估LLM 必须按 JSON 格式给出结论。返回ok: false时 Claude 不会停下而是带着 reason 继续干活。把同样的模式挪到SubagentStop上就能给子代理加一道交卷检查{ hooks: { SubagentStop: [ { hooks: [ { type: prompt, prompt: 检查这个子代理能否收工输入$ARGUMENTS。逐项核对任务是否完成、有无报错需要修、是否还需补充上下文。放行返回 {\ok\: true}否则 {\ok\: false, \reason\: \原因\} } ] } ] } }效果子代理想提前结束时会被打回重做多代理流水线里每个子任务的完成质量都有人验收。这个仓库里的 meta-agent 和团队校验体系就是这类思路的完整落地。进阶技巧退出码语义、prompt 钩子与多钩子组合玩到这一步几个底层机制值得一次讲透。退出码是钩子和 Claude Code 之间的通用语言退出码含义会发生什么0成功正常继续stdout在 transcript 模式Ctrl-R可见UserPromptSubmit场景下 stdout 还能作为上下文注入给 Claude2拦截错误stderr自动反馈给 Claude在PreToolUse、Stop、SubagentStop等事件上会真的阻止动作其他非阻塞错误stderr展示给你看流程照常继续除了退出码钩子还能输出结构化 JSON 做更细的控制比如{decision: block, reason: 测试没过先修再收工}以及{continue: false, stopReason: ...}。优先级上continue: falsedecision: block 退出码 2。两种钩子类型的分工command型跑 shell 命令或脚本快、确定性强适合规则明确的事格式化、黑名单、日志。prompt型发起一次 LLM 评估慢一点默认 30 秒超时可用timeout字段调整适合需要理解上下文的判断题。输入输出约定每个钩子启动时Claude Code 会把当前上下文工具名、参数、会话 ID 等以 JSON 形式从 stdin 喂进来钩子脚本读 stdin、通过 stdout/stderr 和退出码回应——这就是为什么前面那些命令都从json.load(sys.stdin)或jq开始。多钩子组合同一个事件、同一个 matcher 下可以挂多个钩子它们并行执行。典型组合是PreToolUse拦危险命令 记日志PostToolUse跑格式化 跑 linter前哨和善后各管一段。另外注意每个钩子有 60 秒执行上限脚本写重了会直接超时。快速上手6 步完成你的第一个钩子安装jq钩子命令里会用它处理 JSON 输入brew install jq或apt install jq。克隆参考仓库看完整示例git clone https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery在 Claude Code 会话里输入/hooks选择PreToolUse事件。选择 Add new matcher输入Bash只拦 shell 命令输入*则匹配所有工具。选择 Add new hook粘贴命令jq -r \(.tool_input.command) - \(.tool_input.description // \No description\) ~/.claude/bash-command-log.txt存储位置选User settings所有项目生效或项目 settings仅当前项目生效然后按 Esc 返回。测试让 Claude 执行一条ls再cat ~/.claude/bash-command-log.txt看到一行ls - Lists files...的记录钩子就上线了。之后随时用/hooks查看、修改、删除配置。更多配置细节见 官方 Getting Started 文档。最后提醒一句钩子是以你的凭据自动运行的代码从外部抄来的配置一定要先读懂再注册尤其是含curl | sh这类模式的命令。钩子本质上就是把软约束升级成硬约束——触发点地图看懂了、退出码语义记住了剩下的只是按场景挑工具。完整的事件字段与决策控制参考 Hooks 官方文档镜像。【免费下载链接】claude-code-hooks-masteryMaster Claude Code Hooks项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考