How to Share One Instruction File Across Coding Agents

The drift problem

A repository used by one coding agent usually has one instruction file. Add a second agent and a second file appears. Add an editor with its own rules format and there is a third. Each starts as a copy of the others. Within weeks they disagree: the test command changed in one, a new constraint was added to another, and the third still describes a folder layout from last quarter.

The result is subtle. Two developers ask two agents for the same change and get different conventions, because each agent read a different version of the truth. Nobody notices until review, if then.

AGENTS.md and CLAUDE.md

AGENTS.md is a plain markdown convention for agent instructions, adopted by a growing list of coding agents and editors. It holds the same kind of content as a README for machines: build and test commands, conventions, and constraints.

CLAUDE.md is the file Claude Code loads natively as project memory. It supports importing other files with an at-sign path reference, which is what makes sharing straightforward.

Whether a given version of a given tool reads AGENTS.md directly has changed over time and is still changing. That is the reason to design for portability rather than rely on any one tool's current behaviour.

Where Claude Code stands now. Current versions read a repository's AGENTS.md natively, but as a fallback: when a CLAUDE.md exists in the directory or any parent, that file wins and AGENTS.md is not loaded automatically. So a repository carrying both still needs the import, which is why the pattern below survives the discovery rules changing again.

Three ways to keep one source of truth

Pick the simplest one your tools support.

Verify that each agent actually reads it

Do not assume. Put a harmless, distinctive instruction in the canonical file, such as a specific phrase to include when asked for the project's test command, then ask each agent. If one does not respond as expected, it is not loading the file, or not loading it in that mode.

Repeat the check after tool upgrades. File discovery rules, settings that gate loading, and precedence between global and project files all change between releases, and a silent change means an agent quietly working without your constraints.

Global, project, and folder files

Most agents read instruction files at more than one level. A global file in your home directory applies to every project. A project file at the repository root applies to that repository. Some tools also read files in subfolders, which suits monorepos where each package has its own commands.

The sharing approach should respect those levels. Personal preferences, such as how terse responses should be, belong in each person's global file for each tool, not in the shared repository file. Package-specific commands belong in that package's folder file, imported or linked the same way as the root file.

The common mistake is putting everything at the root. A monorepo root file that lists commands for twelve packages is long, expensive on every request, and still wrong for most tasks. Split by folder, keep each file to what applies there, and let the agent load the one that matches where it is working.

What belongs in the shared file

Everything in an instruction file is sent on every request, to every agent. Keep it to what agents cannot infer from the code: commands that actually work, conventions the code does not reveal, and hard constraints with consequences.

Architecture explanations, decision history, API references, and onboarding material do not belong there. They make the file long, expensive, and stale. Put them in a vault or docs folder, index it, and connect it to every agent through an MCP server. Each agent then retrieves the relevant chunk when the task needs it, and all of them draw from the same source, which solves the drift problem for deep knowledge the same way one canonical file solves it for rules.