Migration Skill: Cursor → Claude Code

Overview

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

核心原则：

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

何时使用本技能

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

核心概念映射

迁移流程

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

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

SubAgent 任务清单：

1. 探索项目结构

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

2. 分析现有规范

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

3. 识别知识孤岛

   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 引用）
   

验证任务：

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
   

验证任务：

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 集成
• 改进模板完善
• 检查清单建立
• 持续改进可行

整体验证

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

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