Claude Code Hooks 实战：用确定性规则约束 AI 行为

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-sensitive-files.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/protect-sensitive-files.sh
 
# 从 stdin 读取 JSON 输入
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
# 定义敏感文件模式
SENSITIVE_PATTERNS='(\.env|\.env\.local|\.env\.production|secrets\.yaml|credentials\.json|id_rsa|\.pem)$'
 
if [[ -n "$FILE_PATH" && "$FILE_PATH" =~ $SENSITIVE_PATTERNS ]]; then
  # exit 2 阻断操作，stderr 内容会反馈给 Claude
  echo "BLOCKED: 不允许修改敏感文件 $FILE_PATH" >&2
  echo "如果需要修改配置，请在 CLAUDE.md 中明确授权，或手动编辑该文件" >&2
  exit 2
fi
 
# exit 0 或不输出，允许操作继续
exit 0

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PROJECT_DIR}/.claude/hooks/auto-format.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/auto-format.sh
 
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
# 只在文件存在且是目标类型时执行
if [[ ! -f "$FILE_PATH" ]]; then
  exit 0
fi
 
# 根据文件类型选择格式化工具
case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE_PATH" 2>/dev/null || true
    npx eslint --fix "$FILE_PATH" 2>/dev/null || true
    ;;
  *.json)
    npx prettier --write "$FILE_PATH" 2>/dev/null || true
    ;;
  *.md)
    npx prettier --write "$FILE_PATH" 2>/dev/null || true
    ;;
esac
 
# git add 让修改进入暂存区
git add "$FILE_PATH" 2>/dev/null || true
 
exit 0

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous-commands.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-dangerous-commands.sh
 
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 
# 危险命令模式
# 注意：这里用正则匹配，但命令解析有局限性
DANGEROUS_PATTERNS=(
  'rm\s+-rf\s+/'           # 递归删除根目录
  'rm\s+-rf\s+\*'          # 删除当前目录所有文件
  'git\s+reset\s+--hard'   # 丢弃所有未提交更改
  'git\s+checkout\s+--'    # 丢弃文件修改
  'git\s+push\s+.*--force' # 强制推送
  'DROP\s+TABLE'            # SQL 删除表
  'DROP\s+DATABASE'        # SQL 删除数据库
  'mkfs\.'                 # 格式化文件系统
  'dd\s+if=.*of=/dev/'     # 写入设备文件
)
 
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qEi "$pattern"; then
    echo "BLOCKED: 检测到危险命令" >&2
    echo "匹配模式: $pattern" >&2
    echo "命令: $COMMAND" >&2
    echo "" >&2
    echo "如果确实需要执行，请：" >&2
    echo "1. 明确说明原因和影响范围" >&2
    echo "2. 在 CLAUDE.md 中添加例外规则" >&2
    echo "3. 或手动在终端执行" >&2
    exit 2
  fi
done
 
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "if": "Bash(rm *)",
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-rm.sh"
          }
        ]
      }
    ]
  }
}

# ❌ 坏做法：用 exit 1 试图阻断
if [[ "$FILE_PATH" =~ \.env$ ]]; then
  echo "BLOCKED: 不能修改 .env 文件" >&2
  exit 1  # 错误：exit 1 不会阻断操作
fi
 
# ✅ 好做法：用 exit 2 阻断
if [[ "$FILE_PATH" =~ \.env$ ]]; then
  echo "BLOCKED: 不能修改 .env 文件" >&2
  echo "请手动编辑或明确授权" >&2
  exit 2  # 正确：exit 2 阻断操作并反馈信息
fi

# ❌ 坏做法：直接用 jq 不读 stdin
FILE_PATH=$(jq -r '.tool_input.file_path')  # 错误：jq 收不到输入
 
# ✅ 好做法：先用 cat 读取 stdin
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')
 
# ✅ 更好的做法：一行管道
FILE_PATH=$(cat | jq -r '.tool_input.file_path // empty')

// ❌ 坏做法：matcher 小写
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",  // 错误：工具名是 PascalCase
        "hooks": [...]
      }
    ]
  }
}
 
// ✅ 好做法：matcher 正确大小写
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",  // 正确：Bash、Edit、Write 都是 PascalCase
        "hooks": [...]
      }
    ]
  }
}
 
// ✅ 好做法：多个工具用 | 分隔
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",  // 匹配 Edit 或 Write 工具
        "hooks": [...]
      }
    ]
  }
}

// ❌ 坏做法：复杂逻辑内联
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "CMD=$(cat | jq -r '.tool_input.command') && if echo \"$CMD\" | grep -qE 'rm -rf /'; then echo BLOCKED >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}
 
// ✅ 好做法：脚本外置
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.sh"
          }
        ]
      }
    ]
  }
}