Claude Code Hooks 实战：5 个钩子让 AI 编程效率翻倍

了解配置结构

Hooks 配置通过 settings.json 文件管理，有三个作用域：

# 全局钩子（对所有项目生效）
~/.claude/settings.json

# 项目钩子（仅当前项目生效）
.claude/settings.json

# 本地钩子（仅本人可见，不纳入 Git）
.claude/settings.local.json

配置格式模板：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "your-script-here"
          }
        ]
      }
    ]
  }
}

用 /hooks 命令管理钩子（推荐入口）

Claude Code 提供交互式的钩子管理命令，比直接编辑 JSON 更安全：

# 在 Claude Code 对话框中输入：
/hooks

操作流程：选择事件类型 → 选择"Add new hook" → 输入 matcher → 输入命令 → 保存。

验证配置是否生效：

# 查看全局配置
cat ~/.claude/settings.json

# 期望看到 hooks 字段
{
  "hooks": {
    "PostToolUse": [...]
  }
}

钩子1 — 自动格式化代码（PostToolUse + Write）

场景：Claude 每次写完文件，自动运行格式化工具，告别手动 black . 或 prettier。

创建脚本文件：

mkdir -p ~/.claude/hooks
cat > ~/.claude/hooks/auto-format.sh << 'EOF'
#!/usr/bin/env bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

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

case "$FILE_PATH" in
  *.py)
    python -m black "$FILE_PATH" 2>/dev/null && echo "✅ Python 格式化完成: $FILE_PATH"
    ;;
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE_PATH" 2>/dev/null && echo "✅ JS/TS 格式化完成: $FILE_PATH"
    ;;
  *.go)
    gofmt -w "$FILE_PATH" 2>/dev/null && echo "✅ Go 格式化完成: $FILE_PATH"
    ;;
esac
EOF
chmod +x ~/.claude/hooks/auto-format.sh

添加到配置（~/.claude/settings.json）：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{"type": "command", "command": "~/.claude/hooks/auto-format.sh"}]
      },
      {
        "matcher": "Edit",
        "hooks": [{"type": "command", "command": "~/.claude/hooks/auto-format.sh"}]
      }
    ]
  }
}

钩子2 — 拦截危险命令（PreToolUse + Bash）

场景：防止 Claude 执行 rm -rf、git reset --hard 等高风险命令，在执行前提示确认。

cat > ~/.claude/hooks/block-dangerous.sh << 'EOF'
#!/usr/bin/env bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

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

DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "rm -rf \."
  "git reset --hard"
  "git push --force"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qF "$pattern"; then
    jq -n \
      --arg reason "⚠️ 危险命令被钩子拦截: $pattern" \
      '{
        hookSpecificOutput: {
          hookEventName: "PreToolUse",
          permissionDecision: "deny",
          permissionDecisionReason: $reason
        }
      }'
    exit 0
  fi
done

exit 0
EOF
chmod +x ~/.claude/hooks/block-dangerous.sh

添加到全局配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "~/.claude/hooks/block-dangerous.sh"}]
      }
    ]
  }
}

钩子3 — 桌面通知（Notification Hook）

场景：Claude 需要你输入时，自动弹出系统通知（macOS/Linux 均支持）。

macOS 通知脚本：

cat > ~/.claude/hooks/notify-mac.sh << 'EOF'
#!/usr/bin/env bash
INPUT=$(cat)
MESSAGE=$(echo "$INPUT" | jq -r '.message // "Claude Code 需要你的关注"')

osascript -e "display notification \"$MESSAGE\" with title \"Claude Code\" sound name \"Ping\""
EOF
chmod +x ~/.claude/hooks/notify-mac.sh

添加到全局配置（~/.claude/settings.json）：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": "~/.claude/hooks/notify-mac.sh"}]
      }
    ]
  }
}

钩子4 & 5 — 运行测试 + Git 自动存档

钩子4：写文件后自动运行测试：

cat > ~/.claude/hooks/run-tests.sh << 'EOF'
#!/usr/bin/env bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if echo "$FILE_PATH" | grep -qE '\.(test|spec)\.(ts|js|py)$'; then
  echo "🧪 检测到测试文件变更，运行测试..."
  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
  if [ -f "package.json" ]; then
    npm test --silent 2>&1 | tail -5
  elif [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
    python -m pytest --tb=short -q 2>&1 | tail -10
  fi
fi
EOF
chmod +x ~/.claude/hooks/run-tests.sh

钩子5：每次 Claude 完成工作自动 Git 存档：

cat > ~/.claude/hooks/git-checkpoint.sh << 'EOF'
#!/usr/bin/env bash
cd "$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0

if ! git diff --quiet || ! git diff --staged --quiet || \
   [ -n "$(git ls-files --others --exclude-standard)" ]; then
  TIMESTAMP=$(date '+%Y-%m-%d %H:%M')
  git add -A
  git commit -m "checkpoint: Claude Code 自动存档 [$TIMESTAMP]" --no-verify 2>/dev/null
  echo "📦 Git 存档完成: [$TIMESTAMP]"
fi
EOF
chmod +x ~/.claude/hooks/git-checkpoint.sh

在项目配置中启用（.claude/settings.json）：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{"type": "command", "command": "~/.claude/hooks/run-tests.sh"}]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": "~/.claude/hooks/git-checkpoint.sh"}]
      }
    ]
  }
}