Migration Skill: Cursor → Claude Code

Overview

Smoothly migrate projects developed with Cursor to Claude Code development mode, extract best practices from benchmark projects, and establish a highly abstract development specification system independent of languages and frameworks. This skill adopts a collaborative mode of Main Agent + SubAgent to ensure the systematicness and verifiability of the migration process.

Core Principles:

Abstraction First: Extract general engineering practices rather than specifications for specific tech stacks
Progressive Migration: Migrate in phases with verifiable results at each step
Compounding Engineering: Make every improvement a permanent part of the system's knowledge
Main Agent Mode: Main Agent designs solutions, SubAgents execute details, and independent Tasks verify results

When to Use This Skill

Migrate from Cursor IDE to Claude Code CLI
Establish an AI Agent-friendly project configuration system
Optimize context engineering practices for existing projects
Supplement AI development specification documents for legacy projects
Build a project knowledge base and experience accumulation mechanism

Core Concept Mapping

Cursor Mode	Claude Code Mode	Description
`.cursorrules`	`CLAUDE.md`	Agent configuration file
`.cursor/`	`.claude/`	Configuration directory
Inline Rules	Progressive Disclosure	Configuration files point to detailed documents
Single Rule File	Hierarchical Document System	Configuration + Rules + Documentation
Implicit Knowledge	Explicit Knowledge Base	Experience accumulation in AGENTS.md

Migration Process

Phase 1: Current State Analysis (Main Agent)

Objective: Understand the current project status, identify migration scope and priorities

SubAgent Task List:

Explore Project Structure

bash

Task: Explore subagent_type=Explore
Explore the current project:
- Tech stack and framework types
- Directory structure and module division
- Existing configuration files (.cursorrules, .cursor/, etc.)
- Completeness of documentation system
Return: Project structure report and existing configuration list

Analyze Existing Specifications

bash

Task: Explore subagent_type=Explore
Analyze existing development specifications:
- Code style rules
- Architecture patterns and conventions
- Testing strategies
- Git workflows
Return: Summary of existing specifications and improvement suggestions

Identify Knowledge Silos

bash

Task: Grep pattern="TODO|FIXME|HACK|NOTE"
Extract implicit knowledge from code:
- Temporary solutions in comments
- Pitfalls requiring documentation
- Team conventions (naming, patterns, etc.)
Return: Implicit knowledge list and classification

Main Agent Decision Points:

Determine migration priorities (Configuration → Rules → Documentation)
Identify domain knowledge that must be retained
Plan document hierarchy

Phase 2: Configuration File Migration (Main Agent + SubAgent)

Objective: Establish an AI Agent configuration file system (WHAT/WHY/HOW)

SubAgent Task List:

Create CLAUDE.md (Index file, < 500 lines)

Task: Write file CLAUDE.md
Content structure:
## Project Overview (WHAT)
- Tech stack: [Framework] + [Language] + [Database] + [Other key dependencies]
- Key directories: Responsibilities of src/, tests/, docs/, etc.

## Core Architecture Decisions (WHY)
- Why was this architecture chosen?
- What are the technical debts?
- Which design decisions must Agents follow?

## Development Workflow (HOW)
- How to run the project?
- How to test?
- How to verify changes?

## Core Constraints (5-10 items)
- Most critical rules (marked with CRITICAL)
- Each rule links to detailed documentation

## Detailed Document Index
- Themed document links

Migrate Existing Rules

Task: Edit/Migrate
Migrate .cursorrules content to:
- CLAUDE.md (brief description)
- rules/ (detailed documentation)
- agent_docs/ (technical documentation)
Follow the principle of progressive disclosure

Create Rule Documents

Task: Write files in rules/
Create independent documents for each core rule:
- rule-name.md
- Problem description and importance
- Comparison of correct and incorrect examples
- Common mistakes
- Reference code (using file:line references)

Verification Task:

bash

Task: General-purpose
Verify configuration migration quality:
- CLAUDE.md has < 500 lines
- All rules have detailed documentation
- Cross-document references are correct
- No configuration errors during runtime

Phase 3: Experience Accumulation System (Main Agent + SubAgent)

Objective: Establish AGENTS.md to implement Compounding Engineering

SubAgent Task List:

Create AGENTS.md

Task: Write file AGENTS.md
Content structure:
## Code Style
- Naming conventions
- Import order
- Language feature preferences

## Known Pitfalls
- Common error patterns
- Practices to avoid
- Framework-specific pitfalls

## Success Patterns
- Standard workflows
- Reusable templates
- Best practice examples

## Compounding Engineering Practices
- Improvement checklist after bug fixes
- Specification updates after code reviews

Mine Implicit Knowledge

Task: Grep + Read
Extract from code history and comments:
- Fix records in Git commit history
- Common issues in code reviews
- "Why" explanations in comments
- Team conventions and patterns
Classify and organize into AGENTS.md

Verification Task:

bash

Task: General-purpose
Verify experience accumulation quality:
- AGENTS.md covers major pitfalls
- Each pitfall has specific code examples
- Success patterns are actionable
- Compounding engineering checklist is complete

Phase 4: Documentation System Improvement (Main Agent + SubAgent)

Objective: Build a hierarchical, progressive disclosure documentation system

Document Structure:

agent_docs/
├── architecture/          # Architecture documentation
│   ├── overview.md        # System architecture overview
│   ├── modules.md         # Module division and responsibilities
│   └── decisions.md       # Architecture decision records (ADR)
├── workflows/             # Workflows
│   ├── development.md     # Development process
│   ├── testing.md         # Testing process
│   └── deployment.md      # Deployment process
├── troubleshooting.md     # Troubleshooting guide
└── api/                   # API documentation (if needed)
    └── README.md

rules/
├── rule-1.md              # Detailed explanation of core rules
├── rule-2.md
└── ...

SubAgent Task List:

Create Architecture Documentation

Task: Write + Explore
Generate architecture documentation:
- System hierarchy
- Module dependencies
- Data flow diagrams
- Reasons for technology selection

Create Workflow Documentation

Task: Write
Standardize workflows:
- New feature addition process
- Bug fix process
- Code review process
- Release process

Create Troubleshooting Guide

Task: Write
Resolve common issues:
- Environment configuration problems
- Dependency issues
- Performance issues
- Debugging techniques

Phase 5: Context Engineering Optimization (Main Agent + SubAgent)

Objective: Apply best practices to optimize context management

Core Principles (from Context Engineering Best Practices):

Configuration File Simplification Principle

Task: Edit CLAUDE.md
Ensure configuration files:
- Have < 500 lines (the shorter the better)
- Only contain universally applicable content
- Detailed content links to independent documents
- Avoid code style guidelines (leave to linters)

Progressive Disclosure

Task: Reorganize docs/
Implement three-level loading:
1. CLAUDE.md (metadata, automatically loaded)
2. rules/ (detailed rule explanations, loaded on demand)
3. agent_docs/ (technical documentation, for in-depth reference)

Pointers Over Copies

Task: Edit all .md files
Uniformly use file:line references:
- Do not copy code snippets
- Use "See src/module/file.ts:123"
- Keep documentation synchronized with code

200K Tokens Are Sufficient

Main Agent Strategy:
- Continue when single conversation < 100K tokens
- Start new conversations after completing subtasks
- Reset when Agent shows "drunk" symptoms
- Treat "starting new conversations" as normal workflow

Phase 6: Compounding Engineering Mechanism (Main Agent + SubAgent)

Objective: Build a continuous improvement knowledge system

SubAgent Task List:

Establish Git Hooks Integration

Task: Write scripts/
Create automation scripts:
- pre-commit: Check document updates
- commit-msg: Verify commit message format
- post-merge: Remind to update documents

Create Improvement Templates

Task: Write templates/
Standardize improvement processes:
- Bug fix report template
- Code review feedback template
- New specification proposal template

Document Update Checklist

Task: Write CHECKLIST.md
Check after each change:
- [ ] Have new pitfalls been discovered?
- [ ] Have new patterns been summarized?
- [ ] Do specifications need to be updated?
- [ ] Have tests been added to prevent regression?

Universal Best Practices (Tech Stack Independent)

1. Documentation Writing Principles

WHAT (What it is):

Tech stack and tools
Directory structure and responsibilities
Core concepts and terminology

WHY (Why it matters):

Background of architecture decisions
Explanation of technical debts
Design tradeoff considerations

HOW (How to implement):

Run and test commands
Development workflows
Troubleshooting methods

2. Rule Definition Pattern

Each rule includes:

## Rule N: [Rule Name] [Priority]

**Problem Description**:
Why is this rule needed?

**Correct Practice** (✅):
[Code Example]

**Incorrect Practice** (❌):
[Code Example]

**Common Mistakes**:
- [Mistake 1]
- [Mistake 2]

**Reference Documentation**:
- Detailed explanation: rules/rule-name.md
- Example code: src/module/file.ts:123

3. Experience Accumulation Structure

## Code Style
- Language feature preferences
- Naming and formatting conventions

## Known Pitfalls
- Framework-specific pitfalls
- Common error patterns
- Practices to avoid

## Success Patterns
- Standard workflows
- Reusable templates
- Best practice examples

## Compounding Engineering
- Bug fixes → Specification updates
- Code reviews → Pattern extraction
- Experience → Permanent knowledge

4. Context Management Strategy

Configuration File (CLAUDE.md):

Index nature, < 500 lines
Only contains universally applicable constraints
Detailed content links to documents
Avoid: Code style, over-specification

Rule Documents (rules/):

Independent document for each rule
Comparison of correct and incorrect examples
Common mistakes and solutions
Links to code implementations

Technical Documentation (agent_docs/):

Architecture and design documents
Workflow guides
Troubleshooting manuals
API reference manuals

Main Agent Working Mode

Role Definitions

Main Agent (You):

Think about requirements and implementation plans
Split tasks and direct SubAgents
Do not perform detailed operations
Initiate independent Tasks to verify results

SubAgent (Task Tool):

Execute specific operations
Collect information and analyze
Complete tasks as instructed
Return result reports

Verification Task (Independent General-purpose Agent):

Check implementation quality
Discover anomalies and correct them
Ensure compliance with specifications
Provide improvement suggestions

Workflow

1. Main Agent analyzes requirements
   ↓
2. Split into SubAgent tasks
   ↓
3. Execute multiple Tasks in parallel
   ↓
4. Summarize and analyze results
   ↓
5. Initiate Verification Task for inspection
   ↓
6. Adjust based on feedback
   ↓
7. Proceed to the next phase

Execution Principles

Main Agent:

✅ Think about "why" and "how"
✅ Plan migration paths
✅ Identify risks and dependencies
✅ Evaluate priorities
❌ Do not directly edit files
❌ Do not perform detailed tasks
❌ Do not run commands

SubAgent:

✅ Execute specific operations
✅ Collect and analyze information
✅ Complete tasks as instructed
❌ Do not make decisions
❌ Do not change plans

Verification Task:

✅ Independently verify results
✅ Discover potential issues
✅ Provide improvement suggestions
✅ Ensure quality standards

Verification and Testing

Per-phase Verification Checklist

Phase 1: Current State Analysis

Complete project structure mapping
All existing configurations identified
Implicit knowledge fully mined
Reasonable priority planning

Phase 2: Configuration Migration

CLAUDE.md is complete and < 500 lines
All rules have detailed documentation
Progressive disclosure implemented
No configuration file errors

Phase 3: Experience Accumulation

AGENTS.md covers major pitfalls
Success patterns are actionable
Compounding engineering mechanism established
Experience is reusable

Phase 4: Documentation System

Clear document hierarchy
Correct reference relationships
Complete and accurate content
Easy to find and update

Phase 5: Context Optimization

Simplified configuration
Progressive document disclosure
Pointer references used
Efficient context management

Phase 6: Compounding Mechanism

Git Hooks integrated
Improvement templates complete
Checklist established
Continuous improvement feasible

Overall Verification

bash

Task: General-purpose
Final Verification:
1. Documentation structure completeness
   - CLAUDE.md and AGENTS.md exist
   - rules/ and agent_docs/ are well-organized
   - All references are accessible

2. Content quality check
   - Rules have correct and incorrect examples
   - Pitfalls have specific code examples
   - Workflows are actionable

3. Practicality verification
   - New developers can get started quickly
   - Agents can understand specifications
   - Knowledge is reusable

4. Compounding engineering verification
   - Bug fix process includes document updates
   - Code reviews include specification extraction
   - Experience accumulation mechanism exists

Frequently Asked Questions

Q1: How long should configuration files be?

A: CLAUDE.md should be kept under 500 lines, the shorter the better. Only retain universally applicable content, with detailed explanations in rules/ and agent_docs/.

Q2: How to balance detail and conciseness?

A: Use progressive disclosure:

CLAUDE.md: Index and summary
rules/: Detailed rule explanations
agent_docs/: In-depth technical documentation

Q3: Are code style guidelines needed?

A: Not recommended. Leave this to linters and formatters (ESLint, Prettier, Biome). LLMs are slow and expensive for format checks, and it reduces their ability to follow other instructions.

Q4: How to prevent documentation from becoming outdated?

Use file:line references instead of code copies
Set up Git Hooks to remind document updates
Check document consistency during code reviews
Run verification scripts regularly

Q5: How to handle tech stack-specific content?

A: Adhere to the abstraction principle and extract general practices:

❌ "How to use Prisma"
✅ "ORM Usage Specifications: Singleton Pattern, Transaction Boundaries, Connection Management"

Q6: How long does migration take?

A: Conduct in phases:

Phase 1-2 (Configuration Migration): 2-4 hours
Phase 3-4 (Documentation Improvement): 1-2 days
Phase 5-6 (Optimization Mechanism): Ongoing

It is recommended to complete Phase 1-2 first to enable Agents to start working, then gradually improve the rest.

Resources

Reusable Configuration Templates

The assets/ directory contains:

```
CLAUDE.md.template
```
- Configuration file template
```
AGENTS.md.template
```
- Experience accumulation template
```
rules/
```
- Rule document templates
```
agent_docs/
```
- Technical document templates

Reference Documentation

The references/ directory contains:

```
context-engineering-best-practices.md
```
- Context Engineering Best Practices
```
compounding-engineering.md
```
- Compounding Engineering Guide
```
documentation-structure.md
```
- Documentation Structure Specifications

Execution Scripts

The scripts/ directory contains:

```
analyze_project.py
```
- Project analysis script
```
validate_migration.py
```
- Migration verification script
```
check_docs_consistency.py
```
- Document consistency check script

migration-skill

NPX Install

Tags

SKILL.md Content (Chinese)

Migration Skill: Cursor → Claude Code

Overview

When to Use This Skill

Core Concept Mapping

Migration Process

Phase 1: Current State Analysis (Main Agent)

Phase 2: Configuration File Migration (Main Agent + SubAgent)

Phase 3: Experience Accumulation System (Main Agent + SubAgent)

Phase 4: Documentation System Improvement (Main Agent + SubAgent)

Phase 5: Context Engineering Optimization (Main Agent + SubAgent)

Phase 6: Compounding Engineering Mechanism (Main Agent + SubAgent)

Universal Best Practices (Tech Stack Independent)

1. Documentation Writing Principles

2. Rule Definition Pattern

3. Experience Accumulation Structure

4. Context Management Strategy

Main Agent Working Mode

Role Definitions

Workflow

Execution Principles

Verification and Testing

Per-phase Verification Checklist

Overall Verification

Frequently Asked Questions

Q1: How long should configuration files be?

Q2: How to balance detail and conciseness?

Q3: Are code style guidelines needed?

Q4: How to prevent documentation from becoming outdated?

Q5: How to handle tech stack-specific content?

Q6: How long does migration take?

Resources

Reusable Configuration Templates

Reference Documentation

Execution Scripts

Further Reading