让 AI 听你的：Claude Code Hooks 完整指南与自动化教程

相信 Claude Code 这个 AI 编程助手已经成为很多开发者终端里的常客了。它在快速开发新功能、查找 Bug 和整理代码方面表现出色。

但作为开发者，我们都知道，大语言模型（LLM）的本质是“概率性”的。这意味着当你要求它写完代码后“记得”运行测试或格式化时，它可能会遗忘或误解。我们渴望的是 确定性！

这正是 Claude Code Hooks 横空出世的原因。它将那些依赖聊天指令的不确定性，变成了每次都会触发的确定性命令。Claude Code Hooks 不仅仅是一个功能更新，它标志着 AI 编程范式的转变——从依赖 AI 的“概率性理解”，到构建可靠的“确定性系统”。

简单来说，Claude Code Hooks 是用户自定义的 Shell 命令，它作为自动触发器，在 Claude Code 运行的特定时刻执行自定义脚本。这使得你的开发规范得以强制执行，实现可靠的、自动化的工作流。

一、Claude Code Hooks 的工作原理与四大核心事件

Claude Code Hooks 的配置存储在 JSON 文件中，通常位于项目目录的 .claude/settings.json 或用户设置目录的 ~/.claude/settings.json。您可以在此文件中定义 Claude Code 生命周期中想要监听的“事件”。

以下是您需要了解的几个最重要的 Claude Code Hooks 事件：

Hook 事件	触发时机	常见用途
PreToolUse 钩子	在 Claude Code 运行工具（如写入文件或执行命令）之前。	安全与权限：验证命令，阻止危险操作（如 `rm -rf`），或修改工具输入参数。
PostToolUse 钩子	在工具成功完成之后。	质量保障：自动格式化代码，运行测试套件，或记录操作日志。
Notification 钩子	当 Claude Code 发送通知时。	自定义提醒：发送桌面通知或 Slack 提醒，告知任务完成或需要用户输入。
Stop 钩子	当主 AI 智能体完成其整个响应时。	会话收尾：触发最终动作，如生成工作总结或自动备份/提交更改。
UserPromptSubmit 钩子	当您提交提示词，但在 AI 处理它之前。	上下文注入：自动为提示添加额外上下文（如当前时间或 Git 分支信息），或验证提示安全性。

通过混合搭配这些 Claude Code Hooks 事件，您可以构建几乎可以自行运行的开发循环。

二、Claude Code Hooks 使用教程：记录命令日志

为了让您快速上手 Claude Code Hooks，我们以最简单的“记录所有执行的 Bash 命令”为例，进行手把手教学。

1. 准备工作

您需要安装 jq 工具，这是一个用于命令行中处理 JSON 数据的工具，因为 Claude Code Hooks 会通过 stdin 传入 JSON 格式的数据。

2. 打开 Hooks 配置

在 Claude Code 的终端中输入斜杠命令 /hooks。

3. 选择事件与匹配器

选择 PreToolUse 钩子事件。
选择 + 添加新匹配器…。
输入 Bash。这告诉 Claude Code，只对 Bash 工具的调用运行此 Hooks 脚本。

小贴士： 您可以使用 * 或留空来匹配所有工具。

4. 添加 Hook 命令

选择 + 添加新钩子…，并输入以下命令。该命令使用 jq 解析传入的 JSON 数据，提取出 command 和 description，并将其追加到日志文件中：

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

5. 保存配置

选择存储位置，例如选择用户设置（User settings）。这样，该 Claude Code Hooks 将应用于您所有项目。

6. 验证和测试您的 Hooks

您可以再次运行 /hooks 或查看 ~/.claude/settings.json 文件来验证配置是否已注册。
要求 Claude Code 运行一个简单命令，例如 ls。
检查您的日志文件：cat ~/.claude/bash-command-log.txt。您应该会看到类似 ls - Lists files and directories 的记录。

现在，您已经成功设置了您的第一个 Claude Code Hooks！

三、Claude Code Hooks 的高级应用场景

一旦掌握了基本用法，您可以利用 Claude Code Hooks 实现更强大的自动化。

1. 自动格式化和 Linting（PostToolUse）

这是最常见的 Claude Code Hooks 用例。通过在文件修改后自动运行格式化工具，您可以保持代码库的整洁。

实现方式： 配置 PostToolUse 钩子，匹配 Edit|MultiEdit|Write 工具，然后运行 Prettier 或 Black 等格式化命令。
示例： 每次 Claude Code 编辑 .ts 文件后，自动运行 Prettier：

{
"hooks":{
"PostToolUse":[
{
"matcher":"Edit|Write",
"hooks":[
{
"type":"command",
"command":"jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
}
]
}
]
}
}

2. 强制执行测试和质量检查（PostToolUse）

使用 Claude Code Hooks 确保 AI 引入的新代码不会破坏现有功能。

实现方式： 配置 PostToolUse 钩子，自动对被修改的文件运行您的测试套件（如 pytest 或 npm test）。如果测试失败，您可以让 Hook 阻止 Claude Code 继续执行。

3. 文件保护与安全策略（PreToolUse）

利用 PreToolUse 钩子的阻止能力，在危险操作发生前设置安全防护。

实现方式： 配置 PreToolUse 钩子，检查 Claude Code 尝试修改的文件路径是否包含敏感信息（如 .env、secrets.yml 或 .git/ 目录）。如果检测到，Hook 可以返回退出代码 2 或特定的 JSON 输出，阻止工具调用并向 Claude 提供反馈。

4. 集成通知和多任务协调（Notification & Stop）

通过 Notification 钩子集成 Slack 或桌面通知系统，让您在执行长时间任务时可以安心去做其他事情。Stop 钩子则可以用于任务完成后的语音通知，或者自动创建 Git 备份提交。

四、安全提示和最佳实践

Claude Code Hooks 虽然强大，但由于它们使用您当前环境的凭据自动执行任意 Shell 命令，因此必须谨慎对待安全问题。

始终验证输入： 永远不要盲目信任输入数据。
使用引号保护变量： 在 Shell 脚本中，确保使用 "$VAR" 而不是 $VAR 来引用变量，以防止命令注入。
阻止路径遍历： 检查文件路径中是否包含 ..。
保持速度： Claude Code Hooks 是同步执行的，会阻塞 AI 代理的循环。理想情况下，Hook 的执行时间应少于 100 毫秒。对于耗时的操作（如运行完整测试），应考虑使用 run_in_background 参数或将操作转移到后台异步任务。
利用 stop_hook_active： 在处理 Stop 或 SubagentStop 钩子时，检查 stop_hook_active 状态，以防止 Hook 导致 Claude Code 无限次地强制继续执行。

Claude Code Hooks 是将 AI 辅助编程提升到下一个层次的关键功能。通过定制这些钩子，您将真正获得与 AI 协作的主导权！

让 AI 听你的：Claude Code Hooks 完整指南与自动化教程