<!-- title: Claude Code上下文工程与Hooks深度实战 -->

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

## 概述

本教程面向已掌握Claude Code基础操作的中高级开发者，深入讲解两大核心进阶主题：**上下文工程（Context Engineering）**——通过CLAUDE.md、记忆系统、上下文窗口优化让Claude Code真正"理解"你的项目；以及**Hooks自动化**——通过生命周期钩子实现代码格式化、安全校验、通知推送等确定性自动化。学完后，你将能构建一个"开箱即懂项目、自动执行规范"的Claude Code开发环境。

**适用人群**：已使用Claude Code 1个月以上的开发者，希望从"能用"升级到"高效"。

**前置条件**：
- Claude Code CLI 已安装并配置（`npm install -g @anthropic-ai/claude-code`）
- 至少一个真实项目可供实操
- 基本的JSON配置文件编写能力
- 了解bash脚本基础知识

---

## 第一部分：上下文工程——让Claude Code真正理解你的项目

Andrej Karpathy在2026年将其称为"AI编码的核心技能"：不是提示词工程（prompt engineering），而是**上下文工程（context engineering）**——构建持久的、结构化的上下文，让AI Agent在整个会话中都能做出正确决策。

### 1.1 Claude Code的上下文窗口解剖

Claude Code拥有200K token的上下文窗口。理解这个窗口如何被填充，是一切优化的起点：

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

**关键洞察**：每次对话轮次，Claude Code都会重新处理整个活跃上下文。一个携带了数十个文件内容的会话，每一轮都在"支付"这些token的代价。这意味着：

1. **读取的文件越多，每轮推理越慢、越贵**
2. **CLAUDE.md中每个token都在持续消耗空间**
3. **对话历史会自动增长，需要定期压缩**

### 1.2 CLAUDE.md层级架构实战

CLAUDE.md是上下文工程的基石。Claude Code支持三层CLAUDE.md，按优先级从低到高：

| 层级 | 路径 | 作用范围 | 典型内容 |
|------|------|----------|----------|
| 全局 | `~/.claude/CLAUDE.md` | 所有项目 | 个人偏好、通用编码风格、默认语言 |
| 项目 | `./CLAUDE.md` | 当前项目 | 技术栈、构建命令、项目架构 |
| 子目录 | `./src/CLAUDE.md` | 子目录范围 | 模块特定规则、局部约定 |

#### 1.2.1 全局CLAUDE.md示例

```markdown
# 全局偏好

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

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

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

#### 1.2.2 项目级CLAUDE.md示例

```markdown
# 项目：电商平台后端

## 技术栈
- 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` — 填充测试数据

## 架构概览
```
src/
├── modules/          # 业务模块（每个模块自包含）
│   ├── auth/         # 认证模块
│   ├── orders/       # 订单模块
│   └── products/     # 商品模块
├── shared/           # 共享工具与中间件
├── config/           # 配置管理
└── index.ts          # 入口文件
```

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

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

#### 1.2.3 CLAUDE.md优化原则

根据多个实战案例分析，CLAUDE.md优化有四大核心原则：

**原则一：精简至上——每个token都在持续消耗空间**

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

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

**原则二：只写代码无法自动推断的内容**

代码本身已经说明了"是什么"，CLAUDE.md应该解释"为什么"和"怎么做"：

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

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

**原则三：层级化——不同层级解决不同问题**

不要把所有内容塞进根目录的CLAUDE.md。利用子目录CLAUDE.md实现精准上下文：

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

**原则四：引用而非重复**

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

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

### 1.3 上下文窗口的实战管理策略

#### 1.3.1 /compact 命令——会话压缩

`/compact` 是Claude Code最重要的上下文管理命令。它将当前对话历史压缩为摘要，释放宝贵的token空间。

**最佳实践——在60%时压缩，而非95%**：

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

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

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

**为什么要提前压缩？** 因为在95%时压缩，摘要质量会显著下降——此时模型已经"看不到"早期对话的完整上下文，摘要会丢失关键细节。

#### 1.3.2 /plan 模式——先规划后执行

对于涉及多文件的大型重构，使用 `/plan` 模式将规划和执行分离：

```bash
# 进入规划模式
/plan

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

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

**为什么plan模式能提升多文件编辑的准确率？** 根据开发者社区的实测反馈，分离规划与执行可以将多文件重构的准确率从约60%提升到90%以上。原因是：

1. 规划阶段不消耗文件内容的上下文空间
2. 计划确定后，执行阶段可以更精准地按步骤操作
3. 用户可以在执行前纠正方向偏差

#### 1.3.3 大文件处理策略

直接读取大文件（超过1000行）会快速消耗上下文空间。推荐策略：

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

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

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

#### 1.3.4 上下文优化检查清单

| 场景 | 优化策略 | 预期效果 |
|------|----------|----------|
| CLAUDE.md过长 | 精简到200行以内，移至子目录 | 初始token减少30-50% |
| 频繁读取文件 | 使用offset/limit分块读取 | 每轮节省5000-10000 token |
| 会话超过30分钟 | 在60%时执行/compact | 保持响应质量 |
| 多文件重构 | 先/plan后执行 | 准确率提升30%+ |
| 重复读取同一文件 | 使用@文件引用 | 避免重复加载 |

---

## 第二部分：Hooks自动化——给Claude Code装上"自动驾驶"

Hooks是Claude Code最强大却最被低估的功能。它们是在特定生命周期事件触发时自动执行的shell命令，让你能对AI编码过程施加**确定性控制**。

### 2.1 Hooks生命周期全景

```mermaid
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
```

### 2.2 Hooks配置文件结构

Hooks配置在 `settings.json` 或 `settings.local.json` 中：

```json
{
  "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任务完成' '请查看最新修改'"
          }
        ]
      }
    ]
  }
}
```

**三个关键生命周期事件**：

| 事件 | 触发时机 | 典型用途 | 能否阻止操作 |
|------|----------|----------|-------------|
| `PreToolUse` | 工具执行**之前** | 参数校验、安全拦截、命令过滤 | ✅ 可以 |
| `PostToolUse` | 工具执行**之后** | 自动格式化、日志记录、触发构建 | ❌ 不能 |
| `Stop` | Claude完成回复**之后** | 通知推送、汇总报告、环境清理 | ❌ 不能 |

### 2.3 实战Hook #1：自动代码格式化

最常见的Hook用途——每次文件写入后自动格式化：

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

对应的 `format-on-edit.sh` 脚本：

```bash
#!/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"
```

### 2.4 实战Hook #2：安全拦截——阻止危险操作

防止Claude Code意外执行危险命令或修改关键文件：

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

`guard-dangerous-commands.sh`：

```bash
#!/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
```

`guard-protected-files.sh`：

```bash
#!/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
```

### 2.5 实战Hook #3：自动测试运行

文件修改后自动运行相关测试：

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

`auto-test.sh`：

```bash
#!/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
```

### 2.6 实战Hook #4：任务完成通知

当Claude Code完成一个任务时发送桌面通知（特别适合长时间运行的任务）：

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

`task-notification.sh`：

```bash
#!/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
```

### 2.7 实战Hook #5：上下文注入（Context Injection）

这是最强大的Hook类型之一——在特定事件后注入额外上下文给Claude：

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

`inject-project-context.sh`：

```bash
#!/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
```

**为什么这个Hook特别有价值？** 因为 `/compact` 压缩对话历史时，可能会丢失关键的项目状态信息。通过Hook自动注入，确保压缩后Claude仍然"记得"最重要的上下文。

---

## 第三部分：实战案例——构建完整的Claude Code工程化环境

### 3.1 项目场景

假设你正在开发一个TypeScript全栈项目（前端React + 后端Fastify），需要配置完整的工程化Claude Code环境。

### 3.2 完整配置步骤

#### 步骤1：创建全局CLAUDE.md

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

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

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

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

#### 步骤2：创建项目级CLAUDE.md

```bash
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` — 数据库迁移

## 架构
```
packages/
├── web/      # React前端
├── api/      # Fastify后端
└── shared/   # 共享类型和工具
```

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

#### 步骤3：创建子目录级CLAUDE.md

```bash
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
```

#### 步骤4：配置Hooks

创建 `.claude/settings.local.json`：

```json
{
  "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*)"
    ]
  }
}
```

创建hooks目录和脚本：

```bash
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
```

#### 步骤5：验证配置

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

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

### 3.3 完整工作流程图

```text
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
```

---

## 第四部分：高级技巧与性能优化

### 4.1 记忆系统深度利用

Claude Code的记忆系统（`/remember` 命令）提供了第四层上下文管理：

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

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

**记忆 vs CLAUDE.md 的选择策略**：

| 场景 | 使用CLAUDE.md | 使用记忆 |
|------|-------------|---------|
| 项目架构约定 | ✅ 所有人需要知道 | ❌ |
| 个人偏好 | ❌ | ✅ |
| 调试过程中的临时发现 | ❌ | ✅ |
| 团队统一的编码规范 | ✅ | ❌ |
| 之前会话中的经验教训 | ❌ | ✅ |
| 非显而易见的配置陷阱 | ✅ 放子目录CLAUDE.md | 也可 |

### 4.2 上下文窗口优化的54%削减策略

根据johnlindquist的实战优化方案，通过以下策略可以将初始token消耗减少54%：

1. **CLAUDE.md精简**：从平均300行压缩到120行，去除冗余描述
2. **使用@import按需引用**：不将大文件内容写进CLAUDE.md，而是使用引用路径
3. **子目录CLAUDE.md延迟加载**：只在Claude进入对应目录时才加载
4. **移除重复的工具定义描述**：CLAUDE.md不需要解释Claude Code已有的工具行为

### 4.3 多文件重构的黄金法则

根据多个实战案例总结的多文件重构流程：

```mermaid
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和类型"]
```

**关键原则**：

1. **自底向上修改**：先修改底层模块（types → utils → services → routes），这样上层修改时底层已经就绪
2. **每2-3个文件验证一次**：不要改完所有文件才测试，错误会指数级扩散
3. **在60%上下文时压缩**：多文件重构消耗大量上下文，主动管理比被动压缩效果好得多
4. **使用worktree隔离**：对于特别大的重构，考虑在git worktree中进行，避免污染主分支

### 4.4 权限配置减少交互中断

在 `settings.json` 中配置权限白名单，可以大幅减少Claude Code工作流中的确认中断：

```json
{
  "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 *)"
    ]
  }
}
```

---

## 第五部分：常见问题与排错

### Q1：Hooks不生效？

**排查步骤**：
```bash
# 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
```

### Q2：CLAUDE.md太长导致响应变慢？

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

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

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

### Q3：/compact后Claude"忘记"了重要信息？

这是正常的——压缩会丢失细节。解决方法：

1. **使用PostToolUse Hook注入关键上下文**（见2.7节）
2. **在压缩前手动总结关键状态**：
   ```
   /compact 保留：1) 已修改的文件列表 2) 当前错误信息 3) 未完成步骤
   ```
3. **将持久化信息写入CLAUDE.md或记忆**，而非依赖对话历史

### Q4：Hook脚本中如何获取工具调用的详细信息？

Hooks通过stdin接收JSON格式的工具调用信息：

```bash
#!/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
```

---

## 训练营适用性评估

| 训练营类型 | 适用性 | 预计教学时长 | 建议 |
|-----------|--------|-------------|------|
| AI辅助开发入门营 | ⭐⭐ | 2小时 | 仅讲解CLAUDE.md基础和/compact |
| Claude Code进阶营 | ⭐⭐⭐⭐⭐ | 4-5小时 | 完整教程，含动手实验 |
| 企业工程化训练营 | ⭐⭐⭐⭐ | 3-4小时 | 侧重Hooks安全和团队规范 |
| DevOps自动化营 | ⭐⭐⭐ | 2-3小时 | 侧重Hooks + CI/CD集成 |
| 全栈开发实战营 | ⭐⭐⭐⭐ | 3小时 | 侧重上下文管理 + 多文件重构 |

**动手实验建议**：
- 实验1（30min）：为一个现有项目创建三层CLAUDE.md
- 实验2（45min）：配置3个Hooks（格式化、安全、通知）
- 实验3（30min）：执行一次多文件重构，体验/plan → 执行 → /compact完整流程
- 实验4（15min）：使用上下文窗口探索器观察token消耗

---

## 延伸阅读

- [Claude Code官方文档 - Hooks指南](https://code.claude.com/docs/en/hooks-guide) — Anthropic官方的Hooks完整参考
- [Claude Code上下文窗口探索器](https://code.claude.com/docs/en/context-window) — 交互式模拟上下文窗口填充过程
- [Claude Code Memory & Agent Memory最佳实践](https://orchestrator.dev/blog/2026-04-06--claude-code-agent-memory-2026/) — 记忆系统深度分析
- [Context Engineering 2026](https://tutorials.technology/tutorials/context-engineering-claude-cursor-2026.html) — Karpathy倡导的上下文工程方法论
- [Claude Code Hooks完整指南 20+示例](https://aiorg.dev/blog/claude-code-hooks) — 最全面的Hooks实战合集

## 参考来源

1. [Automate actions with hooks - Claude Code Docs](https://code.claude.com/docs/en/hooks-guide) — Anthropic官方Hooks指南，涵盖PreToolUse/PostToolUse/Stop三个生命周期事件的完整配置参考
2. [Claude Code Hooks: Complete Guide with 20+ Ready-to-Use Examples](https://aiorg.dev/blog/claude-code-hooks) — 20+个可直接复制使用的Hook配置，从代码格式化到安全拦截全覆盖
3. [Mastering Context Management in Claude Code](https://patrickstuart.com/2026/03/10/mastering-context-management-in-claude-code-claudemd-memory-and-beyond) — 上下文管理分层架构分析，CLAUDE.md与记忆系统的最佳实践
4. [Context Engineering 2026: AGENTS.md, CLAUDE.md That Actually Work](https://tutorials.technology/tutorials/context-engineering-claude-cursor-2026.html) — Andrej Karpathy倡导的上下文工程方法论，AI编码核心技能的系统化阐述
5. [Claude Code & Agent Memory: Best Practices for 2026](https://orchestrator.dev/blog/2026-04-06--claude-code-agent-memory-2026/) — 记忆系统分层架构深度解析，含持久化上下文的工程实践

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)