586 Migration Guide 0c27fc15

# 从 v4.2 迁移到 v5.0 - Context Engineering

> **重要**: 这是一个重大升级，引入了全新的 Context Engineering 架构

---

## 🎯 为什么要迁移？

### Before (v4.2)
```
CLAUDE.md: 20KB（包含大量详细内容）
+ 规则文件: 30KB（全局+项目重复）
+ 能力文档: 70KB（部分加载）
= 总计: 120KB (60% context 占用)
```

**问题**:
- ❌ 大量不相关内容被加载
- ❌ 上下文腐烂
- ❌ 重复的规则文件
- ❌ 没有智能加载机制

### After (v5.0)
```
CLAUDE.md: 5KB（纯索引 + 核心原则）
+ 核心规则: 10KB（总是加载）
+ 按需加载: 20-30KB（根据任务类型）
= 总计: 35-45KB (18-23% context 占用)
```

**改进**:
- ✅ 智能按需加载
- ✅ Context 节省 ~75KB
- ✅ Free context 从 40% → 77%+
- ✅ 清晰的 Subagent 架构
- ✅ Progressive Disclosure

---

## 📋 迁移步骤

### Step 1: 备份现有配置

```bash
# 备份当前的 CLAUDE.md
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE_v4.2_backup.md

# 备份规则文件
cp -r ~/.claude/rules ~/.claude/rules_v4.2_backup
```

### Step 2: 替换主索引文件

```bash
# 使用新的 CLAUDE.md
mv ~/.claude/CLAUDE_v5.md ~/.claude/CLAUDE.md
```

### Step 3: 重组规则文件（如果还没做）

```bash
# 移动现有规则到 domain 目录
mv ~/.claude/rules/coding-style.md ~/.claude/rules/domain/coding.md
mv ~/.claude/rules/testing.md ~/.claude/rules/domain/testing.md
mv ~/.claude/rules/security.md ~/.claude/rules/domain/security.md
mv ~/.claude/rules/git-workflow.md ~/.claude/rules/domain/git.md
```

### Step 4: 清理重复文件

```bash
# 删除项目级的重复规则（如果有）
# 现在统一使用全局规则，按需加载
rm -rf "E:\Bobo's Coding cache\.claude\rules"
```

### Step 5: 验证新架构

```bash
# 检查核心文件是否存在
ls ~/.claude/CLAUDE.md
ls ~/.claude/CONTEXT_MANAGER.md
ls ~/.claude/index/task-router.md
ls ~/.claude/rules/core/work-mode.md
ls ~/.claude/rules/core/blocking-rules.md
```

---

## 🆕 新增文件说明

### 核心系统文件

| 文件 | 用途 | 大小 |
|------|------|------|
| `CLAUDE.md` | 主索引 + 核心原则 | 5KB |
| `CONTEXT_MANAGER.md` | 智能加载规则 | 10KB |
| `CONTEXT_ENGINEERING_PLAN.md` | 完整设计方案 | 15KB |
| `MIGRATION_GUIDE.md` | 迁移指南（本文件） | 8KB |

### 索引文件

| 文件 | 用途 | 大小 |
|------|------|------|
| `index/task-router.md` | 任务路由决策树 | 8KB |
| `index/capabilities-index.md` | 能力索引（待创建） | 3KB |
| `index/tools-index.md` | 工具索引（待创建） | 3KB |
| `index/error-patterns-index.md` | 错误索引（待创建） | 3KB |

### 核心规则

| 文件 | 用途 | 大小 |
|------|------|------|
| `rules/core/work-mode.md` | 4步工作模式 | 5KB |
| `rules/core/blocking-rules.md` | 4种致命阻塞 | 5KB |

### 领域规则（按需加载）

| 文件 | 用途 | 大小 |
|------|------|------|
| `rules/domain/coding.md` | 编码风格规则 | 5KB |
| `rules/domain/testing.md` | 测试要求 | 5KB |
| `rules/domain/security.md` | 安全规则 | 5KB |
| `rules/domain/git.md` | Git 工作流 | 5KB |

### Subagent 定义

| 文件 | 用途 | 大小 |
|------|------|------|
| `agents/SUBAGENT_ARCHITECTURE.md` | 架构说明 | 12KB |
| `agents/context-manager-agent.md` | Context Manager（待创建） | 3KB |
| `agents/task-router-agent.md` | Task Router（待创建） | 3KB |

### 错误库

| 文件 | 用途 | 大小 |
|------|------|------|
| `errors/top-5-errors.md` | 高频错误快速参考 | 6KB |
| `errors/ERROR_CATALOG.md` | 完整错误目录 | 30KB |

---

## 🔄 使用变化

### Before (v4.2)

**启动时**:
- 加载 CLAUDE.md (20KB)
- 加载所有规则文件 (30KB)
- 部分能力文档自动加载 (70KB)

**总是使用 120KB context**

### After (v5.0)

**启动时**:
- 加载 CLAUDE.md (5KB)
- 加载核心规则 (10KB)

**任务识别后**:
- 自动加载相关文档 (15-30KB)

**总共使用 30-45KB context**

---

## 📖 新的工作流程

### 1. 用户提出请求

```
"帮我做一个浏览器自动化脚本"
```

### 2. 系统自动识别任务类型

```
识别: browser-automation
```

### 3. Context Manager 自动加载文档

```
加载:
  - CLAUDE.md (5KB)
  - rules/core/work-mode.md (5KB)
  - rules/core/blocking-rules.md (5KB)
  - rules/domain/coding.md (5KB)
  - capabilities/browser-automation/decision-tree.md (8KB)

总计: 28KB
```

### 4. Task Router 选择 Agent

```
选择: Browser Automation Agent
工具: playwright (MCP)
```

### 5. 执行任务

```
Agent 使用加载的文档执行任务
```

### 6. 返回结果

```
完成，context 使用: 28KB (14%)
Free context: 172KB (86%)
```

---

## ✅ 验证迁移成功

### 测试案例 1: 浏览器自动化

```
用户: "用 Playwright 打开 Google 并搜索"

预期:
  ✓ 自动识别 browser-automation
  ✓ 加载 decision-tree.md
  ✓ Context 使用 <30KB
  ✓ 成功执行任务
```

### 测试案例 2: 视频创作

```
用户: "做一个30秒的产品介绍视频"

预期:
  ✓ 自动识别 video-creation
  ✓ 加载 remotion-guide.md
  ✓ Context 使用 <40KB
  ✓ 输出完整 Remotion 项目
```

### 测试案例 3: 数据分析

```
用户: "查询最近7天的用户增长数据"

预期:
  ✓ 自动识别 data-analysis
  ✓ 加载 data-analysis-guide.md
  ✓ Context 使用 <35KB
  ✓ 生成优化的 SQL 查询
```

---

## 🆚 功能对比

| 功能 | v4.2 | v5.0 |
|------|------|------|
| **主索引大小** | 20KB | 5KB ✅ |
| **Context 使用** | 120KB (60%) | 35-45KB (18-23%) ✅ |
| **智能加载** | ❌ | ✅ |
| **Subagent 架构** | ❌ | ✅ |
| **Progressive Disclosure** | ❌ | ✅ |
| **按需加载** | ❌ | ✅ |
| **任务路由** | ❌ | ✅ |
| **Context 优化** | ❌ | ✅ |

---

## 🎓 学习新系统

### 快速上手（5分钟）

1. **阅读 CLAUDE.md** (5KB)
   - 核心原则
   - 快速索引

2. **浏览 index/task-router.md** (8KB)
   - 找到你需要的能力
   - 30秒快速导航

3. **开始工作**
   - 系统会自动加载必需文档
   - 无需手动管理 context

### 深入理解（30分钟）

1. **Context Engineering**
   - `CONTEXT_MANAGER.md` - 加载规则
   - `CONTEXT_ENGINEERING_PLAN.md` - 完整设计

2. **Subagent 架构**
   - `agents/SUBAGENT_ARCHITECTURE.md` - 架构说明
   - 理解 agent 协作流程

3. **实践测试**
   - 尝试不同类型的任务
   - 观察 context 使用情况

---

## ❓ 常见问题

### Q1: 我的旧文档还能用吗？

✅ **能用**。所有现有能力文档（capabilities/）都保持不变，只是加载方式改为按需加载。

### Q2: 需要手动指定加载哪些文档吗？

❌ **不需要**。系统会根据你的请求自动识别任务类型并加载相关文档。

### Q3: 如果自动识别错误怎么办？

可以手动指定：
```
@load capabilities/browser-automation/decision-tree.md
```

### Q4: v4.2 的功能会丢失吗？

❌ **不会**。所有功能都保留，只是组织方式更优化了。

### Q5: 迁移会影响正在进行的项目吗？

❌ **不会**。这是本地配置优化，不影响项目代码。

---

## 🔧 故障排除

### 问题 1: "找不到 CLAUDE.md"

```bash
# 确认文件存在
ls ~/.claude/CLAUDE.md

# 如果不存在，重新创建
cp ~/.claude/CLAUDE_v5.md ~/.claude/CLAUDE.md
```

### 问题 2: "某个能力文档加载失败"

```bash
# 检查文件是否存在
ls ~/.claude/capabilities/browser-automation/decision-tree.md

# 如果不存在，可能路径错误，检查 CONTEXT_MANAGER.md 中的映射
```

### 问题 3: "Context 使用仍然很高"

```bash
# 检查是否有未清理的旧规则
ls ~/.claude/rules/

# 应该只有 core/ 和 domain/ 两个目录
# 如果有其他文件，可能是旧版本残留
```

---

## 📊 性能提升

### Context 使用对比

```
任务: 浏览器自动化

v4.2:
  CLAUDE.md: 20KB
  + rules: 30KB
  + capabilities: 70KB
  = 120KB (60%)

v5.0:
  CLAUDE.md: 5KB
  + core rules: 10KB
  + browser-automation: 8KB
  = 23KB (12%)

节省: 97KB (48% → 12%)
```

### 响应速度提升

```
v4.2: 加载 120KB → 分析 → 响应
v5.0: 加载 23KB → 分析 → 响应

加载时间减少: ~80%
```

---

## 🎯 下一步

迁移完成后：

1. **测试各种任务类型**
   - 浏览器自动化
   - 视频创作
   - 数据分析
   - UI 设计

2. **监控 Context 使用**
   - 观察加载了哪些文档
   - 是否符合预期

3. **提供反馈**
   - 识别不准确的情况
   - 建议改进

4. **享受更高效的工作流程**
   - 更少的 context 占用
   - 更快的响应速度
   - 更清晰的组织结构

---

## 📚 相关文档

- `CLAUDE.md` - 主索引（新版）
- `CONTEXT_MANAGER.md` - Context 加载规则
- `CONTEXT_ENGINEERING_PLAN.md` - 完整设计方案
- `agents/SUBAGENT_ARCHITECTURE.md` - Subagent 架构
- `index/task-router.md` - 任务路由决策树

---

**版本**: v1.0
**迁移**: v4.2 → v5.0
**更新**: 2026-02-05
**状态**: Ready for Production