Claude Code Hooks实战指南：自动化代码格式化与任务通知配置

Hooks 对于开发者而言并不陌生，主流的编程框架都提供了各自的 Hooks 机制，其核心目的通常是为开发者提供在特定生命周期或流程节点介入和自定义操作的能力。

在使用 Claude Code 进行开发时，我们常常会遇到一些重复性任务或信息统计需求。虽然可以尝试在规则文件或 CLAUDE 指令中进行约束，但效果往往不可控，存在“幻觉”。

例如：

• 每次生成代码后，都需要手动运行 Prettier 等工具进行格式化。虽然集成开发环境（IDE）可以设置保存时自动格式化，但团队成员安装的格式化插件各异，难以统一代码风格。
• 想要记录 Claude 执行了哪些命令，只能逐行翻阅冗长的上下文，效率低下且容易遗漏。
• 希望在 Claude 完成任务后获得自动通知，但目前仅有部分编辑器（如 Cursor）在任务完成后提供了状态栏和声音提醒。

上述痛点，都可以通过配置 Claude Code 的 Hooks 功能来实现自动化处理。

什么是 Claude Code Hooks？

简而言之，Hooks 是预定义在 Claude Code 工作流特定节点自动触发的命令或脚本。Claude Code 提供了 8 个关键的事件钩子（Hook Events）：

• UserPromptSubmit：在用户提交提示词后、Claude 开始处理前运行。（可拦截）
• PreToolUse：在调用任何工具（如 Bash、Write）之前运行。（可拦截）
• Stop：当 Claude Code 完成一次响应时运行。（可拦截）
• Subagent Stop：当子代理（Subagent）完成任务时运行。（可拦截）
• PostToolUse：在工具调用完成后运行。
• Notification：当 Claude Code 发送通知时运行。
• PreCompact：在 Claude Code 即将执行上下文压缩操作前运行。
• SessionStart：当 Claude Code 启动新会话或恢复现有会话时运行。

这 8 个钩子可根据其“拦截”能力分为两类：前 4 个（UserPromptSubmit, PreToolUse, Stop, Subagent Stop）能够在事件发生时阻断原有流程；后 4 个则主要用于执行附加操作或通知。

Hooks 配置详解

Hooks 支持多级别配置，以适应不同范围的需求：

• ~/.claude/settings.json：用户全局设置，影响所有项目。
• .claude/settings.json：项目级设置，通常纳入版本控制以便团队共享。
• .claude/settings.local.json：项目级本地设置，通常被 .gitignore 忽略，用于存放个人或敏感配置。

其基本配置结构如下所示：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\\(.tool_input.command) - \\\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

实战：配置命令执行日志 Hook

下面以“自动记录所有执行的 Bash 命令”为例，演示如何通过交互式命令创建 Hook。

步骤 1：启动 Hook 配置向导
在 Claude Code 中输入命令 /hook，即可进入图形化配置界面。

步骤 2：选择 Hook 触发时机
选择 PreToolUse，表示在工具执行前触发我们的钩子。

步骤 3：设置匹配器（Matcher）
输入 Bash 作为匹配器，这意味着此钩子只针对 Bash 工具调用生效。

步骤 4：定义要执行的命令
输入用于提取和记录命令的 Shell 命令：

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

命令解析：

1. jq -r：用于处理 JSON 数据，-r 输出原始字符串。
2. \"\(.tool_input.command) - \(.tool_input.description // \"No description\")\"：提取 tool_input 中的 command（命令内容）和 description（描述），若无描述则使用“No description”。
3. >> .claude/bash-command-log.txt：将格式化后的字符串追加写入到指定日志文件中。

步骤 5：选择配置保存位置
选择将配置保存到 项目级别 的 .claude/settings.local.json 文件中。

步骤 6：测试与生效
配置完成后，需要完全退出并重启 Claude Code 客户端，新的 Hook 配置才会生效。重启后，执行任意 Bash 命令，即可在项目根目录下的 .claude/bash-command-log.txt 文件中查看到相应的执行记录。

进阶应用场景

场景一：代码自动格式化

通过 Hook 实现代码修改后的自动格式化，确保代码风格统一，减少后期维护成本。以下示例配置在 PostToolUse 阶段，对编辑过的 .html 文件自动运行 Prettier。

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

注意事项：

1. 若在项目级配置，需确保项目已安装 Prettier (npm i prettier)；若为全局配置，需全局安装 (npm i prettier -g)。
2. 若配置后 Edit 等工具报错，可能是命令语法错误（如引号使用不当），需检查修正。

场景二：任务完成桌面通知

配置在 Stop 钩子中，当 Claude Code 完成响应后，在 macOS 系统桌面发送通知。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"所有任务已完成！\" with title \"Claude Code\" subtitle \"工作完成\"'"
          }
        ]
      }
    ]
  }
}

对于其他操作系统，可替换为相应的通知命令，例如 Linux 系统可使用 notify-send 命令。

更多创意场景

基于 Hooks 的扩展性，可以构建更强大的自动化工作流：

• 代码质量保障：提交前自动运行 ESLint 检查、扫描并移除遗留的 console.log、自动为新增文件添加版权头注释等。
• 团队协作增强：代码变更后自动同步到共享目录、发送变更摘要到协作平台、关联更新技术文档等。
• 个人效率工具：统计每日代码产出、自动生成简易工作日报、定时备份关键配置文件等。
• 规范执行器：强制执行命名规范、自动为复杂函数添加JSON Schema 注释模板等。

总结

Claude Code Hooks 功能将其从被动的对话助手，转变为一个可深度定制的自动化协作平台。通过合理配置各类钩子，我们可以将代码格式化、质量检查、通知提醒等重复性操作无缝嵌入到 AI 辅助开发的工作流中，实现“需求提出 → AI 执行 → 自动检查/优化 → 结果通知”的顺畅闭环，从而显著提升开发效率与代码一致性。