Migrating from Other AI Tools

Level: 🌿 Intermediate

You’ve been using Cursor, Windsurf, Copilot, Continue, Aider, Cody, or OpenAI Codex — and now you want to move to Claude Code. Here’s how everything maps over, what to trim, and how to keep your context clean.

The configuration map

Every AI coding assistant has its own config format, but they all solve the same problems. Here’s where things land in Claude Code:

Concept	Cursor	Windsurf	Copilot	Continue	Aider	Codex	Claude Code
Project instructions	`.cursorrules`	`.windsurfrules`	`.github/copilot-instructions.md`	`.continue/config.json`	`.aider.conf.yml`	`AGENTS.md`	`CLAUDE.md`
File-scoped rules	`.cursor/rules/*.md`	`.windsurf/rules/*.md`	—	`.continue/rules/*.md`	—	—	`.claude/rules/*.md`
MCP servers	`.cursor/mcp.json`	`.windsurf/mcp.json`	—	config.json `mcpServers`	—	`config.toml` MCP section	`.mcp.json`
Personal settings (global)	—	—	—	—	—	`~/.codex/config.toml`	`~/.claude/settings.json`
Personal settings (project)	`.cursor/settings.json`	—	—	—	—	—	`.claude/settings.local.json`
Global instructions	—	—	—	—	—	`~/.codex/AGENTS.md`	`~/.claude/CLAUDE.md`
Ignore patterns	—	—	—	—	`.aiderignore`	—	No direct equivalent

Tool-by-tool notes

Cursor

Cursor’s .cursorrules is the closest equivalent to CLAUDE.md. The key differences:

Cursor rules often contain instructions like “you are a helpful AI assistant” — drop these, Claude Code doesn’t need them
.cursor/rules/*.md files with file-scoped rules map to .claude/rules/*.md — preserve the globs: pattern (Cursor uses path:, Claude Code uses globs:)
.cursor/mcp.json maps directly to .mcp.json — the format is nearly identical

Windsurf

Very similar to Cursor:

.windsurfrules → CLAUDE.md
.windsurf/rules/*.md → .claude/rules/*.md
.windsurf/mcp.json → .mcp.json

GitHub Copilot

.github/copilot-instructions.md → CLAUDE.md — usually shorter and more concise than Cursor rules, so less trimming needed
Copilot doesn’t have MCP support, so there’s nothing to migrate there

Continue

.continue/config.json or .continue/config.yaml contains both rules and MCP configs
Extract the systemMessage or custom instructions → CLAUDE.md
Extract mcpServers section → .mcp.json
.continue/rules/*.md → .claude/rules/*.md

Aider

.aider.conf.yml contains model preferences and behavior settings — most are not directly applicable (use /model and permission modes instead)
.aiderignore has no direct Claude Code equivalent — note this in your migration summary

OpenAI Codex CLI

Codex is the closest in architecture to Claude Code:

AGENTS.md → CLAUDE.md (direct 1:1 equivalent — same purpose, same layering concept)
.codex/config.toml model and sandbox settings → not applicable (use /model and permission modes)
.codex/config.toml MCP servers → .mcp.json
~/.codex/AGENTS.md (global instructions) → Consider putting global rules in ~/.claude/CLAUDE.md
AGENTS.override.md, TEAM_GUIDE.md — check for these Codex fallback filenames too

What to trim and why

The biggest mistake in migration is copying everything verbatim. A 500-line .cursorrules file should not become a 500-line CLAUDE.md. Here’s what to cut:

Drop tool-specific instructions

Anything that addresses the AI tool by name (“as a Cursor AI”, “when generating code in this IDE”) is irrelevant in Claude Code. Drop it entirely.

Drop inferable rules

If the project has tsconfig.json, Claude Code already knows it’s TypeScript. If there’s a package.json, it knows the dependencies. Rules like “this project uses React and TypeScript” are wasted context.

Condense verbose rules

Many rule files are written as conversations rather than directives. Condense:

Before: “When writing code, please always make sure to follow the established coding conventions in this project, including using consistent indentation and naming patterns”
After: “Follow existing code conventions for indentation and naming”

Deduplicate across sources

If you’re migrating from both Cursor and Copilot, the same rules often appear in both. Keep each rule once.

Target: ≤100 lines for CLAUDE.md

A good CLAUDE.md is concise. Prioritize:

Build and test commands
Architecture decisions and conventions
Project-specific rules that aren’t obvious from the code
Tech stack details that affect code generation

Deprioritize:

Style preferences Claude can infer
Generic best practices (“write clean code”)
Boilerplate instructions

MCP migration

MCP (Model Context Protocol) servers need scope decisions:

Project scope (.mcp.json): servers that any team member should use — database tools, project-specific APIs
Local scope (claude mcp add --scope local): servers with personal tokens — personal Notion, personal Slack
User scope (claude mcp add --scope user): general utilities you use everywhere — web search, file converters

Some MCP servers may need re-authentication in Claude Code. After migration, run the servers to verify they connect.

Handling the transition period

You don’t have to delete old configs immediately. It’s fine to keep .cursorrules alongside CLAUDE.md for a while:

The old configs won’t interfere with Claude Code — it only reads its own config files
You can compare results between tools during the transition
When you’re satisfied, clean up the old files at your own pace

Using the migration skill

Run /guide:migrate-to-claude and the skill will:

Scan your project for configs from all supported tools
Analyze and classify each piece of content
Condense and deduplicate rules
Present a detailed migration plan with exact file contents
Wait for your review — you can adjust anything before applying
Execute the migration and show a summary of what changed

The migration is additive — it never deletes your original config files.