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: 如何防止文档过时？

A:

• 使用 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

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