Hooks：让关键步骤自动发生

01先选正确的事件

Hook 把脚本或其他处理逻辑接到 Claude Code 的生命周期。PreToolUse 适合工具执行前的检查，PostToolUse 可处理执行结果，Stop 发生在响应结束阶段。

Hook 的事件输入、返回格式与阻断行为各不相同。以对应事件的官方参考为准，不把一个事件的处理方式直接复制到另一个事件。

02从一个小而确定的检查开始

例如在修改后对目标文件运行格式检查，或在关键动作前检查路径。Hook 应该有明确输入、可预测输出和合理超时，失败时给出修复线索。

• 先在普通终端中验证脚本，再接入 Hook。
• 把日志写到可追踪的位置，并过滤敏感字段。
• 区分检查失败、脚本错误与超时。
• 避免每次工具调用都触发完整构建。

03团队落地时评审执行范围

Hook 是会执行实际逻辑的项目组成部分，需要像 CI 脚本一样接受审查。依赖、外部请求、凭证读取和文件写入应能在代码中看清。

如果 Hook 频繁阻断正常工作，先收窄 matcher 与检查范围。减少噪声能让真正的错误更容易被发现。

04为 Hook 写一张输入输出契约

在接入配置前，把事件名称、接收字段、正常退出、异常退出和超时行为写在脚本旁。不同事件的输出协议不同，尤其不要混用 stdout 的结构化结果与普通调试日志。

如果 Hook 用于阻断动作，必须测试“应该允许”和“应该拒绝”两类输入。只证明它能运行，无法证明它执行了你的策略。

• 事件：什么时候触发，是否在你需要的动作之前。
• 范围：matcher 是否覆盖目标工具，是否误匹配其他调用。
• 结果：失败时是否给 Claude 足够的修复信息。
• 依赖：脚本在 CI、Windows 和团队其他机器上是否可运行。