Migration Guides

Comprehensive guides for migrating to Claude Code from other AI coding assistants, upgrading between versions, and migrating configurations.

Quick Reference

Migration Decision Tree

What are you migrating?
|
+-- From another AI tool?
|   +-- GitHub Copilot --> See "From Copilot" section
|   +-- Cursor --> See "From Cursor" section
|   +-- Sourcegraph Cody --> See "From Cody" section
|   +-- Aider --> See "From Aider" section
|
+-- Upgrading Claude Code version?
|   +-- Minor version (1.x to 1.y) --> Usually safe, check changelog
|   +-- Major version (1.x to 2.x) --> Review breaking changes
|
+-- Migrating configuration?
    +-- Personal settings --> ~/.claude/settings.json
    +-- Project settings --> .claude/settings.json
    +-- Team settings --> .claude/settings.json + git

Tool Comparison Overview

Core Concepts Mapping

From Copilot

From Cursor

From Cody

Migration Workflow

Phase 1: Assessment

• Document current tool usage patterns
• List custom configurations and rules
• Identify key workflows to preserve
• Note team conventions and standards

Phase 2: Setup

• Install Claude Code: npm install -g @anthropic-ai/claude-code
• Run initial setup: claude
• Configure authentication
• Set permission mode for your workflow

Phase 3: Configuration

• Create CLAUDE.md with project context
• Migrate rules to .claude/settings.json
• Set up hooks for automation
• Configure MCP servers if needed

Phase 4: Validation

• Test key workflows
• Verify file operations work
• Check git integration
• Validate custom commands

Phase 5: Team Rollout

• Document team conventions
• Share configuration files
• Create onboarding guide
• Establish support channel

Configuration File Mapping

Key Differences to Understand

Agentic vs Autocomplete

Claude Code operates in an agentic mode:

• You describe what you want
• Claude plans and executes multiple steps
• Tools are used automatically (file read/write, search, bash)
• You approve or guide as needed

This differs from autocomplete-style tools where you:

• Type code and get suggestions
• Accept/reject line by line
• Manually trigger chat for larger tasks

Context Window vs Embeddings

Claude Code uses a context window approach:

• Relevant files are loaded into context
• Glob and Grep search for specific content
• CLAUDE.md provides persistent project knowledge
• Compaction summarizes when context fills

Other tools may use embeddings:

• Entire codebase embedded in vector store
• Semantic search for relevant snippets
• May miss recent changes until re-indexed

Permission Model

Claude Code has explicit permissions:

• File reads may need approval
• File writes need approval (unless configured)
• Bash commands need approval
• Permission modes control automation level

Common Migration Challenges

Workflow Translation Examples

Code Review

Copilot/Cursor:

Select code -> Right-click -> "Explain" or "Review"

Claude Code:

claude "review the changes in this PR for bugs and improvements"

Bug Fixing

Copilot/Cursor:

Select error -> "Fix this"

Claude Code:

claude "fix the TypeError in src/api/handler.ts"

Test Generation

Copilot/Cursor:

Select function -> "Generate tests"

Claude Code:

claude "write unit tests for the UserService class"

Code Explanation

Copilot/Cursor:

Select code -> "Explain this"

Claude Code:

claude "explain how the authentication flow works in src/auth/"

Best Practices

1. Start with CLAUDE.md

Create a comprehensive CLAUDE.md at project root:

# Project Name

## Tech Stack
- Framework: Next.js 14
- Database: PostgreSQL with Drizzle
- Testing: Vitest

## Conventions
- Use TypeScript strict mode
- Prefer functional components
- Follow existing patterns in codebase

## Key Files
- `src/lib/db.ts` - Database connection
- `src/middleware.ts` - Auth middleware

2. Use Hooks for Automation

Replace IDE-specific automation with hooks:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bun run format"
          }
        ]
      }
    ]
  }
}

3. Configure Permissions Appropriately

Start conservative, loosen as needed:

# Start with default (asks for everything)
claude

# Move to auto-accept edits when comfortable
claude --dangerously-skip-permissions

4. Create Custom Slash Commands

Replace tool-specific commands with slash commands:

<!-- .claude/commands/review.md -->
---
description: Review code changes for issues
---
Review the following code for:
- Potential bugs
- Performance issues
- Security concerns
- Code style violations

5. Leverage MCP for External Data

Replace tool-specific integrations with MCP servers:

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-docs-server"]
    }
  }
}

Validation Checklist

After migration, verify:

• Can create new files
• Can edit existing files
• Can run bash commands
• Can search codebase (Glob, Grep)
• Git operations work
• Custom commands are available
• Hooks execute correctly
• CLAUDE.md context is loaded
• Team members can use shared config

Reference Files