3 步跑通 Claude Code 自定义钩子：扩展开发完整实操指南

3 步跑通 Claude Code 自定义钩子扩展开发完整实操指南【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code你让 Claude Code 批量改代码它顺手就要跑一条你没授权过的 shell 命令团队里每个人的提交信息格式又各不相同每次都得口头再交代一遍。这类每次都要盯着的琐事其实可以让工具自己记住。这篇文章用 Claude Code 的两个核心扩展能力——钩子hooks在工具执行前后插入自定义逻辑和自定义斜杠命令解决规则要反复交代的问题。文章按先跑通、再理解、后组合的顺序走第一节核对三样前提第二节用装、配、验三步看到第一次拦截生效第三、四节拆解内部生命周期并给出两个可照抄的组合玩法第五节提前讲清最常见的四个坑。读完你能独立写出自己的钩子和命令也知道出问题时往哪查。一、动手前只需检查这几样最小必要准备只有三样花两分钟核对即可Claude Code 已安装且可调用钩子脚本有落脚目录建议放项目根目录的hooks/知道配置文件在哪项目级.claude/settings.json用户级~/.claude/settings.json确认安装与版本npm install -g anthropic-ai/claude-code claude --version脚本语言不限Python、Node、Shell 都行只要它能读标准输入、用退出码表态。二、最短路径跑通第一个示例装 → 配 → 验三步之内就能看到效果。这里用官方示例做底把grep替换成更快的rg完整实现可参考 examples/hooks/bash_command_validator_example.py。Claude Code 钩子怎么配置核心就是下面这段写进 settings 的 JSON{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 hooks/bash_validator.py } ] } ] } }验证环节不用等会话触发手工把一段模拟的工具输入喂给脚本比如echo {tool_name:Bash,tool_input:{command:grep foo src}} | python3 hooks/bash_validator.py。看到 stderr 输出提示、退出码为 2说明脚本本身没问题剩下的就是重启 Claude Code 让配置生效。三、扩展到底是怎么工作的 钩子的本质是一个同步拦截器。每次匹配到matcher的工具调用Claude Code 都会先把一次 JSON含tool_name、tool_input等字段通过标准输入传给脚本然后等你的退出码退出码0放行退出码2拦截并把 stderr 内容反馈给 Claude 让它调整其他非零值仅记录错误不阻断流程常见钩子类型与适用场景对比钩子类型触发时机典型用途PreToolUse工具调用前命令校验、危险操作拦截PostToolUse工具完成后结果后处理、审计日志UserPromptSubmit用户消息发出时自动注入上下文、敏感词检查StopClaude 完成回复时自动校验产物、发通知自定义命令是另一条路一个带 frontmatter 的 markdown 文件就是一个斜杠命令。description决定它何时被自动调用allowed-tools圈定它允许使用的工具正文就是提示词其中的!git status会在渲染时先执行并把输出注入上下文。想看一个现成的直接翻 plugins/commit-commands/ 里的/commit实现。四、把能力组合起来场景一统一提交入口。团队约定 Conventional CommitsClaude Code 自定义命令写法其实很简单一个文件搞定--- description: 按团队规范生成提交信息并提交 allowed-tools: Bash(git add:*), Bash(git commit:*) --- ## Context - 当前变更: !git diff HEAD ## 任务 生成符合规范的提交信息仅调用 git add 与 git commit。场景二提交前自动过 lint。再挂一个 PreToolUse 钩子拦住不合格的提交。关键骨架如下def main(): data json.load(sys.stdin) cmd data.get(tool_input, {}).get(command, ) if cmd.startswith(git commit): if subprocess.run([npm, run, lint]).returncode ! 0: print(lint 未通过先修复再提交, filesys.stderr) sys.exit(2) # 退出码 2 拦截 sys.exit(0) # 其余命令一律放行命令负责怎么做钩子负责不许怎么错两者组合后提交流程里的规则和卡点都被固化了不再依赖每次口头交代。五、踩坑前先看这几点⚠️现象钩子从不触发。原因matcher写错了工具名应为Bash、Edit|Write这类精确名或配置写进了没被读取的 settings 路径。解决跑claude --debug看配置加载与匹配日志。现象会话莫名变慢。原因钩子在每次工具调用时同步执行脚本里跑了网络请求或大文件扫描。解决钩子内只做毫秒级判断重活拆出去异步做。现象退出码用错钩子只报警不拦截。原因exit 1只是记录错误不会阻断只有exit 2才拦截。解决拦截逻辑统一sys.exit(2)提示写 stderr。现象命令正文里的命令被意外执行。原因!command语法在渲染时就会执行不是注释。解决想展示命令文本时不要加感叹号前缀或改用围栏代码块。六、下一步与参考资料把钩子升级成规则引擎参考 plugins/hookify/ 的多规则配置方案探索托管配置managed settings做团队级策略分发示例见 examples/settings/更多钩子与插件的完整用法在项目 plugins/ 目录里都能找到可运行范例官方 Hooks 文档在 Anthropic 文档站搜索 Claude Code hooks 即可定位 挑一条你最近最烦的重复规则今天就用 PreToolUse 钩子把它固化掉。【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考