Claude Code Hooks 实战：自动化你的开发流程

Hooks 让你在 Claude Code 的每一步操作前后插入自定义逻辑，这才是自动化的正确打开方式。

用了一段时间 Claude Code 后，你会发现一个问题：有些操作你每次都要手动确认，有些检查你每次都要自己跑，有些规范你每次都要提醒 AI。

比如：

• 每次改完代码，你都要手动跑 eslint
• 每次 AI 要执行危险命令，你都想多看一眼
• 每次提交前，你都想自动跑测试

Hooks 就是来解决这些"每次都要"的问题的。

---

一、Hooks 是什么

Hooks 是 Claude Code 的事件系统。它让你在特定时间点自动执行 shell 命令。

你可以把它理解为 Git Hooks 的 AI 版本——Git Hooks 在 commit/push 时触发，Claude Code Hooks 在 AI 使用工具/执行命令时触发。

Hooks 配置在 .claude/settings.json 里：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hook": "echo 'AI 要执行命令了'"
      }
    ]
  }
}

---

二、四种 Hook 类型

1. PreToolUse —— 工具执行前

在 AI 调用任何工具之前触发。这是最常用的 Hook。

用途：

• 拦截危险操作
• 添加额外检查
• 修改工具参数

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hook": "/path/to/check-command.sh"
      }
    ]
  }
}

Hook 脚本通过 stdin 接收 JSON 输入，包含工具名和参数。脚本可以返回：

• 退出码 0：允许执行
• 退出码 2：阻止执行
• stdout 输出 JSON 可以修改工具输入或给 AI 反馈

实战例子：阻止删除操作

#!/bin/bash
# block-dangerous-commands.sh
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')

# 检查是否包含危险命令
if echo "$command" | grep -qE 'rm\s+-rf|drop\s+table|git\s+push\s+--force'; then
  echo '{"decision": "block", "reason": "危险命令被 Hook 拦截"}'
  exit 2
fi

exit 0

2. PostToolUse —— 工具执行后

在工具执行完成后触发。适合做后处理和自动化检查。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hook": "/path/to/auto-lint.sh"
      }
    ]
  }
}

实战例子：写文件后自动格式化

#!/bin/bash
# auto-lint.sh
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')

if [ -z "$file_path" ]; then
  exit 0
fi

# 根据文件类型自动格式化
case "$file_path" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$file_path" 2>/dev/null
    echo '{"message": "已自动格式化: '"$file_path"'"}'
    ;;
  *.py)
    python -m black "$file_path" 2>/dev/null
    echo '{"message": "已自动格式化: '"$file_path"'"}'
    ;;
esac

exit 0

3. Notification —— 通知

在 Claude Code 发出通知时触发。比如任务完成、等待输入等。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hook": "/path/to/notify.sh"
      }
    ]
  }
}

实战例子：任务完成时发系统通知

#!/bin/bash
# notify.sh
input=$(cat)
message=$(echo "$input" | jq -r '.message // "Claude Code 需要你的注意"')

# macOS 系统通知
osascript -e "display notification \"$message\" with title \"Claude Code\""

exit 0

4. Stop —— 任务结束

在 Claude Code 停止执行（自动完成或用户中断）时触发。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hook": "/path/to/on-stop.sh"
      }
    ]
  }
}

实战例子：任务结束后自动跑测试

#!/bin/bash
# on-stop.sh
# 检查是否有文件变更
if git diff --quiet; then
  exit 0
fi

# 有变更就跑测试
npm test 2>&1 | tail -20

exit 0

---

三、matcher 怎么写

matcher 字段决定 Hook 在什么条件下触发。它匹配的是工具名。

常用工具名：

• Bash —— 执行 shell 命令
• Read —— 读取文件
• Write —— 写入文件
• Edit —— 编辑文件
• Glob —— 文件搜索
• Grep —— 内容搜索

支持正则和 | 分隔多个匹配：

// 匹配所有文件写入操作
{ "matcher": "Write|Edit" }

// 匹配所有操作（空字符串匹配一切）
{ "matcher": "" }

// 只匹配 Bash 命令
{ "matcher": "Bash" }

---

四、完整配置示例

这是我自己在用的配置，供参考：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hook": "/Users/me/.claude/hooks/block-dangerous.sh"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hook": "/Users/me/.claude/hooks/auto-format.sh"
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hook": "/Users/me/.claude/hooks/system-notify.sh"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hook": "/Users/me/.claude/hooks/run-tests.sh"
      }
    ]
  }
}

这套配置实现了：

1. AI 执行 shell 命令前，自动拦截危险操作
2. AI 写/改文件后，自动跑 prettier/black 格式化
3. Claude Code 有通知时，弹系统通知
4. 任务结束时，自动跑一遍测试

---

五、Hook 脚本的输入输出

每个 Hook 脚本通过 stdin 接收 JSON 数据，格式大致如下：

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/test"
  },
  "session_id": "abc123"
}

脚本可以通过 stdout 返回 JSON 来影响 Claude Code 的行为：

// PreToolUse: 阻止执行
{"decision": "block", "reason": "不允许删除操作"}

// PostToolUse: 给 AI 反馈
{"message": "lint 发现 3 个警告，请修复"}

退出码也很重要：

• 0 —— 成功/允许
• 2 —— 阻止操作（仅 PreToolUse）
• 其他非零 —— Hook 执行失败（不影响 Claude Code 继续）

---

六、注意事项

1. Hook 脚本要快。它们是同步执行的，太慢会影响 Claude Code 的响应速度。目标是 1 秒内完成。

2. 错误处理要做好。Hook 脚本崩了不应该阻塞 Claude Code。做好 stderr 输出方便调试。

3. 用绝对路径。不要假设工作目录，Hook 脚本里的路径都用绝对路径。

4. 先测试再上线。手动跑一遍 Hook 脚本，确认输入输出格式正确。

5. 权限别忘了。chmod +x your-hook.sh。

---

总结

Hooks 是 Claude Code 里最被低估的功能。大部分人用 Claude Code 就是 "说一句话，等结果"，但 Hooks 让你能真正定制 AI 的行为。

推荐的入门路径：

1. 先配一个 Notification Hook——任务完成时收到通知，这个最实用
2. 再配一个 PostToolUse Hook——自动格式化代码，减少手动操作
3. 最后玩 PreToolUse Hook——拦截危险操作，建立安全防线

Hooks 的本质是把你的开发规范变成自动执行的代码，而不是每次都要口头提醒 AI。这才是开发流程自动化的正确姿势。