how to use cursor and claude code together (without losing your mind)

Most developers don’t use just one AI coding tool. They use Cursor for the IDE experience, Claude Code when they need a powerful agentic workflow, and maybe Copilot because it’s already built into GitHub. The tools are genuinely complementary — they’re good at different things.

The problem is the configuration. Cursor wants .cursor/rules. Claude Code wants CLAUDE.md. These files do the same job — tell your AI assistant about your project — but in completely different formats. Keep both tools, and you’re either maintaining duplicated configs or watching them drift apart until one of your AI assistants is giving advice based on outdated information.

This guide is about using both tools well, with a workflow that keeps everything in sync.

Why developers run Cursor and Claude Code together

Each tool has genuine strengths:

Cursor is exceptional for inline completions, tab autocomplete, and in-editor chat. It feels like a pair programmer sitting next to you. The MDC rules format lets you target specific files and contexts with precision. For day-to-day coding flow, the UX is hard to beat.

Claude Code is exceptional for complex agentic tasks — refactoring large codebases, writing comprehensive tests, planning architecture, working across many files at once. The command-line-first workflow makes it easy to orchestrate multi-step tasks without interrupting your editor.

These aren’t competing tools, they’re complementary ones. The question is how to configure both without the maintenance burden eating your productivity gains.

The config drift problem

Here’s what config drift looks like in practice. You spend an hour writing a detailed .cursor/rules/conventions.mdc that captures your team’s TypeScript patterns, naming conventions, and testing approach. Cursor is now excellent.

Two months later, your team adopts a new state management library. You update .cursor/rules. But you forget to update CLAUDE.md. Now Claude Code is suggesting the old patterns while Cursor is using the new ones. Your two AI assistants are contradicting each other.

This happens constantly. And it gets worse with more tools.

A workflow that actually works

The key is having a single source of truth that both tools pull from.

Option 1: AGENTS.md as the shared base

Create an AGENTS.md in your repo root with all the project context that both tools need. Then use tool-specific files for platform-specific configuration only.

AGENTS.md                            # shared project context
CLAUDE.md                            # Claude Code-specific (hooks, tool permissions)
.cursor/rules/
  conventions.mdc                    # Cursor-specific rule targeting

Your CLAUDE.md can be brief if AGENTS.md handles the project context:

See AGENTS.md for project context and conventions.

## Claude-specific

- Use the Bash tool to run tests before marking any task complete
- Check TypeScript errors with `pnpm check` before finishing
- Always create a summary of changes made

Your cursor rules can focus on what MDC format does uniquely well — glob-targeted rules:

---
description: "API route conventions"
globs: ["app/api/**/*.ts"]
alwaysApply: false
---

All API routes use the route handler pattern.
Return typed `ApiResponse<T>` objects.
Handle errors with try/catch and return appropriate status codes.

Option 2: Start from a shared config in spaget

spaget lets you build one agent configuration and export to both formats simultaneously. This is especially useful for teams — one person updates the shared config, everyone re-exports, and both their Cursor rules and CLAUDE.md files stay in sync automatically.

The workflow:

Build your agent configuration in spaget (project context, skills, conventions)
Export to .cursor/rules format and CLAUDE.md format
Commit both to your repo
When conventions change, update in spaget and re-export both

No account required to try this — open the builder and experiment with the export formats.

Task routing: using the right tool for the job

Once your configs are in sync, the higher-leverage question is: when do you reach for Cursor vs. Claude Code?

Use Cursor for:

Inline code completion while actively writing
Quick file edits with in-editor chat (Cmd+K)
Context-aware completions that understand your current file
Fast iterations on small, localized changes

Use Claude Code for:

Anything spanning more than 3-4 files
“Add authentication to this app” style tasks
Writing comprehensive test suites
Codebase exploration and question answering (claude ask)
Complex refactors with architectural implications
Tasks where you want to see a plan before execution

The mental model: Cursor is your always-on copilot for the current file. Claude Code is the specialist you call in for a complex job.

Practical setup walkthrough

Here’s a concrete setup for a Next.js project using both tools.

Your AGENTS.md (shared context)

# Project

Next.js 15 App Router application. TypeScript strict mode.
Tailwind CSS. Prisma + PostgreSQL. NextAuth.js for authentication.

# Stack

- Next.js 15 with App Router (not Pages Router)
- TypeScript strict mode
- Tailwind CSS — no CSS modules
- Prisma ORM with PostgreSQL
- NextAuth.js v5 for authentication
- Vitest for unit tests
- Playwright for e2e tests

# Conventions

- Server components by default
- Client components only when state or browser APIs are needed
- All database queries go in `lib/db/` — never in components or route handlers
- Use server actions for mutations
- Zod for all input validation

# Commands

- `pnpm dev` — development server
- `pnpm test` — Vitest unit tests
- `pnpm test:e2e` — Playwright e2e tests
- `pnpm db:push` — sync Prisma schema

# Avoid

- No `any` types
- No barrel files
- No direct database calls outside `lib/db/`

Your CLAUDE.md (Claude Code-specific)

See AGENTS.md for project context.

## Working with this codebase

Before marking any task complete:
1. Run `pnpm test` — all tests must pass
2. Run `pnpm check` — no TypeScript errors
3. Run `pnpm lint` — no lint errors

## Tool usage

- Use Bash to run tests and verify changes
- Use `pnpm db:push` to apply schema changes (never `prisma migrate dev` in dev)
- Check for existing utilities before creating new ones

Your cursor rules (Cursor-specific)

---
description: "Project conventions"
alwaysApply: true
---

[Project context from AGENTS.md applies here — conventions, stack, commands]
Focus on specific Cursor behaviors: prefer completions that match the existing
patterns in the file being edited. For components, follow the patterns in
src/components/ui/ as the canonical examples.

Keeping both configs fresh

The discipline that makes this work: treat your config files as living documentation, not a one-time setup.

When your team makes an architectural decision, update AGENTS.md first (it’s the source of truth), then update any tool-specific extensions. If you’re using spaget, update the config there and re-export everything at once.

Review your configs quarterly. Ask: is every line still accurate? Are there new patterns the AI keeps getting wrong that should become explicit rules?

The bottom line

Cursor and Claude Code are better together. The key is keeping their configurations in sync so they’re giving you consistent, accurate assistance — not contradicting each other based on config files that have drifted apart.

Pick a single source of truth (AGENTS.md or a visual builder like spaget), layer platform-specific configs on top, and commit the discipline of keeping it current. Your AI assistants are only as good as the context you give them.