I run Cursor and Claude Code together on the same projects. Both tools see the same codebase, but they inject rules in fundamentally different ways. Early on I didn't know this and copy-pasted the same markdown to both sides. One side followed it well, the other slowly forgot. After a month of confusion I landed on the conclusion that "these two are different species when it comes to context injection."

This post unpacks that difference from a solo dev's perspective. On the surface they're both just one markdown file, but crack them open and Cursor Rules has four modes, while CLAUDE.md has three layers plus an import system. Use them without knowing this and the same rule ends up injected twice per message eating tokens, or the file exists but the model never reads it.

I run 16 iOS apps and a few SaaS products as a solo indie. Mixing two or more tools is daily life for me. I hate writing the same rule twice, and I hate even more spending time debugging rules that don't get followed. That's the motivation for this post — how AI coding tool context injection patterns differ, how to split things when running both, and five common traps.

TL;DR

• Cursor Rules is injected per inline edit. CLAUDE.md is loaded once at session start, with child-dir files added on demand.
• Cursor's .mdc has 4 modes (Always Apply / Apply Intelligently / Apply to Specific Files / Apply Manually). CLAUDE.md has 5 locations (~/.claude/, project root, CLAUDE.local.md, parent dirs, child dirs) + @import.
• For the same rule across both, short imperative for Cursor and descriptive context for Claude makes them stick.
• Never commit globals to git. Project CLAUDE.md gets committed, CLAUDE.local.md goes in gitignore.
• The 2026 trend is AGENTS.md as the single source of truth + Cursor/Claude/Codex/Copilot all importing from it.
• When rules don't stick, it's almost always either "the file wasn't actually read" or "two rules contradict each other."

At a glance

Why Cursor Rules and CLAUDE.md are different species

Surface-level, both are markdown. But the tools' usage patterns differ. Cursor's main mode is inline edit. You fix short blocks of code on the spot. Claude Code's main mode is the agent session. Once you start, it autonomously runs dozens of tool calls. That difference is reflected directly in how each rule file is structured.

Cursor builds a fresh system prompt for every inline edit request. So it injects the rules every time. Token cost every time. That's why Cursor Rules works best with short, forceful imperatives. One-line rules like "use Tailwind only" or "App Router only" — the model re-reads them every request.

Claude Code sessions are long. Once you start, it carries the same system prompt all the way through. So CLAUDE.md works better with background context than short commands. Things like "this is why the codebase is structured this way," "here are the danger zones," "here's who I am" — descriptive prose. Material the model references when making its own judgment calls.

When I didn't know this and copy-pasted the same rules to both sides, Claude got annoyed by the imperative tone and started routing around the rules. Cursor was too long, so it only listened to the first 30 lines and skimmed the rest. Just splitting the tone alone visibly improved rule compliance on both tools.

The 4 modes of Cursor Rules

.cursor/rules/*.mdc files are markdown with frontmatter. The frontmatter field combination determines the mode. Early on I didn't read this and just slapped alwaysApply: true on everything, wasting all the efficiency.

---
description: SwiftUI iOS work rules
globs: "**/*.swift"
alwaysApply: false
---

- Swift 6, async/await
- Prefer @Observable macro, no ObservableObject
- No completion handlers
- Split long Views with ViewBuilder

Always mode (alwaysApply: true) is forcibly injected on every request. Same as the old .cursorrules file. I put danger rules here (no production touches, no force push). Only items where forgetting causes accidents.

Auto mode (alwaysApply: false + globs filled in) auto-injects only when globs match. The example above only injects when touching a .swift file. I split stack-specific conventions into this mode.

Agent-requested mode (only description filled, both globs and alwaysApply empty) lets the model decide whether to pull it in. If the description looks relevant, the model fetches it. I keep things like occasional code review checklists or migration procedures here.

Manual mode (just the name, all auto-triggers off) only loads when explicitly called via @rulename in chat. For templates I don't want forced but want to summon on demand.

After a year of running this, my settled ratio is Always 20%, Auto 60%, Agent 15%, Manual 5%. Stuff too much into Always and per-request token cost balloons while the model's attention drops.

CLAUDE.md's 3 layers and @import system

CLAUDE.md doesn't have modes — it has layers. It reads from three places. ~/.claude/CLAUDE.md (global), <project root>/CLAUDE.md (project), and CLAUDE.md inside subfolders. All three get pasted whole at the front of the system prompt at session start.

Global is my personal identity. Name, tone, my regular stack, hard-banned actions. My global is about 50 lines.

Project root is for that codebase only. Stack structure, folder conventions, danger zones. If something contradicts the global, this is where I explicitly override. For example if global says "TypeScript strict" but some legacy project says "any allowed for now," I write in the project CLAUDE.md: "override the global strict rule for this project."

Sub-directory applies only inside that folder. SwiftUI conventions go in apps/ios/CLAUDE.md, Next.js conventions in apps/web/CLAUDE.md. Works well for monorepos.

There's also @import syntax. Write @docs/conventions.md inside CLAUDE.md and it pulls that file in too. My project CLAUDE.md is about 50 lines and imports two files: @docs/stack.md and @docs/danger.md.

Context injection timing — every time vs once

This is the most important difference. Cursor and Claude inject rules at fundamentally different moments.

Cursor rebuilds the system prompt every request. Rules get injected every time. Token cost every time. Upside: add a new rule and the next request applies it instantly.

Claude Code reads once at session start. It carries the same system prompt until that session ends. Token cost is small thanks to prompt cache. Downside: changing a rule doesn't apply to the existing session. You need a new session for the new rule to land.

Add a rule in Cursor and the next inline edit picks it up. Same scenario in Claude requires /clear to reset the session, or opening a new conversation. I once spent 30 minutes confused about "why isn't it picking up the new rule" before I figured this out.

globs matching vs @import — file-splitting pattern

Cursor Rules splits by file via globs. Touch a .swift and only iOS rules come in; touch a .tsx and only Next.js rules come in. No noise in the model context.

.cursor/rules/
├── always-danger.mdc        # alwaysApply: true
├── nextjs-stack.mdc         # globs: "**/*.{tsx,ts}"
├── ios-swiftui.mdc          # globs: "**/*.swift"
├── tailwind.mdc             # globs: "**/*.{tsx,jsx,html}"
└── pr-template.mdc          # manual

CLAUDE.md splits via @import. The main file acts as the entrypoint and imported files trail along. Downside: no globs matching, so everything loads regardless of work context. Every import behaves like alwaysApply: true.

# Project: apsity

@docs/stack.md
@docs/conventions.md
@docs/danger.md

## Extra notes
- Add new routes under app/
- DB schema changes always via migration files

For Cursor I split fine by stack, for Claude I bundle into bigger chunks. Since everything loads on Claude anyway, fine-grained splitting is meaningless. But I never let an imported file go past 200 lines — model attention drops past that line.

Token cost and noise control

Stuffing too many rules in is the trap indie devs fall into most. I crammed 200 lines into a single page. The result was the model dutifully followed the first 30 lines and "is that even there?" the rest.

On Cursor this also hits as direct token cost. Rules go in every request, so a 200-line ruleset is 200 lines of tokens per inline edit. If I do 50 inline edits a day, that's 10,000 lines of tokens per day. Split with globs and usually only 30-50 lines load — 1/4 the tokens.

The rule-writing guide I've settled on has three parts:

1. Write in measurable form. "Write clean code" doesn't land — "split functions over 50 lines" does.
2. One rule per line, one command per rule.
3. Attach a short "why." Claude generalizes when it knows the reason.

Strategy for running both tools together

Only danger rules duplicate across both. Stack conventions go heavily on the Cursor side. Codebase background goes heavily on the Claude side. Personal identity only goes in Claude global.

Debugging order when rules don't stick

I debug "this rule isn't sticking" more often than I write new rules. Almost every case falls into these 4 steps.

Step 1, confirm the file actually got read. On Claude Code, in the first message of a session, ask "list 3 of the danger rules I put in CLAUDE.md." If the answer is accurate, it read it.

Step 2, recheck the rule mode. In Cursor, if alwaysApply: false and both globs and description are empty, that rule will never auto-inject. Always check the frontmatter first.

Step 3, check for rule contradictions. When global vs project, or .cursorrules vs .cursor/rules/*.mdc conflict, the model follows whichever is more strongly worded.

Step 4, check whether the rule is too abstract. "Write clean code" doesn't land. "Split functions over 50 lines" lands. Has to be measurable.

One more thing. Cursor's .cursorrules (old format) and .cursor/rules/*.mdc (new format) both apply when both exist. Keeping both around duplicates rules and confuses the model. Migrate and delete the old file immediately.

Security and git commit policy

Project-level files always get committed, globals never.

<project>/CLAUDE.md, .cursorrules, .cursor/rules/*.mdc are part of the codebase. New collaborators or future-me need the same rules. Don't put them in .gitignore.

The opposite for ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md and other globals — those are personal identity. Email, tone preferences, even names of apps I run. Pushing this to git causes accidents. I keep them in a separate private dotfiles repo.

Watch for secrets inside rule files. I once accidentally put a Supabase project ID in CLAUDE.md. After that I don't put env var names or identifier-style things in rule files. I stop at "env vars live in .env.local."

Real example — my SaaS setup

Project root CLAUDE.md (descriptive context):

# Project: apsity

## Stack
- Next.js 15 App Router, TypeScript strict
- Supabase (PostgreSQL + Auth + Storage)
- Vercel deploy, Tailwind v4

## Structural decisions
- Prefer Server Components, 'use client' only for interactions
- Data fetching: call Supabase directly from Server Components
- API routes only for webhooks and external calls
- Auth via RLS, no backend if-statements

@docs/danger.md
@docs/conventions.md

Same folder's .cursor/rules/nextjs-stack.mdc (imperative, auto via globs):

---
description: Next.js + TypeScript work rules
globs: "**/*.{ts,tsx}"
alwaysApply: false
---

- App Router only. Don't write Pages Router code.
- Minimize 'use client'. Branch at the top of the component tree.
- Tailwind utils only. No styled-components.
- No `as` casting. If unsure, unknown then narrow.
- Split functions over 50 lines.

And .cursor/rules/always-danger.mdc (every-request injection):

---
description: Danger zone guards
alwaysApply: true
---

- Confirm with user before editing supabase/migrations/.
- Never print production env vars.
- DB schema changes always via migration files.
- No git push --force.
- Never read or modify .env files.

Same ruleset, but Cursor gets short commands and Claude gets background + reasoning. They don't conflict.

AGENTS.md — the 2026 single-source-of-truth trend

Pinning the same rule in two files is obviously inefficient. So starting late 2025, AGENTS.md rose as a standard. OpenAI Codex defined it first, and in December 2025 it was donated to Linux Foundation/AAIF. As of 2026, Cursor, Claude Code, Codex CLI, GitHub Copilot, Devin, Windsurf, and Gemini CLI all read AGENTS.md.

My ops pattern got simpler. Keep AGENTS.md as the source of truth, then @AGENTS.md import via a single line in .cursor/rules/index.mdc, @AGENTS.md import in CLAUDE.md, same for other tools. Edit one file and every tool reflects it.

That said, Claude Code's global (~/.claude/CLAUDE.md) and Cursor's user rules (app settings screen) can't be sync'd outside the tool — personal identity, voice — so they stay out of the AGENTS.md source. The source holds project conventions, codebase rules, and danger rules only.

Wrap-up

Cursor Rules and CLAUDE.md look similar on the surface — both markdown — but inside they're entirely different systems. Cursor is short rulesets injected per inline edit; CLAUDE.md is descriptive context pinned at session level. When writing the same rule in both places, you have to match the tone too for both to listen.

My one-year conclusion is simple. Don't pin both files from the start — start with one tool, one file. When that file goes past 80 lines, then split via globs or @import. When you adopt the second tool, that's when you extract AGENTS.md as the source. Build everything up front and you'll just have rules that go unfollowed.

Official sources

• Cursor Rules official docs
• Anthropic Claude Code memory guide
• Anthropic Claude Code Best Practices
• AGENTS.md standard (Linux Foundation/AAIF)
• AGENTS.md — OpenAI Codex guide
• Anthropic prompt caching official docs

This post is current as of 2026-04-30. Both Cursor and Claude Code update their rule systems quickly — six months out, this may need a recheck. The SaaS I run, apsity, is built for solo developers.