cursor-to-claude-code skill

---
name: migration-skill
description: 从 Cursor 开发模式迁移到 Claude Code 开发模式的完整指南。当项目需要从 Cursor AI IDE 切换到 Claude Code CLI 时使用此技能，包括配置迁移、文档结构转换、工作流适配等。
---

# Migration Skill: Cursor → Claude Code

## Overview

将使用 Cursor 开发的项目平滑迁移到 Claude Code 开发模式，提取标杆项目的最佳实践，建立高度抽象的、脱离语言和框架的开发规范体系。本技能采用主控 Agent + SubAgent 的协作模式，确保迁移过程的系统性和可验证性。

**核心原则**：
- **抽象优先**：提取通用的工程实践，而非具体技术栈的规范
- **渐进式迁移**：分阶段迁移，每步都可验证
- **Compounding Engineering**：让每次改进都成为系统永久知识
- **主控模式**：主控 Agent 思考方案，SubAgent 执行细节，独立 Task 验证结果

## 何时使用本技能

- 从 Cursor IDE 迁移到 Claude Code CLI
- 建立 AI Agent 友好的项目配置体系
- 优化现有项目的上下文工程实践
- 为老项目补充 AI 开发规范文档
- 建立项目知识库和经验沉淀机制

## 核心概念映射

| Cursor 模式 | Claude Code 模式 | 说明 |
|------------|-----------------|------|
| `.cursorrules` | `CLAUDE.md` | Agent 配置文件 |
| `.cursor/` | `.claude/` | 配置目录 |
| 内联规则 | 渐进式披露 | 配置文件指向详细文档 |
| 单一规则文件 | 层次化文档体系 | 配置 + 规则 + 文档 |
| 隐式知识 | 显式知识库 | AGENTS.md 经验沉淀 |

## 迁移流程

### Phase 1: 现状分析 (主控 Agent)

**目标**：理解当前项目状态，识别迁移范围和优先级

**SubAgent 任务清单**：

1. **探索项目结构**
   ```bash
   Task: Explore subagent_type=Explore
   探索当前项目：
   - 技术栈和框架类型
   - 目录结构和模块划分
   - 现有的配置文件（.cursorrules, .cursor/ 等）
   - 文档体系完整性
   返回：项目结构报告和现有配置清单
   ```

2. **分析现有规范**
   ```bash
   Task: Explore subagent_type=Explore
   分析现有开发规范：
   - 代码风格规则
   - 架构模式和约定
   - 测试策略
   - Git 工作流
   返回：现有规范摘要和改进建议
   ```

3. **识别知识孤岛**
   ```bash
   Task: Grep pattern="TODO|FIXME|HACK|NOTE"
   搜索代码中的隐性知识：
   - 注释中的临时方案
   - 需要文档化的陷阱
   - 团队约定（命名、模式等）
   返回：隐性知识清单和分类
   ```

**主控决策点**：
- 确定迁移优先级（配置 → 规则 → 文档）
- 识别必须保留的领域知识
- 规划文档层次结构

---

### Phase 2: 配置文件迁移 (主控 Agent + SubAgent)

**目标**：建立 AI Agent 配置文件体系（WHAT/WHY/HOW）

**SubAgent 任务清单**：

1. **创建 CLAUDE.md**（索引文件，< 500 行）
   ```
   Task: Write file CLAUDE.md
   内容结构：
   ## 项目概述 (WHAT)
   - 技术栈：[框架] + [语言] + [数据库] + [其他关键依赖]
   - 关键目录：src/, tests/, docs/ 等的职责说明

   ## 核心架构决策 (WHY)
   - 为什么选择这个架构？
   - 哪些是历史债务？
   - 哪些设计决策需要 Agent 遵守？

   ## 开发工作流 (HOW)
   - 如何运行项目？
   - 如何测试？
   - 如何验证改动？

   ## 核心约束 (5-10 条)
   - 最关键的规则（带 CRITICAL 标记）
   - 每条规则指向详细文档

   ## 详细文档索引
   - 按主题分类的文档链接
   ```

2. **迁移现有规则**
   ```
   Task: Edit/Migrate
   将 .cursorrules 内容迁移到：
   - CLAUDE.md（简述）
   - rules/（详细文档）
   - agent_docs/（技术文档）
   遵循渐进式披露原则
   ```

3. **创建规则文档**
   ```
   Task: Write files in rules/
   为每条核心规则创建独立文档：
   - 规则名称.md
   - 问题描述和重要性
   - 正反例对比
   - 常见错误
   - 参考代码（使用 file:line 引用）
   ```

**验证任务**：
```bash
Task: General-purpose
验证配置迁移质量：
- CLAUDE.md 行数 < 500
- 所有规则都有详细文档
- 文档间引用正确
- 运行时无配置错误
```

---

### Phase 3: 经验沉淀系统 (主控 Agent + SubAgent)

**目标**：建立 AGENTS.md，实现 Compounding Engineering

**SubAgent 任务清单**：

1. **创建 AGENTS.md**
   ```
   Task: Write file AGENTS.md
   内容结构：
   ## 代码风格
   - 命名约定
   - 导入顺序
   - 语言特性偏好

   ## 已知陷阱
   - 常见错误模式
   - 必须避免的做法
   - 框架特定陷阱

   ## 成功模式
   - 标准工作流
   - 可复用模板
   - 最佳实践示例

   ## 复利效应实践
   - Bug 修复后的改进清单
   - 代码审查后的规范更新
   ```

2. **挖掘隐性知识**
   ```
   Task: Grep + Read
   从代码历史和注释中提取：
   - Git commit 历史中的修复记录
   - 代码审查中的常见问题
   - 注释中的"为什么"
   - 团队约定和模式
   分类整理到 AGENTS.md
   ```

**验证任务**：
```bash
Task: General-purpose
验证经验沉淀质量：
- AGENTS.md 覆盖主要陷阱
- 每个陷阱有具体代码示例
- 成功模式可操作
- 复利效应清单完整
```

---

### Phase 4: 文档体系完善 (主控 Agent + SubAgent)

**目标**：建立层次化、渐进式披露的文档体系

**文档结构**：
```
agent_docs/
├── architecture/          # 架构文档
│   ├── overview.md        # 系统架构概览
│   ├── modules.md         # 模块划分和职责
│   └── decisions.md       # 架构决策记录 (ADR)
├── workflows/             # 工作流程
│   ├── development.md     # 开发流程
│   ├── testing.md         # 测试流程
│   └── deployment.md      # 部署流程
├── troubleshooting.md     # 故障排除
└── api/                   # API 文档（如需要）
    └── README.md

rules/
├── rule-1.md              # 核心规则详细说明
├── rule-2.md
└── ...
```

**SubAgent 任务清单**：

1. **创建架构文档**
   ```
   Task: Write + Explore
   生成架构文档：
   - 系统层次结构
   - 模块依赖关系
   - 数据流图
   - 技术选型理由
   ```

2. **创建工作流文档**
   ```
   Task: Write
   标准化工作流程：
   - 添加新功能流程
   - Bug 修复流程
   - 代码审查流程
   - 发布流程
   ```

3. **创建故障排除指南**
   ```
   Task: Write
   常见问题解决：
   - 环境配置问题
   - 依赖问题
   - 性能问题
   - 调试技巧
   ```

---

### Phase 5: 上下文工程优化 (主控 Agent + SubAgent)

**目标**：应用最佳实践，优化上下文管理

**核心原则**（来自上下文工程最佳实践）：

1. **配置文件精简原则**
   ```
   Task: Edit CLAUDE.md
   确保配置文件：
   - 行数 < 500（越短越好）
   - 只包含普遍适用的内容
   - 详细内容指向独立文档
   - 避免代码风格指南（交给 linter）
   ```

2. **渐进式披露**
   ```
   Task: Reorganize docs/
   实现三级加载：
   1. CLAUDE.md（元数据，自动加载）
   2. rules/（规则详细说明，按需加载）
   3. agent_docs/（技术文档，深度查阅）
   ```

3. **指针优于副本**
   ```
   Task: Edit all .md files
   统一使用 file:line 引用：
   - 不复制代码片段
   - 使用 "详见 src/module/file.ts:123"
   - 保持文档与代码同步
   ```

4. **200K Token 足够了**
   ```
   主控 Agent 策略：
   - 单对话 < 100K token 时继续
   - 完成子任务后开新对话
   - Agent 出现"醉酒"症状时重置
   - 把"开新对话"视为正常工作流
   ```

---

### Phase 6: 复利工程机制 (主控 Agent + SubAgent)

**目标**：建立持续改进的知识系统

**SubAgent 任务清单**：

1. **建立 Git Hooks 集成**
   ```
   Task: Write scripts/
   创建自动化脚本：
   - pre-commit: 检查文档更新
   - commit-msg: 验证提交格式
   - post-merge: 提醒更新文档
   ```

2. **创建改进模板**
   ```
   Task: Write templates/
   标准化改进流程：
   - Bug 修复报告模板
   - 代码审查反馈模板
   - 新规范提案模板
   ```

3. **文档更新检查清单**
   ```
   Task: Write CHECKLIST.md
   每次改动后检查：
   - [ ] 是否发现新陷阱？
   - [ ] 是否总结新模式？
   - [ ] 是否需要更新规范？
   - [ ] 是否添加测试防止回归？
   ```

---

## 通用最佳实践（脱离技术栈）

### 1. 文档编写原则

**WHAT（是什么）**：
- 技术栈和工具
- 目录结构和职责
- 核心概念和术语

**WHY（为什么）**：
- 架构决策背景
- 历史债务说明
- 设计权衡考量

**HOW（怎么做）**：
- 运行和测试命令
- 开发工作流程
- 问题排查方法

### 2. 规则定义模式

每条规则包含：
```
## 规则 N: [规则名称] [优先级]

**问题描述**：
为什么需要这条规则？

**正确做法** (✅)：
[代码示例]

**错误做法** (❌)：
[代码示例]

**常见错误**：
- [错误1]
- [错误2]

**参考文档**：
- 详细说明：rules/rule-name.md
- 示例代码：src/module/file.ts:123
```

### 3. 经验沉淀结构

```
## 代码风格
- 语言特性偏好
- 命名和格式约定

## 已知陷阱
- 框架特定陷阱
- 常见错误模式
- 必须避免的做法

## 成功模式
- 标准工作流
- 可复用模板
- 最佳实践示例

## 复利效应
- Bug 修复 → 规范更新
- 代码审查 → 模式提取
- 经验 → 永久知识
```

### 4. 上下文管理策略

**配置文件（CLAUDE.md）**：
- 索引性质，< 500 行
- 只包含普遍适用的约束
- 详细内容指向文档
- 避免：代码风格、过度规范

**规则文档（rules/）**：
- 每条规则独立文档
- 正反例对比
- 常见错误和解决方案
- 指向代码实现

**技术文档（agent_docs/）**：
- 架构和设计文档
- 工作流程指南
- 故障排除手册
- API 参考手册

---

## 主控 Agent 工作模式

### 角色定义

**主控 Agent（你）**：
- 思考需求和落地方案
- 拆分任务并指挥 SubAgent
- 不执行细节操作
- 开启独立 Task 验证结果

**SubAgent（Task 工具）**：
- 执行具体操作
- 搜集信息和分析
- 按指令完成任务
- 返回结果报告

**验证 Task（独立 General-purpose Agent）**：
- 检查实现质量
- 发现异常并更正
- 确保符合规范
- 提供改进建议

### 工作流程

```
1. 主控 Agent 思考需求
   ↓
2. 拆分为 SubAgent 任务
   ↓
3. 并行执行多个 Task
   ↓
4. 汇总结果并分析
   ↓
5. 开启验证 Task 检查
   ↓
6. 根据反馈调整
   ↓
7. 继续下一阶段
```

### 执行原则

**主控 Agent**：
- ✅ 思考"为什么"和"怎么做"
- ✅ 规划迁移路径
- ✅ 识别风险和依赖
- ✅ 评估优先级
- ❌ 不直接编辑文件
- ❌ 不执行细节任务
- ❌ 不运行命令

**SubAgent**：
- ✅ 执行具体操作
- ✅ 搜集和分析信息
- ✅ 按指令完成任务
- ❌ 不做决策
- ❌ 不改变计划

**验证 Task**：
- ✅ 独立验证结果
- ✅ 发现潜在问题
- ✅ 提供改进建议
- ✅ 确保质量标准

---

## 验证和测试

### 每阶段验证清单

**Phase 1: 现状分析**
- [ ] 项目结构完整映射
- [ ] 现有配置全部识别
- [ ] 隐性知识充分挖掘
- [ ] 优先级合理规划

**Phase 2: 配置迁移**
- [ ] CLAUDE.md 完整且 < 500 行
- [ ] 所有规则有详细文档
- [ ] 渐进式披露实现
- [ ] 配置文件无错误

**Phase 3: 经验沉淀**
- [ ] AGENTS.md 覆盖主要陷阱
- [ ] 成功模式可操作
- [ ] 复利效应机制建立
- [ ] 经验可复用

**Phase 4: 文档体系**
- [ ] 文档层次清晰
- [ ] 引用关系正确
- [ ] 内容完整准确
- [ ] 易于查找和更新

**Phase 5: 上下文优化**
- [ ] 配置精简
- [ ] 文档渐进披露
- [ ] 使用指针引用
- [ ] 上下文高效

**Phase 6: 复利机制**
- [ ] Git Hooks 集成
- [ ] 改进模板完善
- [ ] 检查清单建立
- [ ] 持续改进可行

### 整体验证

```bash
Task: General-purpose
最终验证：
1. 文档结构完整性
   - CLAUDE.md, AGENTS.md 存在
   - rules/ 和 agent_docs/ 组织合理
   - 所有引用可访问

2. 内容质量检查
   - 规则有正反例
   - 陷阱有具体代码
   - 工作流可操作

3. 实用性验证
   - 新开发者能快速上手
   - Agent 能理解规范
   - 知识可复用

4. 复利效应验证
   - Bug 修复流程包含文档更新
   - 代码审查包含规范提取
   - 经验有沉淀机制
```

---

## 常见问题

### Q1: 配置文件应该多长？

**A**: CLAUDE.md 应控制在 500 行以内，越短越好。只保留普遍适用的内容，详细说明放在 rules/ 和 agent_docs/。

### Q2: 如何平衡详细和简洁？

**A**: 使用渐进式披露：
1. CLAUDE.md：索引和摘要
2. rules/：规则详细说明
3. agent_docs/：深度技术文档

### Q3: 是否需要代码风格指南？

**A**: 不建议。交给 linter 和 formatter（ESLint, Prettier, Biome）。LLM 做格式检查既慢又贵，而且会降低对其他指令的遵循能力。

### Q4: 如何防止文档过时？

**A**:
1. 使用 file:line 引用而非代码副本
2. 建立 Git Hooks 提醒更新
3. 代码审查时检查文档一致性
4. 定期运行验证脚本

### Q5: 如何处理技术栈特定内容？

**A**: 保持抽象原则，提取通用实践：
- ❌ "如何使用 Prisma"
- ✅ "ORM 使用规范：单例模式、事务边界、连接管理"

### Q6: 迁移需要多长时间？

**A**: 分阶段进行：
- Phase 1-2（配置迁移）：2-4 小时
- Phase 3-4（文档完善）：1-2 天
- Phase 5-6（优化机制）：持续进行

建议先完成 Phase 1-2，让 Agent 开始工作，再逐步完善。

---

## Resources

### 可复用的配置模板

**assets/** 目录包含：
- `CLAUDE.md.template` - 配置文件模板
- `AGENTS.md.template` - 经验沉淀模板
- `rules/` - 规则文档模板
- `agent_docs/` - 技术文档模板

### 参考文档

**references/** 目录包含：
- `context-engineering-best-practices.md` - 上下文工程最佳实践
- `compounding-engineering.md` - 复利工程指南
- `documentation-structure.md` - 文档结构规范

### 执行脚本

**scripts/** 目录包含：
- `analyze_project.py` - 项目分析脚本
- `validate_migration.py` - 迁移验证脚本
- `check_docs_consistency.py` - 文档一致性检查

---

## 扩展阅读

- 上下文工程最佳实践（用户提供的摘选）
- Compounding Engineering（复利工程）
- 第一性原理拆解 Agentic Coding
-标杆项目 CLAUDE.md 和 AGENTS.md

---

**版本**: v1.0
**最后更新**: 2026-01-29
**维护者**: Migration Team

**贡献指南**: 本技能旨在通用化，贡献时请保持脱离技术栈的抽象性。