How to manage shared AI coding rules across a development team

AI coding agents are usually set up with project-specific instructions. For one developer, that is a file or two and a few habits. For a team, it becomes a question of which version is current.

A team might have repository-level instructions, personal agent configuration, Cursor-specific context, Claude Code-specific context, architecture documents, specifications, and conventions copied from older projects. Each of those can be correct on its own. Together they raise a harder question: which version represents how the team wants software to be built?

This guide is about that question. It is not about whether developers can be trusted to write good instructions. The problems are consistency, maintenance, and ownership.

What are shared AI coding rules?

Shared AI coding rules are project or organization-level instructions that multiple developers use when working with AI coding agents. They describe how the team builds software, so any agent working on the project can follow the same approach.

Rules are not limited to formatting preferences. Common categories are:

• Architecture. Controllers stay thin. Business logic belongs in services. Database access follows the agreed project patterns.
• Testing. New behavior requires tests. External APIs are mocked in unit tests.
• API conventions. Response structure, error handling, and pagination patterns.
• Security. Authentication requirements, authorization boundaries, and how credentials are handled.
• Project constraints. Supported runtime versions, libraries to use or avoid, and deployment or environment assumptions.

Project specifications and workflow instructions belong in the same family. They are longer and more specific than rules, but they are the same kind of shared knowledge.

Why individual AI configurations start to drift

Context drift occurs when developers, repositories, or coding agents maintain separate copies of the same engineering knowledge and those copies stop matching.

Consider a five-developer team that uses both Cursor and Claude Code. At the start, everyone has the same instructions. Over the following months:

• One developer improves the testing rules in their local setup.
• Another updates the architecture notes in the repository documentation.
• A new decision about error handling is added to the Cursor rules but not to the Claude Code ones.
• An older repository still carries last year's convention.
• A new developer copies a setup from whoever is nearest, and it is already out of date.

No single change is a mistake. The result is that different developers, and different agents, work from different context on the same project.

This is the same mechanism described in sharing project context between Cursor and Claude Code, applied to a whole team rather than one person using two agents.

Decide what belongs to the team

Not every instruction should be shared. A practical split has three levels:

• Organization-level context: general engineering standards, security expectations, reusable architecture principles.
• Project-level context: this project's architecture, domain rules, API conventions, technical constraints, and specifications.
• Developer preferences: how verbose the agent should be, preferred explanation style, local experiments.

Shared engineering decisions need a clear source of truth. Personal preferences do not. Both agents already have a place for them: Cursor has user rules that apply across your projects, and Claude Code reads ~/.claude/CLAUDE.md and a private CLAUDE.local.md. Keeping preferences there leaves the shared context shorter.

Option 1: store shared rules in the repository

For many teams this is the simplest approach, and often the right one. Rules live in AGENTS.md, CLAUDE.md, or .cursor/rules, and are committed with the code. Both Cursor and Claude Code read project instruction files, and both can read AGENTS.md.

The advantages:

• The rules are version controlled and reviewed alongside code changes.
• The whole team can see them.
• They are tied to the project they describe.
• There is no additional infrastructure.

The trade-offs:

• Organization-level rules are duplicated across repositories.
• Different agents consume instruction files differently, so one file may not serve both equally well.
• Reusable team knowledge becomes coupled to individual repositories.
• A change has to be propagated to every project that carries the rule.

If your team has one repository, one primary coding agent, and wants its instructions versioned with the code, repository-level rules may be all you need. The trade-offs are covered in more detail in keeping AI coding agent rules outside your repository.

Option 2: maintain agent-specific shared configuration

Another model is to maintain a configuration for each agent the team uses: Cursor project rules, with descriptions and file globs that control when they apply, and a CLAUDE.md with .claude/rules/ for Claude Code. Each can be shaped to how that agent loads context.

The cost is that overlapping knowledge now has two representations. A decision about error handling must be written twice, in two formats, and updated in both. Nothing checks that the two still agree, so the same architectural decision can drift between agents even when everyone follows the process.

This works when the team mostly uses one agent, or when the agents genuinely need different content.

Option 3: use a shared agent-independent context layer

An agent-independent context layer gives teams a shared source for project knowledge without tying that source to one coding agent. The team maintains rules, specifications, and background knowledge in one place. Each supported agent is connected to that place, and each developer works with whichever agent they prefer.

The benefits are practical:

• Consistency. Everyone starts from the same project context.
• Central updates. A decision is changed once, not once per developer or agent.
• Reuse. Context can serve several projects.
• Ownership. Someone is responsible for the shared source.
• Less duplication, and a source that does not depend on any one agent.

Shared context and developer onboarding

Without shared context, a new developer has to find the right instruction files, copy someone's local configuration, learn the architecture conventions from scattered documents, configure each agent separately, and work out which documentation is current. Each step is small. Together they mean the developer's agent may know less about the project than their teammates' agents do for weeks.

With one clear source, onboarding is closer to connecting to the team's current project context than assembling it. The developer is not choosing between versions.

Managing updates without context drift

The lifecycle is simple:

1. The team agrees on an engineering or project rule.
2. The shared source of truth is updated.
3. Developers' agents use the updated context.
4. Old independent copies do not have to be tracked down and maintained.

Centralizing rules does not make them good. A shared source still needs care:

• Keep rules concise. Long instruction sets are followed less consistently.
• Remove obsolete instructions when the decision behind them changes.
• Avoid contradictions between rules, especially across levels.
• Separate permanent rules from temporary implementation notes.
• Review important changes, the same way you would review a change to code.

If your source is a file in a repository, review comes with the pull request. If it is a wiki or a dashboard, the team needs to agree on how changes are reviewed, because the tool may not enforce it.

How XOROX approaches shared team context

XOROX is an agent-independent project context layer for AI coding agents. It provides a shared place for project context and makes it available to the agents it supports, currently Cursor and Claude Code.

• Rulesets are persistent instructions such as conventions and architecture rules. They reach the agent automatically.
• Specifications are detailed project knowledge. The agent gets an index and retrieves the full text when it is relevant.
• Tasks are the implementation queue. They are separate from the rules, and can come from XOROX, GitHub, or Notion.

Rulesets are read from XOROX live, so an edit reaches the agent on a following prompt. XOROX does not provide an approval workflow or change history for Rulesets. If you want review, one option is to back a Ruleset with a file in a connected GitHub repository, so changes go through your normal pull request process and the Ruleset updates when the file changes on push. A Ruleset can also come from a Notion page. See the GitHub and Notion pages for what is read and what is not.

Rulesets and Specifications belong to one XOROX project. Workspaces with several members are part of the Pro plan; see the pricing on the home page.

Example team workflow

A five-person team works on one application. They have architecture rules, API conventions, testing requirements, and a project specification. Some developers use Cursor, others use Claude Code.

1. The project is created in XOROX.
2. The architecture rules, API conventions, and testing requirements are added as Rulesets. The project specification is added as a Specification.
3. Each developer installs the xorox command-line tool and runs xorox init in their clone, using a project credential. A project can have several credentials, so each person can have their own and one can be revoked without affecting the others.
4. Cursor or Claude Code, whichever the developer uses, receives the Rulesets and can retrieve the Specification when relevant.
5. When the team changes a convention, someone edits the Ruleset, or the file that backs it. The team maintains that one source instead of a copy per developer and per agent.

Installation, on macOS or Linux:

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

On Windows (x64), in PowerShell:

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

xorox init stores the credential in the developer's user-level configuration, not in the repository, and keeps its project files out of Git. See Quickstart for the full flow.

This does not guarantee that every developer's agent behaves identically. It means they start from the same Rulesets, and a changed Ruleset is delivered on the next prompts rather than waiting for each person to update a local file.

What should not become a shared AI rule

More context is not better context. Be wary of turning these into permanent shared rules:

• Temporary debugging instructions.
• Details of a one-off task. Put them in the task instead.
• Individual developer preferences.
• Constraints from a migration that has finished.
• Obvious, generic programming advice the model already follows.
• Anything reliably enforced by automated tooling.

If a formatter or linter fully enforces formatting, repeating every formatting rule in natural language adds noise and costs context for little gain. Keep rules for what tools cannot check: architecture, intent, and decisions.

When you don't need a shared context layer

A separate shared system may be unnecessary when:

• the team is very small,
• everyone uses the same agent,
• the project is contained in one repository,
• repository-level instructions are easy to maintain,
• the shared context rarely changes, or
• the team wants all project instructions versioned alongside the code.

In those cases, repository-level instructions are simpler. A shared, agent-independent layer becomes more useful when:

• several developers use different coding agents,
• context is duplicated across developers,
• engineering rules span multiple repositories or client projects (see the guide for agencies),
• organizational context needs to be reused,
• project knowledge needs a source independent of one agent, or
• developers regularly join or move between projects.

Summary

• Where AI coding rules are stored matters less than whether shared engineering decisions have a clear source of truth.
• Without one, rules drift between developers, repositories, and agents, and nothing signals which copy is current.
• Repository files are the simplest source and are enough for many teams. Agent-specific files add control and duplication. A shared, agent-independent layer helps when several agents, developers, or repositories need the same context.
• Any shared source needs upkeep: concise rules, no contradictions, obsolete ones removed, important changes reviewed.
• Consistent context does not mean consistent output.

XOROX provides an agent-independent place to manage shared project context when maintaining separate copies for repositories, developers, or coding agents becomes difficult. The quickstart shows how to connect one project.