Using CLAUDE.md and Cursor Rules Together

Teams that use both Claude Code and Cursor do not need a philosophical debate about which tool is "the real" coding agent. They need a harness pattern that keeps the tools from disagreeing. Claude Code has CLAUDE.md. Cursor has .cursor/rules. The repo may also have AGENTS.md for Codex or other agents. If every file becomes a separate source of project truth, the team will spend more time debugging instruction drift than debugging code.

The working pattern is simple: make AGENTS.md canonical, make CLAUDE.md a thin Claude Code adapter, and generate or maintain .cursor/rules as scoped Cursor adapters. The goal is not to erase tool-specific behavior. The goal is to stop project rules from living in three places.

This matters more than it looks. A package-manager rule is not a Cursor rule. A branch policy is not a Claude Code rule. A generated-file rule is not an editor preference. Those are project rules. They should be owned once and exposed to every tool that needs them.

The harness layers

Think of the repo's agent instructions as three layers.

The first layer is canonical project policy. It says what the project is, how to install, how to build, how to test, which files are generated, how branches work, what security rules are hard, and where deeper references live. This belongs in AGENTS.md because the name is tool-neutral and Codex treats it as a first-class instruction file.

The second layer is tool adapters. CLAUDE.md is an adapter for Claude Code. .cursor/rules is an adapter for Cursor. A Copilot instructions file would be another adapter. These files should point at the canonical source and then add tool-specific mechanics.

The third layer is enforcement. CI, hooks, permissions, branch protection, and review gates make the rules real. No markdown file can enforce "tests must pass." It can only tell the agent what to do. The harness has to verify it.

Most teams mix these layers. CLAUDE.md contains project policy, Claude hook notes, and a release checklist. Cursor rules contain package-manager policy, component style, and a copied paragraph about Claude slash commands. AGENTS.md gets added later and copies pieces from both. That works for a week. Then it drifts.

The target layout

For a repo using Claude Code, Cursor, and Codex, I want this layout:

AGENTS.md
CLAUDE.md
.cursor/rules/project.mdc
.cursor/rules/frontend.mdc
.cursor/rules/backend.mdc
scripts/sync-agent-rules.ts

AGENTS.md is edited by humans and reviewed as the project policy source. CLAUDE.md is either a symlink to AGENTS.md or a short pointer with Claude-only notes. Cursor rules are either generated from AGENTS.md plus scoped templates, or maintained as small .mdc files with clear ownership.

The important part is not the script name. The important part is direction. Project policy flows outward from AGENTS.md. It does not get invented independently inside each tool.

Worked example: AGENTS.md canonical

Start with a root AGENTS.md:

# AGENTS.md

## Project facts
This is a TypeScript monorepo for a developer tool.
Apps live in apps/. Shared packages live in packages/.

## Commands
- Install: npm ci
- Build all: npm run build
- Test all: npm test
- Lint: npm run lint

## Working rules
- Use npm only. package-lock.json is canonical.
- Branch from main and open a PR. No direct pushes to main.
- Do not edit generated dist/ or packages/api-client/ by hand.
- Never print secret values. Refer to environment variable names only.

## Architecture boundaries
- apps/web owns customer-facing UI.
- apps/admin owns internal workflows.
- packages/ui owns shared primitives after two apps need the component.
- packages/api-client is generated from the OpenAPI schema.

## References
- package.json is the source of truth for commands.
- .github/workflows/ci.yml is the source of truth for CI.
- docs/release.md covers release procedure.

This file is not a generic AI prompt. It is a project map. It gives every agent the same package manager, commands, branch rule, generated-file boundary, and architecture boundary.

Now CLAUDE.md can be tiny:

# CLAUDE.md

AGENTS.md is the canonical project instruction file.
Read AGENTS.md before making changes.

## Claude Code-specific behavior
- Workflow-specific instructions live in .claude/skills/.
- Hooks are configured in .claude/settings.json.
- If this file and AGENTS.md conflict on project rules, AGENTS.md wins.

If your repo tolerates symlinks, this can be even simpler:

CLAUDE.md -> AGENTS.md

I prefer the pointer version when the team has real Claude Code-specific notes. I prefer the symlink only when there are no meaningful Claude-only rules.

Worked example: generated Cursor rules

Cursor needs .mdc files, not just a pointer in prose. Create one always-applied project pointer:

---
description: Canonical project rules
globs:
alwaysApply: true
---

Project rules live in AGENTS.md. Treat AGENTS.md as canonical for package manager,
commands, branch policy, generated files, security rules, and architecture boundaries.

Before changing project-wide behavior, update AGENTS.md first.

That rule does not duplicate every project rule. It tells Cursor where the source is and what kinds of rules are owned there. Then add scoped rules where Cursor's loading model helps.

For frontend:

---
description: Frontend rules for React and UI work
globs: "apps/web/**/*.{ts,tsx,css}"
alwaysApply: false
---

- Use packages/ui primitives before creating app-local primitives.
- Do not introduce a new route without checking apps/web/src/routes.ts.
- Above-the-fold images need width/height or aspect-ratio.

For backend:

---
description: Backend rules for API and data work
globs: "apps/api/**/*.ts"
alwaysApply: false
---

- Public API behavior changes require docs and integration tests.
- New external HTTP calls must set an explicit timeout.
- Do not catch unknown errors unless the handler logs context or rethrows.

Those Cursor rules are not copies of AGENTS.md. They are scoped adapters that Cursor can attach when files match. This is where .cursor/rules is stronger than CLAUDE.md: it can put local guidance close to the files that need it.

A minimal sync script

You do not need a complex generator on day one. A small script can enforce the relationship.

For example, scripts/sync-agent-rules.ts can read a fenced block from AGENTS.md and write the always-applied Cursor pointer:

const cursorProjectRule = `---
description: Canonical project rules
globs:
alwaysApply: true
---

Project rules live in AGENTS.md. Treat AGENTS.md as canonical for package manager,
commands, branch policy, generated files, security rules, and architecture boundaries.

Before changing project-wide behavior, update AGENTS.md first.
`;

That may look too small to matter, but it creates a reviewable contract. If someone edits .cursor/rules/project.mdc by hand, CI can fail and say "run npm run sync-agent-rules." If someone changes package-manager policy in a scoped Cursor rule, review can push it back to AGENTS.md.

The generator should not blindly copy all of AGENTS.md into every Cursor rule. That defeats scoped loading and bloats Cursor context. Generate adapters, not duplicates.

Review rules for teams

Once the layout exists, enforce it socially and mechanically.

Use this review checklist:

- Project-wide rule changed? AGENTS.md changed first.
- Claude Code behavior changed? CLAUDE.md or .claude/ changed.
- Cursor loading behavior changed? .cursor/rules frontmatter changed.
- Package manager, build, test, or branch policy changed? All adapters still point to AGENTS.md.
- Long procedure added? It belongs in docs/ or a skill, not always-loaded files.

This checklist is intentionally boring. The boring parts are where drift starts. Teams usually catch big architecture mistakes. They miss the one-line "use pnpm" rule added to a Cursor file during a rushed fix.

What to do with existing messy files

If CLAUDE.md already has 400 lines and .cursor/rules already has ten copied files, do not rewrite everything in one heroic PR. First classify.

Mark every rule as one of:

project
claude-only
cursor-only
reference
stale

Move project rules into AGENTS.md. Keep Claude-only rules in CLAUDE.md or .claude/. Keep Cursor-only rules in .cursor/rules. Move long reference material into docs/. Delete stale rules after verifying the referenced paths or commands are truly gone.

Then add a small CI check. It can be crude at first: verify that CLAUDE.md contains the pointer sentence, verify .cursor/rules/project.mdc contains alwaysApply: true, and verify AGENTS.md names the package manager and validation commands. You can make it stricter later.

Where this pattern fails

The pattern fails if AGENTS.md becomes a dumping ground. Canonical does not mean huge. AGENTS.md should own project rules, not every workflow detail. Release runbooks, handoff formats, design review checklists, and incident drills belong in docs or tool-specific skills.

It also fails if tool-specific adapters are too thin to be useful. Cursor does benefit from scoped .mdc rules. Claude Code does benefit from skills and hooks. Do not flatten those mechanics into AGENTS.md. Keep the shared policy shared and the tool advantages intact.

Finally, it fails if nobody reviews the relationship. The first drift bug is usually small. A Cursor rule gets a new test command. CLAUDE.md gets a new branch exception. AGENTS.md stays unchanged. No single diff looks dangerous. The combined harness is now inconsistent.

The durable rule

One repo should have one owner for project policy. In a multi-agent repo, AGENTS.md is the cleanest owner. CLAUDE.md and .cursor/rules should adapt that policy into their harnesses and add only the semantics each tool needs.

AgentLint belongs at the end of this loop because it can inspect the files as a unit. It catches the moment AGENTS.md, CLAUDE.md, Cursor rules, CI, and hooks stop telling the same story.