How to share project context between Cursor and Claude Code

The problem: the same instructions in two places

Cursor and Claude Code both read project-specific context, but they use different mechanisms to find it. A team that uses both can end up maintaining the same instructions twice, once for each agent.

That is cheap on day one. It gets expensive when the instructions change. Someone updates a rule in one file, the other file is not touched, and the two agents start giving different answers about the same codebase.

How Cursor handles project context

Cursor has three places for persistent instructions:

• Project rules in .cursor/rules. Each rule is an .mdc file with frontmatter that decides when it applies: always, only when the agent judges its description relevant, only when a matching file is in context, or only when mentioned by hand. Project rules are version-controlled with the repository.
• AGENTS.md, a plain markdown file in the project root or a subdirectory. Nested files apply to their own directory.
• User rules, set in Cursor and applied to every project on your machine. Teams on Cursor's Team and Enterprise plans can also define team rules in the Cursor dashboard.

Rules shape Cursor's Agent chat. They do not affect Cursor Tab or its other AI features.

How Claude Code handles project context

Claude Code starts every session with a fresh context window and loads instructions from files:

• CLAUDE.md at ./CLAUDE.md or ./.claude/CLAUDE.md for project-wide instructions, ~/.claude/CLAUDE.md for personal ones, and CLAUDE.local.md for private project preferences. Files in subdirectories load when Claude works on files there.
• Imports. A CLAUDE.md can pull in other files with @path/to/file.
• .claude/rules/, a directory of markdown files that can be scoped to file paths.
• AGENTS.md. Claude Code reads it when no CLAUDE.md exists in the working directory or above it. If both exist, it reads the CLAUDE.md files only, unless CLAUDE.md imports AGENTS.md.

Anthropic describes these files as context, not enforced configuration. Specific, short instructions are followed more consistently than long ones.

Why project context drifts

Drift needs two copies and a reason to edit one of them. Teams that use more than one agent usually have both. The content that drifts first tends to be:

• Architecture rules, such as "controllers never access the database directly".
• Coding conventions: naming, error handling, test layout.
• Project specifications: how checkout works, what the API contract says.
• Implementation constraints: the library you decided not to use, and why.
• Team knowledge that lives in a wiki or a person's head and only reaches an agent when someone pastes it into a chat.

Nothing fails loudly when two copies disagree. The agent just follows whichever one it was given.

Option 1: keep context in the repository

The simplest approach is a single instruction file in the repository, reviewed in pull requests like code. AGENTS.md makes this practical for two agents: Cursor reads it, and Claude Code reads it when no CLAUDE.md exists. If you want a CLAUDE.md as well, it can import AGENTS.md so the content stays in one file.

The advantages are real:

• The instructions are versioned with the code they describe.
• Anyone who clones the repository gets them. There is nothing else to set up.
• Changes go through the review process you already trust.

For one repository, with a short set of rules and a team that is happy to keep them in version control, this is usually enough. Start here.

It starts to strain when the context should not live in the repository: large specifications that would bloat every session, knowledge shared across several repositories, or material that belongs to a client rather than to the codebase. The guide on keeping AI coding agent rules outside your repository covers those cases.

Option 2: maintain agent-specific context

You can also use each agent's native features fully: .cursor/rules with globs and descriptions for Cursor, CLAUDE.md and .claude/rules/ for Claude Code. Each agent gets context in the format it handles best, including per-file scoping.

This works well when most of the team uses one agent, or when the two agents need different things. The cost shows up when they need equivalent context. The same rule exists in two formats, and keeping them aligned is manual work with no check that it was done.

Option 3: use an agent-independent context layer

The third approach separates two things the first two combine: what the project knows and how a particular agent loads it.

In this model, rules, specifications, and work items are stored once, outside any agent's own configuration. Each agent is connected to that store through whatever mechanism it supports, and adding a new agent means adding a connection, not rewriting the content.

There are three distinct kinds of context in these options. Repository context is stored in the repository and shared by everyone who clones it. Agent-specific context is written in one agent's format and read by that agent only. Agent-independent context belongs to the project and is delivered to whichever agent is working on it.

Sharing project context with XOROX

XOROX is an agent-independent project context layer for AI coding agents. It is built on the model above and currently supports Cursor and Claude Code. It organizes project knowledge into three things:

• Rulesets: persistent instructions such as conventions and architecture rules. They reach the agent automatically.
• Specifications: detailed project knowledge. The agent receives an index of names and descriptions, and retrieves the full text when it decides one is relevant.
• Tasks: the implementation queue, linked to the Specifications each task needs. Tasks can come from XOROX itself, from GitHub Issues and Project items, or from a Notion task board.

Rulesets and Specifications can also be backed by existing sources. A Ruleset can be read from a file in a connected GitHub repository, and Rulesets and Specifications can be created from Notion pages.

How each agent receives it

The delivery mechanism differs by agent, and the content does not. In Cursor, a beforeSubmitPrompt hook supplies the active Rulesets and the Specifications index with every prompt. In Claude Code, a SessionStart hook tells the agent to retrieve the Rulesets before working, and a UserPromptSubmit hook delivers them again when they change. In both, Specifications and Tasks are retrieved through the XOROX MCP server. The details are on the Cursor and Claude Code pages.

Setup

Install the xorox command-line tool. On macOS or Linux:

curl -fsSL https://xorox.eu/install.sh | sh

On Windows, in PowerShell:

irm https://xorox.eu/install.ps1 | iex

Then connect each project from inside it:

cd your-project
xorox init

xorox init asks for the project ID and a project credential, checks them, and configures the agents it finds on the machine: Cursor, Claude Code, or both. The credential is typed hidden and stored in user-level configuration readable only by you. It is not written to the repository and does not belong in a .env file. The files xorox init adds to the project are kept local through .git/info/exclude. See Installation and Quickstart for the full flow, including the one-time step to enable the XOROX MCP server in Cursor.

Example workflow: one team, two agents

Take a team with an API service. They have three pieces of project knowledge: an architecture rule ("all endpoints go through service classes"), API conventions (error format, pagination, naming), and a specification for the billing flow. Some developers use Cursor, others use Claude Code, and a few switch between them.

1. The architecture rule and API conventions are written as Rulesets. Both apply to every task, so both belong in the always-delivered layer.
2. The billing flow is a Specification, described as "Billing and payment-state transitions. Applies to anything touching invoices or subscriptions." It is only loaded when the work needs it.
3. The work comes from the team's GitHub Issues. Each is a Task in the same queue, linked to the billing Specification where relevant.

A developer in Cursor and a developer in Claude Code both receive the same two Rulesets. When either starts a billing task, their agent sees the Specification in its index and retrieves it. When the team changes the pagination convention, they edit the Ruleset once. Cursor picks it up with the next prompt. Claude Code receives the new version on its next prompt as well, and new sessions start with it.

Nothing was copied into .cursor/rules or CLAUDE.md, so there was nothing to keep in sync.

When you don't need XOROX

If you are one developer, you use one coding agent, you work in one repository, and you are comfortable keeping the instructions there, the agent's native files are probably enough. A well-kept AGENTS.md or CLAUDE.md costs nothing and has no moving parts. Adding a context layer to that setup adds a system without removing a problem.

An agent-independent layer becomes more useful when one or more of these is true:

• More than one agent works on the same project and needs equivalent context.
• A team shares rules and wants one place to change them. See managing shared AI coding rules across a development team.
• Several projects need the same conventions, or you move between them often.
• Client projects carry context that should stay with the client project, not with a developer's machine or one agent's configuration. See managing AI coding context across multiple client projects.
• The context should not live in the repository, because it is large, private, or owned by someone who does not commit to that repository.

Summary

• Cursor reads .cursor/rules and AGENTS.md. Claude Code reads CLAUDE.md, .claude/rules/, and AGENTS.md when no CLAUDE.md is present.
• For one repository, a shared AGENTS.md (or a CLAUDE.md that imports it) is the simplest way to avoid duplication.
• Agent-specific files give the most control but need to be kept in sync by hand when both agents need the same content.
• An agent-independent context layer stores rules, specifications, and tasks once and delivers them to each agent. XOROX is one such layer, supporting Cursor and Claude Code today.
• If you have one agent and one repository, you likely do not need one.