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 任务清单：

探索项目结构

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

分析现有规范

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

识别知识孤岛

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

主控决策点：

确定迁移优先级（配置 → 规则 → 文档）
识别必须保留的领域知识
规划文档层次结构

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

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

SubAgent 任务清单：

创建 CLAUDE.md（索引文件，< 500 行）

Task: Write file CLAUDE.md
内容结构：
## 项目概述 (WHAT)
- 技术栈：[框架] + [语言] + [数据库] + [其他关键依赖]
- 关键目录：src/, tests/, docs/ 等的职责说明

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

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

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

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

迁移现有规则

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

创建规则文档

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

验证任务：

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

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

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

SubAgent 任务清单：

创建 AGENTS.md

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

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

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

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

挖掘隐性知识

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 任务清单：

创建架构文档

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

创建工作流文档

Task: Write
标准化工作流程：
- 添加新功能流程
- Bug 修复流程
- 代码审查流程
- 发布流程

创建故障排除指南

Task: Write
常见问题解决：
- 环境配置问题
- 依赖问题
- 性能问题
- 调试技巧

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

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

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

配置文件精简原则

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

渐进式披露

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

指针优于副本

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

200K Token 足够了

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

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

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

SubAgent 任务清单：

建立 Git Hooks 集成

Task: Write scripts/
创建自动化脚本：
- pre-commit: 检查文档更新
- commit-msg: 验证提交格式
- post-merge: 提醒更新文档

创建改进模板

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

文档更新检查清单

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: 使用渐进式披露：

CLAUDE.md：索引和摘要
rules/：规则详细说明
agent_docs/：深度技术文档

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

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

Q4: 如何防止文档过时？

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

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

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

migration-skill

Migration Skill: Cursor → Claude Code

Overview

何时使用本技能

核心概念映射

迁移流程

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

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

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

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

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

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

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

1. 文档编写原则

2. 规则定义模式

3. 经验沉淀结构

4. 上下文管理策略

主控 Agent 工作模式

角色定义

工作流程

执行原则

验证和测试

每阶段验证清单

整体验证

常见问题

Q1: 配置文件应该多长？

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

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

Q4: 如何防止文档过时？

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

Q6: 迁移需要多长时间？

Resources

可复用的配置模板

参考文档

执行脚本

扩展阅读