Migrating Between AI Coding Assistants

Switching from Cursor to Claude Code? Adding Copilot alongside Windsurf? Here's how to migrate your agent rules without starting from scratch.

The Core Principle

The good news: agent rules are fundamentally the same concept across all tools — a Markdown document that tells the AI about your project. The differences are in file naming, location, and a few tool-specific features.

Migration Paths

From .cursorrules to CLAUDE.md

1. Copy your .cursorrules content to CLAUDE.md
2. Cursor-specific references (like "when I use Cmd+K") can be removed
3. Add Claude-specific guidance if needed (e.g., "When using Claude Code CLI...")
4. The rest transfers directly — tech stack, code style, architecture rules all work the same

From .cursorrules to copilot-instructions.md

1. Copy content to .github/copilot-instructions.md
2. Remove Cursor-specific interaction references
3. For path-specific rules, use .github/instructions/ directory with applyTo frontmatter
4. Keep the content focused — Copilot works best with concise instructions

From CLAUDE.md to .cursorrules

1. Copy CLAUDE.md content to .cursorrules
2. Remove any Claude-specific references
3. Consider splitting into .cursor/rules/ directory for organization

What Transfers Directly

These rule categories work identically across all tools:

• Tech stack declarations: Frameworks, libraries, versions
• Code style rules: Naming, formatting, patterns
• Architecture rules: File structure, module boundaries, import rules
• Testing conventions: Frameworks, patterns, requirements
• Security rules: Validation, sanitization, secrets management
• Negative instructions: "Never use X", "Avoid Y"

What Needs Adaptation

• Tool-specific interaction patterns: "When using Composer..." or "In inline edit mode..."
• File references: Cursor's @file syntax differs from CLAUDE.md's @path import syntax
• Path-scoping syntax: Cursor uses globs, Claude Code uses paths, Copilot uses applyTo, and Cline uses paths — all in YAML frontmatter but with different field names
• User-level settings: Each tool has its own global config location (~/.claude/, ~/.codex/, ~/.gemini/, etc.)

Maintaining Multiple Formats

If your team uses multiple AI tools, you have two approaches:

Approach A: Single Source of Truth

Maintain one canonical rules file and use a script or the Agent Rules Builder to export to each format. This ensures consistency but requires a build step.

Approach B: Shared + Specific

Have a shared base that all formats reference, plus small tool-specific additions:

codeCopy
my-project/
├── .cursor/rules/                      # Cursor rules directory
├── CLAUDE.md                           # Claude Code
├── .claude/rules/                      # Claude path-scoped rules
├── .github/
│   ├── copilot-instructions.md         # GitHub Copilot
│   └── instructions/                   # Copilot path-specific rules
├── .windsurf/rules/                    # Windsurf rules directory
├── .clinerules/                        # Cline rules directory
├── AGENTS.md                           # OpenAI Codex
├── GEMINI.md                           # Gemini CLI
├── .agent/rules/rules.md              # Google Antigravity
└── docs/
    └── ai-rules-base.md                # Shared rules (source of truth)

In practice, most of the content (90%+) is identical across all formats. The small tool-specific additions rarely justify the maintenance overhead of separate files.

Using Agent Rules Builder

The simplest migration path: paste your existing rules into the Agent Rules Builder, or build new rules from your stack, and export to all formats at once. This guarantees consistency and gives you a well-structured baseline for every tool.

Tips for a Smooth Migration

1. Don't start from scratch — your existing rules contain valuable project knowledge
2. Test with a common prompt — ask each tool the same question and compare output
3. Migrate incrementally — start with core rules, then add tool-specific ones
4. Keep rules format-agnostic — avoid tool-specific syntax in your core rules
5. Review quarterly — remove rules for tools your team no longer uses