https://www.knightli.com/tags/%E8%87%AA%E5%8A%A8%E5%8C%96/ Recent content in 自动化 on KnightLi的博客 Hugo -- gohugo.io zh-cn Fri, 01 May 2026 03:11:27 +0800 https://www.knightli.com/2026/05/01/claude-code-hooks-mastery-guide/ Fri, 01 May 2026 03:11:27 +0800 https://www.knightli.com/2026/05/01/claude-code-hooks-mastery-guide/ <p><code>claude-code-hooks-mastery</code> 是一个围绕 <code>Claude Code Hooks</code> 的学习项目。</p> <p>它不是只给几个零散脚本，而是把 Claude Code 的 hooks 生命周期、配置方式、脚本写法和常见自动化场景放在一起讲清楚。对于想让 Claude Code 更可控、更像工程化助手的人来说，这类资料很值得看。</p> <p>Claude Code 默认已经能读代码、改文件、跑命令。但如果你想让它在特定时机自动检查权限、拦截危险操作、注入项目规范、运行测试、提醒团队规则，单靠聊天指令就不够稳定。Hooks 的价值就在这里：把“每次都要提醒 AI 的规则”变成可执行的流程。</p> <h2 id="hooks-解决什么问题">Hooks 解决什么问题 </h2><p>使用 Claude Code 一段时间后，常见痛点大概有这些：</p> <ul> <li>每次新会话都要重复告诉它项目规则</li> <li>担心它执行不该执行的命令</li> <li>希望文件修改前后自动做检查</li> <li>想在提交前自动跑格式化、测试或安全扫描</li> <li>想把团队规范写成固定流程，而不是靠口头提醒</li> <li>想在工具调用前后拿到上下文，做记录或拦截</li> <li>希望复杂任务可以触发子代理或专门脚本处理</li> </ul> <p>Hooks 就是为这些“固定时机的自动动作”准备的。</p> <p>你可以把它理解成 Claude Code 工作流里的事件钩子：当会话开始、用户提交提示词、模型准备调用工具、工具调用完成、代理即将结束等节点发生时，Claude Code 可以执行你配置的脚本。</p> <h2 id="13-个-hooks-生命周期">13 个 Hooks 生命周期 </h2><p>项目 README 的重点之一，是系统整理了 Claude Code 的 13 个 hook 事件。</p> <p>这些事件覆盖了从会话开始到工具调用、从用户输入到代理结束的多个节点。按用途可以粗略分成几类：</p> <ul> <li>会话启动相关：用于初始化环境、注入项目上下文</li> <li>用户输入相关：用于检查提示词、补充规则、做审计</li> <li>工具调用前相关：用于权限判断、命令拦截、安全检查</li> <li>工具调用后相关：用于记录结果、触发格式化、运行验证</li> <li>任务结束相关：用于总结、清理、通知或保存状态</li> </ul> <p>这种生命周期设计让你不必把所有规则都写进一个超长提示词里。</p> <p>比如，权限控制应该发生在工具调用前；格式化检查更适合发生在文件修改后；项目规范注入适合发生在会话开始或用户输入后。把规则放到正确的 hook 节点，通常比把所有内容塞进 system prompt 更可靠。</p> <h2 id="配置文件在哪里">配置文件在哪里 </h2><p>Claude Code 的 hooks 通常通过设置文件配置。</p> <p>常见位置包括：</p> <ul> <li>用户级配置：<code>~/.claude/settings.json</code></li> <li>项目级配置：<code>.claude/settings.json</code></li> </ul> <p>用户级配置适合放个人偏好，比如通用安全规则、命令拦截、日志路径。</p> <p>项目级配置适合放仓库相关规则，比如这个项目必须跑什么测试、哪些目录不能改、生成文件怎么处理、提交前要做哪些检查。</p> <p>如果你在团队里使用 Claude Code，更推荐把项目级配置放进仓库。这样每个人打开项目时，拿到的是同一套 AI 协作约束，而不是各自凭记忆提醒。</p> <h2 id="单文件脚本为什么重要">单文件脚本为什么重要 </h2><p>项目里强调了 <code>UV</code> 单文件脚本的写法。</p> <p>这类脚本的好处是部署简单。一个 Python 文件就可以声明依赖并运行，不必为了一个 hook 单独维护复杂环境。对 hooks 来说，这很合适，因为很多 hook 只是做一件小事：</p> <ul> <li>检查命令是否允许执行</li> <li>判断文件路径是否安全</li> <li>读取项目规范并返回给 Claude</li> <li>扫描输出中是否包含敏感信息</li> <li>在修改后运行格式化或测试</li> <li>把事件写入日志</li> </ul> <p>Hook 脚本越小，越容易维护，也越不容易变成新的复杂系统。</p> <h2 id="可以做哪些自动化">可以做哪些自动化 </h2><p><code>claude-code-hooks-mastery</code> 展示的方向比较多，实际工作中最常见的是下面几类。</p> <h3 id="1-权限和安全控制">1. 权限和安全控制 </h3><p>这是 hooks 最直接的用途。</p> <p>比如在 Claude Code 准备执行命令之前，先检查命令内容。如果命令包含删除、重置、清空、覆盖等高风险动作，就阻止执行或要求人工确认。</p> <p>类似规则还可以用于文件路径：</p> <ul> <li>不允许修改生产配置</li> <li>不允许写入密钥文件</li> <li>不允许删除迁移脚本</li> <li>不允许触碰指定目录</li> <li>不允许执行未批准的网络命令</li> </ul> <p>这类保护放在工具调用前，比写一句“不要做危险操作”更可靠。</p> <h3 id="2-上下文注入">2. 上下文注入 </h3><p>很多项目都有固定背景：</p> <ul> <li>技术栈</li> <li>编码规范</li> <li>测试命令</li> <li>分支策略</li> <li>目录结构</li> <li>禁止事项</li> <li>生成文件处理规则</li> </ul> <p>这些内容每次手动告诉 Claude Code 很麻烦，也容易漏。Hooks 可以在会话开始或用户提交提示词后，把必要上下文自动注入进去。</p> <p>这相当于给 Claude Code 配一个项目级的工作说明书。它不会替代 README 或开发文档，但能让 AI 在执行任务前更快进入正确状态。</p> <h3 id="3-修改后的验证">3. 修改后的验证 </h3><p>当 Claude Code 修改文件后，可以通过 hook 自动触发检查。</p> <p>常见动作包括：</p> <ul> <li>运行格式化</li> <li>运行 lint</li> <li>运行单元测试</li> <li>检查类型错误</li> <li>扫描生成文件</li> <li>校验 Markdown 或 JSON 格式</li> </ul> <p>这对减少低级错误很有帮助。尤其是 AI 改动多个文件时，修改后自动跑一轮轻量验证，可以更早发现问题。</p> <p>不过也要注意，hook 里不适合默认塞太重的任务。每次文件改动都跑完整测试套件，可能会让体验变得很慢。更实用的做法是按文件类型、目录和任务风险选择检查范围。</p> <h3 id="4-团队规则验证">4. 团队规则验证 </h3><p>如果团队已经有明确约定，可以把一部分约定放进 hooks。</p> <p>比如：</p> <ul> <li>提交信息格式</li> <li>代码风格规则</li> <li>禁止直接修改某些生成文件</li> <li>文档必须同步更新</li> <li>API 变更必须改测试</li> <li>某些目录只能用指定工具生成</li> </ul> <p>这会让 Claude Code 更像团队流程的一部分，而不是一个不受约束的外部助手。</p> <p>当然，hooks 不应该替代 CI。它更适合做本地快速提醒和前置拦截，真正的最终验证仍然应该交给 CI、review 和测试系统。</p> <h3 id="5-子代理和专门任务">5. 子代理和专门任务 </h3><p>README 里还提到子代理相关内容。</p> <p>这类用法适合把复杂任务拆给更专门的流程处理。比如主会话负责理解需求，hook 或配置触发专门的检查、审计、总结、文档整理任务。</p> <p>对个人用户来说，最先值得做的不是复杂代理编排，而是把重复、明确、低风险的动作交给 hooks。等规则稳定后，再考虑更复杂的自动化。</p> <h2 id="statusline-和输出样式">Statusline 和输出样式 </h2><p>项目还覆盖了状态栏和输出样式。</p> <p>这部分看起来像体验细节，但对长期使用 Claude Code 很有意义。状态栏可以展示当前上下文、任务状态、环境信息或提示信息；输出样式则可以让 Claude Code 的回答更符合你的工作习惯。</p> <p>如果你每天都在同一个终端里和 AI 协作，这些细节会影响效率。好的状态提示能减少误操作，也能让你更快判断当前会话是否处在正确项目、正确分支、正确环境里。</p> <h2 id="不要把-hooks-写得过重">不要把 hooks 写得过重 </h2><p>Hooks 很强，但不适合什么都往里面塞。</p> <p>比较好的规则是：</p> <ul> <li>高频动作要快</li> <li>安全拦截要明确</li> <li>输出要短</li> <li>失败原因要可读</li> <li>脚本尽量单一职责</li> <li>重型检查交给显式命令或 CI</li> </ul> <p>如果一个 hook 每次都执行十几秒，用户很快就会想关掉它。如果一个 hook 拦截规则含糊不清，Claude Code 和用户都会难以理解下一步该怎么做。</p> <p>Hooks 最适合处理那些边界清楚的事情：允许或拒绝、补充上下文、记录日志、运行轻量检查、提示下一步。</p> <h2 id="适合怎样的使用者">适合怎样的使用者 </h2><p>如果你只是偶尔让 Claude Code 改一小段代码，可能暂时不需要深入 hooks。</p> <p>但如果你符合下面几种情况，就很适合研究这个项目：</p> <ul> <li>高频使用 Claude Code</li> <li>经常让 AI 修改真实项目代码</li> <li>担心 AI 执行危险命令</li> <li>想把团队规范自动注入 AI 工作流</li> <li>希望修改后自动跑检查</li> <li>想把重复提醒变成配置</li> <li>正在搭建更稳定的 AI 编程流程</li> </ul> <p>尤其是多人协作项目，hooks 的意义会更明显。它可以把一部分团队经验沉淀成脚本，而不是靠每个人临时提醒 AI。</p> <h2 id="使用时要注意">使用时要注意 </h2><p>第一，先从安全类 hook 开始。</p> <p>相比复杂自动化，命令拦截、路径保护、敏感文件检查更容易落地，也更能立刻降低风险。</p> <p>第二，项目级规则要谨慎提交。</p> <p><code>.claude/settings.json</code> 会影响所有使用这个仓库的人。把规则提交前，最好确认它不会过度限制正常开发，也不会依赖只有你本机才存在的路径。</p> <p>第三，hook 输出要简洁。</p> <p>Claude Code 会消费这些输出。输出太长，会污染上下文；输出太模糊，又起不到指导作用。最好只返回必要判断和下一步建议。</p> <p>第四，保持可调试。</p> <p>Hooks 一旦变多，问题可能出在配置、脚本、权限、路径、依赖或 Claude Code 本身。给脚本留下清晰日志，会让后续排查轻松很多。</p> <h2 id="参考">参考 </h2><ul> <li><a class="link" href="https://github.com/disler/claude-code-hooks-mastery" target="_blank" rel="noopener" >disler/claude-code-hooks-mastery</a></li> </ul> <h2 id="最后一句">最后一句 </h2><p><code>Claude Code Hooks</code> 的价值，是把“希望 AI 每次都记住的规矩”变成真正会执行的流程。</p> <p>如果你已经开始把 Claude Code 用在真实项目里，hooks 会是从“会聊天的编程助手”走向“可约束的工程协作者”的关键一步。</p>