How to keep AI coding agent rules outside your repository

AI coding agents work better when they know the project. That knowledge usually takes the form of written instructions: architecture rules, coding conventions, implementation constraints, project specifications, workflow steps, and the team knowledge that never made it into the README.

Most teams keep these instructions in the repository, and for many projects that is the right place. This guide covers when it stops being the most convenient place: when the same knowledge has to serve several repositories, agents, teams, or clients, or when the people maintaining it are not the people who own the repository.

Why AI coding rules usually live in the repository

Repository-level AI coding rules work well when the instructions belong to one codebase. The reasons are practical:

• They are version controlled. A rule change has a diff, an author, and a review, like any other change.
• They sit next to the code. A rule about the billing module can live in the same pull request as the billing change.
• Anyone can read them. A new developer clones the repository and sees what the agent has been told.
• Agents support them directly. Both Cursor and Claude Code load instruction files from the project, and both read AGENTS.md.

If you are one developer, or one team with one repository, this is enough. Nothing in the rest of this guide argues otherwise.

When repository-based rules become limiting

The limits show up when the knowledge is not really about one repository. Typical situations:

• The same engineering rules are needed in many repositories, so they get copied into each one.
• Different coding agents each want their own instruction files, so every repository carries more than one version of the same rule.
• The copies drift, because nobody updates all of them at once.
• A team wants to change a shared rule in one place and have every project pick it up.
• An agency wants to apply its own engineering practices across client repositories that it does not own.
• The reusable engineering context belongs to the agency, while the repository belongs to the client.
• When an engagement ends, the agency's access to that context should end without anyone editing the client's repository.

None of these makes repository files a bad choice. They mean that repository files are being asked to do a second job, which is sharing knowledge between repositories. For the team-level version of this problem, see how to manage shared AI coding rules across a development team.

The duplication problem

Take an agency with eight client repositories. It has shared conventions for Laravel projects, rules for API design, testing requirements, and deployment constraints. Written once, they are a few hundred lines.

To make them available to an agent in each repository, the agency copies them into all eight. On the day of the copy, everything matches.

A month later, the testing requirements change. The update goes into the repository where it was noticed, then into two more. The other five keep the old version, and nothing indicates which ones are out of date. An agent working in repository D follows rules the agency no longer holds.

This is not a failure of discipline. Copies diverge because propagating a change to every copy is manual, and nothing flags the ones that were missed.

Option 1: keep rules in each repository

This is the simplest approach and often the best one. Rules live in AGENTS.md, a CLAUDE.md, or the agent's own rules directory, and they are committed with the code.

The advantages:

• No extra infrastructure and nothing to set up.
• Fully transparent: the rules are in the same place as everything else.
• Versioned and reviewed with the code they describe.

The trade-offs:

• Rules shared across repositories are duplicated.
• Different agents may need different files, or at least imports between them.
• An update has to be repeated in every repository that carries the rule.
• Organizational knowledge ends up attached to individual repositories.

If those costs are small for you, stay here. For one repository they usually are.

Option 2: maintain separate rules for each coding agent

Some teams use each agent's native mechanisms fully: .cursor/rules for Cursor, CLAUDE.md and .claude/rules/ for Claude Code. Each agent gets context in the format it handles best, including rules scoped to particular files.

Both agents also have places for instructions that live outside a repository:

• Cursor has user rules, which apply across all of your projects, and team rules managed in the Cursor dashboard on Team and Enterprise plans.
• Claude Code reads ~/.claude/CLAUDE.md and ~/.claude/rules/ for every project on your machine. A project's .claude/rules/ can also be a symlink to a shared directory, and a CLAUDE.md can import files by path. Links and imports that point outside the project need your approval once per project.

These work well for personal preferences. They are tied to one agent and, for the user-level ones, to one person's machine. A team that uses both agents still maintains two sets, and the problem described in how to share project context between Cursor and Claude Code applies on top of the repository duplication above.

Another common workaround is a separate repository of shared standards that each project pulls in with a Git submodule or a sync script. It keeps one source, but every project still has to update to the new version, and each checkout still contains a copy.

Option 3: use an agent-independent context layer

The third approach moves the source of project knowledge out of both the repository and the agent.

An external context layer is useful when the same project or organizational knowledge needs to be shared across repositories or coding agents. The knowledge is stored once, in a system that is neither a repository nor one agent's configuration, and each agent is connected to it. A new agent means a new connection, not a rewritten rule set.

There is a limit to what this changes, and it is worth stating plainly. An external layer does not keep the rules secret. A developer who is working with the agent can see what the agent was given, and the model reads all of it. What changes is ownership, reuse, consistency, and lifecycle: who maintains the rules, how many places hold them, whether they match, and who can switch them off.

Keeping agency knowledge separate from client repositories

Agencies show the ownership problem most clearly. An agency has its own architecture conventions, testing requirements, security guidelines, and implementation patterns. The client owns the application repository.

The agency wants to use its practices on the project. Committing all of that reusable context into the client's repository has side effects: the client now holds the agency's working method, the copy stays in Git history after the engagement, and the agency has a new copy to maintain.

Keeping the two apart gives a cleaner boundary. The repository contains the client's code and the instructions that belong to that code. The agency's reusable context is held separately and supplied to the agent while the work is under way.

When the engagement ends:

• The client keeps its repository, unchanged by the agency's context.
• The agency keeps its reusable engineering context.
• Access to the external context can be revoked without touching the client's repository.

Revoking access stops future delivery. It does not recall text an agent already received in a running conversation, and it does not remove anything the client chose to copy into their own repository. The same scoping problem across many clients is covered in managing AI coding context across multiple client projects.

How XOROX approaches this

XOROX is an agent-independent project context layer for AI coding agents. It manages project context outside the repository and makes it available to the coding agents it supports, currently Cursor and Claude Code.

The context is organized as:

• Rulesets: persistent instructions such as conventions and architecture rules, delivered to the agent automatically.
• Specifications: detailed project knowledge that the agent retrieves when it is relevant.
• Tasks: the work queue, which can come from XOROX, GitHub, or Notion.

Each XOROX project has its own credentials, and a credential can be revoked on its own. A revoked credential stops working immediately. The credential is stored in your user-level configuration, not in the repository, and the files xorox init adds to the project are kept out of Git through .git/info/exclude. Tracked files are not edited unless you pass --force.

To set it up, install the xorox command-line tool. 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

Run xorox init from inside the project. It asks for the project ID and a project credential, checks them, and configures the agents it detects. See Installation and Quickstart.

Example workflow: an agency on a client project

1. The agency creates a project in XOROX for the client work.
2. It adds its Rulesets (Laravel conventions, API design, testing requirements) and a Specification for the client's deployment constraints.
3. A developer clones the client repository and runs xorox init inside it, entering the project ID and a credential created for that project.
4. When the developer starts Cursor or Claude Code in that directory, the agent receives the Rulesets and can retrieve the Specification when it applies.
5. The client repository does not carry a copy of the agency's rules. Its own committed instructions still work as before.
6. When the agency changes a convention, it edits the Ruleset in XOROX. Both agents receive the updated version on a following prompt, with no commit to the client repository.
7. At the end of the engagement, the agency revokes the project's credential. The repository stays as the client left it.

For several clients, each client project gets its own XOROX project and credential, so access can end for one without affecting the others.

When you should keep rules in the repository

External context is probably unnecessary if:

• you are one developer,
• you mainly use one coding agent,
• the rules apply to a single repository,
• you want the instructions versioned directly alongside the code, or
• duplication and ownership are not problems you actually have.

In that case, repository-level instructions are simpler and may be the better choice. There is nothing to keep running and nothing to explain to a new teammate.

An independent context layer becomes more useful when context has to span:

• multiple coding agents,
• multiple repositories,
• multiple developers,
• multiple client projects, or
• organizational rather than repository ownership.

Summary

• Keeping AI coding rules in the repository is the simplest option and is enough for a single codebase.
• It becomes limiting when the same rules are copied across repositories or agents, because the copies drift.
• An external, agent-independent context layer separates who owns and maintains the rules from where the code lives. It improves reuse, consistency, and lifecycle control. It does not hide the rules from developers or the model.
• For agencies, it keeps reusable engineering context out of client repositories, with access that can be ended without touching them.
• XOROX provides an agent-independent place to manage project context when repository-level instructions are no longer enough. If they are enough, keep them where they are.