1. Hooks 要解决的五个痛点#

• AI 忘记项目约定（如用 Bun 不用 npm）
• Claude 误改敏感文件导致配置泄露
• 代码格式不符合项目规范，需手动格式化或等 CI 报错
• 并行运行多个 Claude 时错过等待输入提示，任务卡住
• 无法审计 Claude 执行了哪些 Bash 命令

2. Hooks 的三大核心概念#

生命周期钩子：Claude Code 有固定流程（会话开始 → 加载配置 → 接收输入 → 调用工具 → 生成响应 → 会话结束），Hooks 在关键节点插入自定义逻辑，类比 Git pre-commit 或 npm postinstall。

确定性控制：CLAUDE.md 是给 AI 看的建议，Hooks 是强制执行的规则。这是 Hooks 区别于指令文件的关键。

自动化工作流：格式化代码、发送通知、记录日志、拦截危险操作，无需人工干预。

3. 16 种 Hook 事件（按生命周期分类）#

会话管理（4 种）：

• SessionStart：会话开始或恢复，每个会话触发一次
• SessionEnd：会话终止，清理资源
• InstructionsLoaded：CLAUDE.md 加载时触发
• ConfigChange：配置文件变更，可阻止未授权变更

用户交互（2 种）：

• UserPromptSubmit：用户提交提示时，可过滤敏感词
• Notification：Claude 需要用户输入时触发

工具调用（4 种）：

• PreToolUse：工具执行前拦截，可阻止危险命令
• PermissionRequest：权限请求，可自动批准/拒绝
• PostToolUse：工具执行成功后做后处理
• PostToolUseFailure：工具执行失败后处理

子代理与团队（4 种）：

• SubagentStart / SubagentStop：监控子代理行为
• TeammateIdle：团队成员空闲时分配任务
• TaskCompleted：任务标记完成时验证

其他（2 种）：

• Stop：Claude 完成响应后触发
• PreCompact：上下文压缩前保存关键信息

关键维度：可阻止（exit 2）的事件和匹配器支持的事件不同，不是所有事件都可拦截。

4. 四种 Hook 类型#

选择策略：确定性规则用 Command，需要远程服务用 HTTP，需要判断力用 Prompt，需要验证实际状态用 Agent。

5. Hook 执行流程#

1
事件触发 → 匹配器检查（可选）→ Hook 处理器执行 → Claude Code 处理结果
2
                                                          ├── exit 0：允许继续
3
                                                          ├── exit 2：阻止操作
4
                                                          └── 其他：非阻塞错误，记录日志

同一事件的多个 Hook 并行执行，自动去重。exit 2 是唯一能阻止操作的方式。

6. 六个实战场景#

场景一：任务完成通知（Stop Hook）

• 问题：Claude 跑耗时任务时不知道何时完成
• 方案：Stop Hook + macOS 桌面通知
• 关键：检查 stop_hook_active 避免无限循环

场景二：等待输入提醒（Notification Hook）

• 问题：并行运行多个 Claude 时错过等待输入提示
• 方案：Notification Hook + 声音提醒 + 项目名称
• 关键：matcher idle_prompt 只匹配等待输入场景

场景三：代码自动格式化（PostToolUse Hook）

• 问题：Claude 生成代码格式不符合规范
• 方案：PostToolUse + Prettier/Black/gofmt 多工具支持
• 关键：matcher Write|Edit|MultiEdit，设置 timeout 15s

场景四：保护敏感文件（PreToolUse Hook）

• 问题：Claude 误改 .env、package-lock.json、SSH 密钥
• 方案：PreToolUse + 文件路径模式匹配，exit 2 阻止
• 关键：支持通配符，消息输出到 stderr

场景五：上下文重新注入（SessionStart Hook）

• 问题：上下文压缩后 Claude 忘了项目约定
• 方案：SessionStart + Git 历史 + 项目规则文件动态注入
• 关键：matcher compact 只在上下文压缩后触发

场景六：命令审计日志（PostToolUse Hook）

• 问题：无法追溯 Claude 执行了哪些命令
• 方案：PostToolUse + 结构化日志（时间戳 + 会话 ID + 工作目录）
• 关键：可用于 SIEM 分析和问题复现

7. 最佳实践#

分层配置策略：

• 用户级（~/.claude/settings.json）：通用通知、通用保护
• 项目级（.claude/settings.json）：项目特定规则，提交到 Git
• 本地级（.claude/settings.local.json）：敏感环境变量，gitignored
• 策略级（企业）：管理员强制安全规则

脚本健壮性：使用 set -euo pipefail，验证 JSON 输入，使用默认值 // empty

性能优化：高频事件保持快速（<1s），合理设置超时，非关键任务用 async

调试：Ctrl+O 切换详细模式，用 echo 模拟 JSON 输入手动测试

1. Hooks 与 CLAUDE.md 的关系不是替代而是分层控制#

很多人会混淆 Hooks 和 CLAUDE.md 的作用。实际上它们构成一个控制金字塔：

1
顶层（软约束）：CLAUDE.md、system prompt — 引导 AI 的"思考方式"
2
    ↓
3
中层（半硬约束）：PreToolUse Hook — 在 AI 行动前拦截
4
    ↓
5
底层（硬约束）：PostToolUse Hook、exit 2 机制 — 强制执行、无法绕过

CLAUDE.md 适合：编码风格、架构决策、技术栈偏好、文档规范 Hooks 适合：安全拦截、格式化、审计日志、通知、权限控制

实际建议：先用 CLAUDE.md 引导 AI 行为，对重要的、不可违反的规则再用 Hooks 兜底。两层都有成本——CLAUDE.md 消耗 context window，Hooks 增加执行延迟。所以不要把所有规则都搬到 Hooks 层，只在”必须强制执行”的场景使用。

2. 被忽略的高价值 Hook：PreCompact#

文章中 PreCompact 只是一笔带过，但我认为这是最值得深挖的 Hook。

Claude Code 的上下文窗口有限，到达阈值后会触发 compaction（上下文压缩），丢失早期对话中的关键信息。PreCompact 在压缩前触发，可以做三件事：

• 将关键项目规则写入文件（Claude 下次读取文件时可恢复）
• 记录当前工作进度和待办事项
• 保存重要的上下文摘要到 .claude/ 目录

这是对抗”AI 遗忘”最有效的机制。可以结合 SessionStart Hook 实现上下文自愈：压缩前保存 → 恢复后重新注入。

3. 企业级场景：安全审计与合规#

文章提到了 HTTP Hook 做远程审计，但没有展开企业级场景。考虑以下需求：

• SOC 2 / ISO 27001 合规：需要记录所有 AI 对代码库的操作，包括时间戳、操作者（哪个 Claude 实例）、具体命令、执行结果。这可以通过 PostToolUse HTTP Hook + 中央日志服务实现。
• 代码审批流：在 PreToolUse 阶段，如果 Claude 要修改关键文件（如支付相关代码），可以要求人工审批（exit 2 暂停 + 通知）。
• 多租户隔离：在 SaaS 开发环境中，确保 Claude 不会跨项目访问数据。

4. Hooks 的局限性和风险#

性能开销：每个 PreToolUse / PostToolUse 都会增加延迟。如果 Claude 频繁调用工具（比如探索大型代码库），Hook 延迟会累积。高频事件（Notification）的脚本必须在 <1s 内完成。

调试复杂度：Hook 脚本出错时，错误信息可能不直观。特别是 Shell profile 中的 echo 语句会干扰 JSON 解析（文章已经提到），这是一个典型的”隐性 bug”。

并发安全：同一事件的多个 Hook 并行执行，如果都写同一个日志文件，可能出现竞态条件。需要使用文件锁或原子写入。

安全边界：Hook 脚本本身是 shell 命令，如果脚本路径被篡改（比如 .claude/hooks/ 被恶意修改），可能执行任意命令。需要配合文件完整性检查。

5. 未来方向：从 Hooks 到智能体治理#

当前 Hooks 是”规则驱动”的——你定义规则，它执行。未来可能的方向：

• 动态 Hook 生成：根据项目类型自动推荐 Hook 配置（检测到 Python 项目自动生成 Black 格式化 Hook）
• Hook 市场：社区共享预配置的 Hook 包，类似 VS Code 扩展
• AI 辅助 Hook 编写：用自然语言描述需求，自动生成 Hook 脚本
• 可观测性集成：Hook 执行指标（成功率、延迟、阻止率）自动上报，生成仪表盘

6. 与我工作方式的关联#

作为前后端全栈开发者，文章提到的几个场景与我直接相关：

• 代码自动格式化：前端项目用 Prettier + ESLint，后端 Node.js 项目也有 lint 规则。PostToolUse Hook 可以在 Claude 每次改代码后自动格式化，避免 CI 失败。
• 保护敏感文件：.env、package-lock.json、SSH 密钥都是需要保护的文件。PreToolUse 的 exit 2 机制比 CLAUDE.md 中”不要修改 .env”这种软约束可靠得多。
• 命令审计日志：调试问题时经常需要回顾”刚才 Claude 做了什么”。结构化日志比手动翻对话记录高效得多。
• 上下文重新注入：长对话中 Claude 经常忘记项目约定（比如”用 TypeScript 严格模式”），SessionStart compact matcher 可以解决这个问题。

本文档基于 腾讯云开发者社区文章 整理总结，并加入了扩展理解