Hooks in Claude Code

📚 Hooks 核心概念学习笔记

一、 Hooks 定义与核心特性

• 定义： Hooks 允许在 Claude 代码生命周期的特定时间点运行自定义命令。
• 核心特性： Hooks 是确定性的 (Deterministic)，意味着它们会无例外地、每次都运行。
• 主要用途： 自动格式化、记录执行命令（合规性）、阻止危险操作、发送通知。

二、 Hooks 配置与事件类型

• 配置位置： 在 settings. json 文件中配置。
• 配置要素： 选择事件 (Event) → 可选的匹配器 (Matcher) → 要运行的命令 (Command)。
• 关键事件类型：
• user prompt submit：用户提交提示词前。
• pre-tool use：工具调用执行前。
• post-tool use：工具调用完成后。
• notification：Claude 发送通知时。
• stop：Claude 完成响应时。

三、 关键应用场景

• 自动格式化 (Auto-formatting)：
• 配置： 使用 post-tool use 钩子，设置匹配器为 edit 或 multi-edit。
• 实现： 命令会检查文件扩展名，并运行相应的格式化工具（如 TypeScript 使用 Prettier，Go 使用 Go format）。
• 阻止危险操作 (Blocking)：
• 配置： 使用 pre-tool use 钩子。
• 机制： 钩子接收工具名称和输入。
• 退出代码判断：
• 代码 0 (Exit code 0)：允许操作继续执行 (Proceed)。
• 代码 2 (Exit code 2)：阻止操作 (Block)，并将错误信息反馈给 Claude。
• 应用示例： 阻止写入生产配置目录、阻止包含 rm-rf 的 Bash 命令。

四、 部署与最佳实践

• 作用范围： Hooks 配置在 . Claude/settings. json 中，属于项目级别 (Project level)。
• 团队协作： 必须将 Hooks 提交到代码仓库 (Check into repo)，以确保整个团队自动获得一致的规则。
• 核心原则： 如果某项操作必须“每次都发生且不容失败”，请使用 Hooks，而不是在提示词中要求。

Takeaways

• Hooks 是在 Claude 代码生命周期特定时间运行的确定性自定义命令，用于执行自动格式化、记录或阻止操作。
• 配置位于 settings. json 文件中，通过选择关键事件（如 pre-tool use, post-tool use）来触发相应的命令。
• 阻止危险操作时，通过判断钩子接收的退出代码实现控制：代码 0 表示允许继续执行，代码 2 表示阻止操作。
• Hooks 是项目级别的配置，必须提交到代码仓库，以确保团队成员遵守一致的规则。