Claude Code上下文工程与Hooks深度实战：从配置到自动化的完整指南

┌──────────────── 200K Token 上下文窗口 ────────────────┐
│                                                        │
│  ┌─────────── 系统提示 (~15-20K) ───────────┐          │
│  │  工具定义、安全规则、内置指令              │          │
│  └──────────────────────────────────────────┘          │
│                                                        │
│  ┌─────────── CLAUDE.md层级 (~2-10K) ───────┐          │
│  │  全局 ~/.claude/CLAUDE.md                  │          │
│  │  项目根 ./CLAUDE.md                        │          │
│  │  子目录 ./src/CLAUDE.md                    │          │
│  └──────────────────────────────────────────┘          │
│                                                        │
│  ┌─────────── 对话历史 (~动态增长) ──────────┐          │
│  │  用户消息 + Claude回复 + 工具调用结果      │          │
│  └──────────────────────────────────────────┘          │
│                                                        │
│  ┌─────────── 文件读取 (~按需加载) ──────────┐          │
│  │  Read工具读取的文件内容                     │          │
│  └──────────────────────────────────────────┘          │
│                                                        │
│  ⚠️ 当总使用量超过阈值时，触发自动压缩(compaction)     │
└────────────────────────────────────────────────────────┘

# 全局偏好

## 语言
- 默认使用中文回复，代码注释用英文
- 回复简洁明了，避免冗长解释

## 通用编码规范
- 使用 TypeScript strict mode
- 优先函数式编程风格
- 变量命名使用 camelCase，常量使用 UPPER_SNAKE_CASE
- 提交信息格式：type(scope): description

## 安全
- 永远不要提交 .env 文件
- 不要在代码中硬编码密钥
- 使用环境变量管理敏感配置

# 项目：电商平台后端

## 技术栈
- Node.js 20 + Fastify
- PostgreSQL 16 + Prisma ORM
- Redis 7（缓存与会话）
- Docker + Docker Compose

## 关键命令
- `pnpm dev` — 启动开发服务器（端口3000）
- `pnpm test` — 运行测试套件
- `pnpm lint` — ESLint检查
- `pnpm db:migrate` — 执行数据库迁移
- `pnpm db:seed` — 填充测试数据

## 架构概览

## 关键约定
- 所有API路由必须包含请求验证（使用 TypeBox schema）
- 数据库操作通过 Prisma Repository 模式，不直接写原始SQL
- 错误处理使用 Fastify 的 ErrorHandler，统一错误格式
- 日志使用 pino，禁止 console.log

## 已知陷阱
- Prisma的`findFirst`在无匹配时返回null而非抛错，务必处理null情况
- Redis连接在Docker重启后需要等待5秒才能就绪
- 测试环境使用独立数据库，不要连接开发库

# ❌ 糟糕的写法（浪费token）
我们在这个项目中使用TypeScript作为主要的编程语言，因为TypeScript
提供了类型安全，可以帮助我们在开发过程中捕获更多的错误。所有的新
代码都应该使用TypeScript编写，并且确保类型定义完整...

# ✅ 好的写法（简洁有力）
- TypeScript strict mode，所有新代码必须有完整类型定义

# ❌ 不需要写（代码已表达）
- 使用Express框架
- 入口文件是index.ts

# ✅ 应该写（非显而易见的决策）
- API版本通过URL前缀 /v1/ 管理，主版本变更时创建新路由文件
- 认证中间件顺序：rateLimit → cors → jwt → routeHandler

# src/modules/auth/CLAUDE.md
## 认证模块特定规则
- JWT有效期：access 15min，refresh 7d
- 密码哈希使用 argon2id，不要用 bcrypt
- 登录失败5次后锁定15分钟
- OAuth回调必须验证state参数防CSRF

# ❌ 重复README内容
本项目使用pnpm管理依赖...（省略50字重复内容）

# ✅ 引用已有文档
详细架构说明参见 docs/architecture.md

# 查看当前上下文使用情况
# Claude Code会自动显示上下文使用百分比

# 当上下文使用量达到60-70%时，主动执行压缩
/compact

# 带自定义指令的压缩（推荐）
/compact 保留以下关键信息：1) 已完成的文件修改列表 2) 未完成的重构步骤 3) 当前的错误状态

# 进入规划模式
/plan

# Claude Code会输出详细的修改计划，但不执行任何修改
# 你可以审查计划，确认无误后再执行

# 退出规划模式，开始执行
# Claude会按照计划逐步修改文件

# ❌ 错误做法：一次性读取整个大文件
读取 src/huge-service.ts（3000行）→ 消耗约15000 token

# ✅ 正确做法：分块读取
先读取文件的前50行了解结构 → ~250 token
然后只读取需要修改的函数范围 → ~500 token

# ✅ 更好的做法：让Claude使用offset和limit参数
"读取 src/huge-service.ts 的第200-250行"

flowchart TB
    subgraph "Claude Code 生命周期"
        A[会话启动] --> B[用户发送消息]
        B --> C{PreToolUse Hook}
        C -->|允许| D[工具执行]
        C -->|拒绝/修改| E[返回调整后的参数]
        E --> D
        D --> F{PostToolUse Hook}
        F -->|继续| G[生成回复]
        F -->|注入上下文| G
        G --> H{Stop Hook}
        H -->|通知/清理| I[等待用户下一条消息]
        I --> B

        subgraph "Hook触发点"
            C
            F
            H
        end

        subgraph "Hook能力"
            J[拦截与修改工具参数]
            K[注入额外上下文]
            L[执行副作用操作]
            M[发送通知]
        end
    end

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --check $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code任务完成' '请查看最新修改'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "format-on-edit.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# format-on-edit.sh — 根据文件类型自动格式化

FILE="$CLAUDE_FILE_PATH"

case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE" 2>/dev/null
    npx eslint --fix "$FILE" 2>/dev/null
    ;;
  *.py)
    python -m black "$FILE" 2>/dev/null
    python -m isort "$FILE" 2>/dev/null
    ;;
  *.go)
    gofmt -w "$FILE" 2>/dev/null
    ;;
  *.rs)
    rustfmt "$FILE" 2>/dev/null
    ;;
  *.json|*.yaml|*.yml)
    npx prettier --write "$FILE" 2>/dev/null
    ;;
esac

echo "✅ Formatted: $FILE"

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "guard-dangerous-commands.sh"
          }
        ]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "guard-protected-files.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# guard-dangerous-commands.sh — 拦截危险的bash命令

# 从stdin读取工具调用输入
INPUT=$(cat)

# 提取命令内容
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 危险命令模式列表
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "git push --force"
  "git reset --hard"
  "DROP TABLE"
  "DROP DATABASE"
  "DELETE FROM.*WHERE 1=1"
  "chmod 777"
  "curl.*|.*sh"
  "> /dev/sda"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qiE "$pattern"; then
    echo "BLOCKED: 检测到危险命令模式: $pattern"
    echo "原始命令: $COMMAND"
    echo "如果确实需要执行，请手动确认。"
    exit 2  # exit code 2 = 阻止执行
  fi
done

# 允许执行
exit 0

#!/bin/bash
# guard-protected-files.sh — 保护关键文件不被修改

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 受保护的文件列表
PROTECTED_FILES=(
  "production.env"
  ".env.production"
  "database/production.sql"
  "terraform/prod.tfvars"
  ".github/workflows/deploy.yml"
)

for protected in "${PROTECTED_FILES[@]}"; do
  if echo "$FILE_PATH" | grep -q "$protected"; then
    echo "BLOCKED: 不允许修改受保护文件: $protected"
    echo "此文件属于生产环境配置，修改需要通过正式流程审批。"
    exit 2
  fi
done

exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "auto-test.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# auto-test.sh — 文件修改后自动运行相关测试

FILE="$CLAUDE_FILE_PATH"

# 只对源码文件触发测试，忽略其他文件
case "$FILE" in
  *.test.*|*.spec.*) 
    # 测试文件本身被修改 → 运行该测试
    TEST_FILE=$(basename "$FILE")
    echo "🧪 运行测试: $TEST_FILE"
    npx vitest run "$FILE" 2>&1 | tail -5
    ;;
  src/**/*.ts|src/**/*.tsx)
    # 源码文件被修改 → 查找对应测试
    BASENAME=$(echo "$FILE" | sed 's/src\///' | sed 's/\.\(ts\|tsx\)$//')
    POSSIBLE_TESTS=(
      "src/${BASENAME}.test.ts"
      "src/${BASENAME}.spec.ts"
      "tests/${BASENAME}.test.ts"
      "__tests__/${BASENAME}.test.ts"
    )

    for test in "${POSSIBLE_TESTS[@]}"; do
      if [ -f "$test" ]; then
        echo "🧪 运行相关测试: $test"
        npx vitest run "$test" 2>&1 | tail -5
        break
      fi
    done
    ;;
esac

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "task-notification.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# task-notification.sh — 多平台任务完成通知

PLATFORM="$(uname)"

if [ "$PLATFORM" = "Darwin" ]; then
  # macOS 通知
  osascript -e 'display notification "Claude Code任务已完成，请查看终端" with title "Claude Code" sound name "Glass"'
elif [ "$PLATFORM" = "Linux" ]; then
  # Linux 通知（需要libnotify）
  notify-send "Claude Code" "任务已完成，请查看终端" --icon=dialog-information 2>/dev/null
fi

# 可选：发送到Slack/Discord webhook
# curl -s -X POST "$WEBHOOK_URL" \
#   -H 'Content-type: application/json' \
#   -d '{"text":"✅ Claude Code任务完成 - '"$(date +%H:%M)"'"}' \
#   > /dev/null 2>&1

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Compact",
        "hooks": [
          {
            "type": "command",
            "command": "inject-project-context.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# inject-project-context.sh — 压缩后注入关键项目信息

cat << 'EOF'
[自动注入的项目上下文 — 压缩后恢复关键信息]

当前活跃Git分支: $(git branch --show-current 2>/dev/null)
最近修改的文件: $(git diff --name-only HEAD~5 2>/dev/null | head -10)
当前测试状态: $(npx vitest run --reporter=verbose 2>&1 | tail -3)

请确保在后续操作中保持对这些文件的一致性。
EOF

cat > ~/.claude/CLAUDE.md << 'EOF'
# 全局偏好

## 语言与风格
- 默认使用中文回复，代码注释用英文
- 回复简洁明了，避免冗长解释

## 编码规范
- TypeScript strict mode
- 优先使用函数式组件和hooks
- 使用 pnpm 作为包管理器
- 提交信息格式：type(scope): description

## 安全
- 不提交 .env 文件和密钥
- 不使用 console.log，使用正式的日志库
- 所有外部输入必须验证
EOF

cat > ./CLAUDE.md << 'EOF'
# 项目：全栈电商平台

## 技术栈
- 前端：React 18 + Vite + TanStack Query
- 后端：Fastify + Prisma + PostgreSQL
- 共享：TypeScript monorepo (pnpm workspace)

## 关键命令
- `pnpm --filter web dev` — 启动前端开发服务器
- `pnpm --filter api dev` — 启动后端开发服务器
- `pnpm -r test` — 运行所有包的测试
- `pnpm -r lint` — 运行lint检查
- `pnpm --filter api db:migrate` — 数据库迁移

## 架构

## 关键约定
- API路由定义在 api/src/routes/ 下，每个资源一个文件
- Prisma schema变更后必须执行 db:migrate
- 前端组件使用 co-location 模式（组件、样式、测试放同一目录）
- 错误处理：前端用ErrorBoundary，后端用Fastify errorHandler
EOF

cat > ./packages/api/CLAUDE.md << 'EOF'
# API模块规则

## 认证
- JWT + Refresh Token双token模式
- 所有受保护路由使用 @fastify/jwt 预处理

## 数据库
- Prisma Client通过依赖注入使用
- 复杂查询优先使用 Prisma 的 include/select
- 禁止原始SQL（除非性能必需并注明原因）

## API设计
- RESTful风格，资源名用复数
- 响应格式统一：{ data, meta?, error? }
- 分页参数：?page=1&limit=20
EOF

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/guard-dangers.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-format.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/notify-done.sh"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(pnpm test*)",
      "Bash(pnpm lint*)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)"
    ]
  }
}

mkdir -p .claude/hooks

# 自动格式化Hook
cat > .claude/hooks/auto-format.sh << 'SCRIPT'
#!/bin/bash
FILE="$CLAUDE_FILE_PATH"
case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx|*.json)
    npx prettier --write "$FILE" 2>/dev/null
    ;;
  *.py)
    python -m black "$FILE" 2>/dev/null
    ;;
esac
SCRIPT
chmod +x .claude/hooks/auto-format.sh

# 安全防护Hook
cat > .claude/hooks/guard-dangers.sh << 'SCRIPT'
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -qiE "rm -rf /|DROP TABLE|git push --force|chmod 777"; then
  echo "BLOCKED: 危险命令已被拦截"
  exit 2
fi
exit 0
SCRIPT
chmod +x .claude/hooks/guard-dangers.sh

# 完成通知Hook
cat > .claude/hooks/notify-done.sh << 'SCRIPT'
#!/bin/bash
PLATFORM="$(uname)"
if [ "$PLATFORM" = "Darwin" ]; then
  osascript -e 'display notification "Claude Code任务完成" with title "✅ Done"' 2>/dev/null
elif [ "$PLATFORM" = "Linux" ]; then
  notify-send "Claude Code" "✅ 任务完成" 2>/dev/null
fi
SCRIPT
chmod +x .claude/hooks/notify-done.sh

# 启动Claude Code并验证配置加载
claude

# 在Claude Code中验证
# 1. CLAUDE.md已加载（Claude会引用你的项目规则）
# 2. Hooks已生效（修改文件后自动格式化）
# 3. 安全Hook工作（尝试执行危险命令会被拦截）

flowchart LR
    subgraph "启动阶段"
        A[加载全局CLAUDE.md] --> B[加载项目CLAUDE.md]
        B --> C[加载子目录CLAUDE.md]
        C --> D[加载settings.json]
        D --> E[注册Hooks]
    end

    subgraph "交互循环"
        E --> F[用户输入]
        F --> G[PreToolUse Hooks]
        G -->|通过| H[工具执行]
        G -->|拦截| I[返回拦截信息]
        H --> J[PostToolUse Hooks]
        J --> K[生成回复]
        K --> L[Stop Hooks]
        L --> F
    end

    subgraph "上下文管理"
        M[/compact 60%时压缩] -.-> F
        N[/plan 大型重构先规划] -.-> F
        O[子目录CLAUDE.md 按需加载] -.-> F
    end

# 保存一条记忆
/remember 项目使用pnpm workspace管理monorepo，根目录的package.json是workspace配置

# 记忆保存在 ~/.claude/projects/<project-hash>/memory/ 目录下
# 每个记忆是一个独立文件，包含frontmatter元数据

flowchart TD
    A["识别重构范围<br/>使用Grep/Glob定位所有相关文件"] --> B["进入Plan模式<br/>/plan 生成修改计划"]
    B --> C["审查计划<br/>确认文件列表和修改逻辑正确"]
    C --> D["执行修改<br/>从底层到顶层（工具→服务→路由→测试）"]
    D --> E["运行测试<br/>每修改2-3个文件后跑一次测试"]
    E --> F{测试通过？}
    F -->|是| G["继续下一组文件"]
    F -->|否| H["立即修复<br/>不要累积错误"]
    H --> E
    G --> I{还有文件？}
    I -->|是| D
    I -->|否| J["全局测试<br/>pnpm -r test"]
    J --> K["代码审查<br/>检查import和类型"]

{
  "permissions": {
    "allow": [
      "Bash(pnpm *)",
      "Bash(npm run *)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git branch*)",
      "Bash(node *)",
      "Bash(npx vitest*)",
      "Bash(npx eslint*)",
      "Bash(npx tsc*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push*)",
      "Bash(DROP *)"
    ]
  }
}

# 1. 检查配置文件路径
ls -la .claude/settings.local.json
# 或全局
ls -la ~/.claude/settings.json

# 2. 验证JSON格式
cat .claude/settings.local.json | python3 -m json.tool

# 3. 检查脚本权限
ls -la .claude/hooks/
# 确保脚本有执行权限：chmod +x .claude/hooks/*.sh

# 4. 检查shebang行
head -1 .claude/hooks/auto-format.sh
# 应该是：#!/bin/bash

# 1. 统计CLAUDE.md行数和大概token数
wc -l CLAUDE.md
# 经验值：1行 ≈ 10-15 token

# 2. 如果超过200行，考虑拆分到子目录
# 根目录CLAUDE.md只保留最关键的50行
# 详细规则移到对应子目录

# 3. 使用@import引用外部文件而非内联

#!/bin/bash
# 读取stdin中的JSON输入
INPUT=$(cat)

# 提取工具名称
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')

# 提取工具输入参数
TOOL_INPUT=$(echo "$INPUT" | jq -r '.tool_input // empty')

# 根据工具类型提取特定字段
case "$TOOL" in
  "Write"|"Edit")
    FILE_PATH=$(echo "$TOOL_INPUT" | jq -r '.file_path // empty')
    ;;
  "Bash")
    COMMAND=$(echo "$TOOL_INPUT" | jq -r '.command // empty')
    ;;
esac