CLAUDE.md, AGENTS.md and .cursorrules: One Config Strategy

Most enterprise development teams I work with now run more than one AI coding agent. The platform team standardized on Claude Code, the front-end team pays for Cursor, everyone has GitHub Copilot through the organization’s GitHub Enterprise agreement, someone is queuing background tasks in Codex, and the data team has Gemini CLI on half its laptops. Each tool reads its own instruction file, and each file was written by whoever adopted that tool first. Six months later the build command in CLAUDE.md is wrong, .cursorrules still bans a library the team now depends on, and nobody can say which file is authoritative. This guide lays out a single configuration strategy for that situation: one vendor-neutral source of truth in AGENTS.md, thin tool-specific adapters around it, clear rules for what has to stay tool-specific, and the governance that keeps the files honest. Every claim about what a tool reads is checked against that vendor’s current documentation and linked inline.

The problem: five tools, five files, drift

An instruction file is the onboarding document you hand a new engineer, except the engineer reads it at the start of every single session and never pushes back when it is wrong. That makes drift expensive in a way documentation drift never was. A stale README.md wastes a new hire’s afternoon once. A stale instruction file sends every agent session in the repository down the same wrong path, and because each tool has its own file, the drift is uneven: Claude Code might know about the new test runner while Copilot still runs the old one.

I covered the two most common files on their own in the CLAUDE.md guide for enterprise teams and the AGENTS.md guide for enterprise AI coding. Those posts explain what goes inside each file. This one sits above them and answers the question that keeps arriving in search queries and discovery calls: when a team runs several agents, which file wins, and how do you stop maintaining five copies of the same rules?

The short answer is that you do not maintain five copies. You maintain one, and you understand exactly how each tool consumes it.

What each tool reads

The table below is the reference I wish I had when I started untangling this. It is built from each vendor’s current documentation, and the per-tool sections after it carry the details and the links.

Claude Code: CLAUDE.md and its layers

Claude Code’s memory documentation lists four scopes in load order: a managed policy file deployed by IT (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows), the user file at ~/.claude/CLAUDE.md, the project file at ./CLAUDE.md or ./.claude/CLAUDE.md, and a gitignored ./CLAUDE.local.md for personal notes. Claude loads CLAUDE.md files from the working directory and every directory above it at launch, concatenates them from the filesystem root downward so the closest file is read last, and loads subdirectory files only when it reads, writes or edits a file in that subdirectory.

Three details matter for a shared strategy. First, the @path/to/file import syntax pulls another file into context, resolves relative to the file that contains the import, and can nest four hops deep; imports inside code spans and fenced blocks are ignored. Second, Anthropic’s guidance is to target under 200 lines per CLAUDE.md file, and imports do not reduce that cost because imported files load with the file that imports them. Third, .claude/rules/*.md files load alongside the project CLAUDE.md, and a paths: frontmatter field scopes a rule to matching files so it loads only when Claude works on them. If you want the layer-by-layer picture of a Claude Code repository, including skills and hooks, read The Anatomy of a Claude Code Project.

OpenAI Codex: AGENTS.md with an override file

Codex is the tool the format was built for, and its AGENTS.md documentation is the most precise description of nesting I found. Codex looks first in its home directory (~/.codex, or CODEX_HOME), where it uses only the first non-empty file, preferring AGENTS.override.md to AGENTS.md. It then starts at the project root, usually the Git root, and walks down to the current directory, taking at most one file per directory in the order AGENTS.override.md, AGENTS.md, then any names listed in project_doc_fallback_filenames. The files are joined from the root downward separated by blank lines, so instructions nearer your working directory appear later in the prompt and take precedence.

The limit most teams miss: project_doc_max_bytes caps the combined size at 32 KiB by default, and Codex stops adding files once the chain reaches that limit. A bloated root file can silently push a package-level file out of context.

GitHub Copilot: three kinds of instruction file

GitHub’s documentation on repository custom instructions describes a repository-wide .github/copilot-instructions.md, path-specific NAME.instructions.md files under .github/instructions/ with an applyTo glob in frontmatter (and an optional excludeAgent of code-review or cloud-agent), and agent instruction files: AGENTS.md anywhere in the repository, with the nearest file taking precedence, or a single CLAUDE.md or GEMINI.md at the root. When a path-specific file matches and a repository-wide file also exists, both are used. Across sources, personal instructions rank above repository instructions, which rank above organization instructions, but all relevant sets are provided to the model, so GitHub’s advice is to avoid contradictions rather than rely on ranking.

The catch is the support matrix. Copilot cloud agent, Copilot code review on GitHub.com, Copilot Chat in VS Code and Copilot CLI read AGENTS.md. Copilot Chat on GitHub.com, in Visual Studio and in JetBrains IDEs reads .github/copilot-instructions.md but not AGENTS.md. Copilot code review also reads instructions from the pull request’s head branch, not the base branch, which matters when you change the files in the same PR.

Cursor: .cursor/rules and AGENTS.md

Cursor’s rules documentation describes project rules as .mdc files under .cursor/rules/ (a plain .md there is ignored because it has no frontmatter) with three frontmatter fields: alwaysApply: true puts the rule in every chat, globs attaches it when a matching file is in context, and description alone lets the agent decide whether to pull it in. Rules merge in the order Team Rules, Project Rules, User Rules, with the earlier source winning on conflict. Team Rules are managed from the Cursor dashboard on Team and Enterprise plans and can be enforced so users cannot disable them. Cursor also asks you to keep rules under 500 lines and warns that a file referenced from a rule is not inlined; the agent reads it with its tools only when it decides to.

AGENTS.md is documented as a plain-Markdown alternative to .cursor/rules for straightforward cases, supported in the project root and in subdirectories, with nested instructions combined with their parents and the more specific file taking precedence. The single .cursorrules file that older guides describe does not appear on the current rules page at all. Treat it as legacy and migrate.

Gemini CLI: GEMINI.md, renamable

Gemini CLI’s context file documentation describes a global ~/.gemini/GEMINI.md, GEMINI.md files found in the configured workspace directories and their parents, and just-in-time loading of files from any directory a tool touches, up to a trusted root. Everything found is concatenated and sent with each prompt. @file.md imports are supported with relative and absolute paths. The feature that matters here is context.fileName in settings.json, which takes a single name or a list, and the documentation’s own example is ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]. /memory show prints the combined context and /memory reload re-scans the files.

Windsurf: rules with character limits

Windsurf’s rules documentation now lives under Devin Desktop, with .devin/rules/*.md preferred and .windsurf/rules/*.md kept as a fallback; the legacy single-file .windsurfrules is still read. Each rule file carries a trigger of always_on, glob, model_decision or manual. The global rules file is limited to 6,000 characters and each workspace rule file to 12,000 characters, which is the tightest documented limit of any tool here. AGENTS.md is supported in any directory: a root file is always on and subdirectory files are automatically glob-scoped to their directory. In Git repositories the search also walks up to the Git root, and enterprise IT can deploy read-only system rules.

The one-source strategy: AGENTS.md plus thin adapters

Why AGENTS.md is the source of truth

The AGENTS.md specification is plain Markdown with no required fields, stewarded by the Agentic AI Foundation under the Linux Foundation, and it lists Codex, Cursor, Gemini CLI, Windsurf, GitHub Copilot’s coding agent, VS Code, Zed, JetBrains Junie, Devin, Aider, Factory and others among its supporters, with more than 60,000 open-source projects using it. It is the only file in the comparison table that every tool either reads natively or can be configured to read. Nothing else comes close: CLAUDE.md is read by Claude Code and, at the root only, by some Copilot surfaces; GEMINI.md by Gemini CLI and those same Copilot surfaces; .cursor/rules by Cursor alone.

So the shared conventions go in AGENTS.md, and every other file becomes an adapter: either a thin stub that holds tool-specific instructions and pulls in the shared file, or a generated copy that CI keeps in sync.

Claude Code: import, do not duplicate

The trap here is the default. Anthropic’s documentation states that Claude reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. A repository that has both files, because someone added a CLAUDE.md for Claude-specific notes, silently stops loading AGENTS.md in Claude Code. The documented fix is to make @AGENTS.md the first line of CLAUDE.md; Claude reads the imported file first and then the Claude-specific content below it, and the documentation confirms the import never causes a double read.

A symlink (ln -s AGENTS.md CLAUDE.md) also works, but Anthropic warns against it when anyone clones on Windows, where creating a symlink needs Administrator privileges or Developer Mode and Git checks a committed symlink out as a one-line text file unless core.symlinks is enabled. Most of my clients have at least one Windows developer, so I use the import. There is also a Project instructions setting with a claude-md-and-agents-md value, but it is honoured only from user, --settings or managed settings and ignored in project and local settings, so you cannot commit it to the repository. The import is the portable answer.

GitHub Copilot: generate, do not point

For the Copilot surfaces that read AGENTS.md, you are done. For Copilot Chat on GitHub.com, Visual Studio and JetBrains, the only repository file that loads is .github/copilot-instructions.md. Writing “read AGENTS.md” in that file relies on the model deciding to open it, the same weakness Anthropic calls out for a CLAUDE.md that tells Claude in words to read AGENTS.md. The reliable pattern is to generate .github/copilot-instructions.md from AGENTS.md in CI, with a header that says it is generated, and a check that fails the pipeline when the two diverge. Path-specific Copilot behaviour, such as rules that apply only to **/*.sql, goes in .github/instructions/*.instructions.md, which has no equivalent in the shared file.

Cursor, Gemini CLI, Codex and Windsurf

Cursor reads root and nested AGENTS.md natively, so .cursor/rules shrinks to Cursor-specific, glob-scoped behaviour and anything your admins enforce through Team Rules. Gemini CLI needs one committed line of configuration, context.fileName set to ["AGENTS.md", "GEMINI.md"] in .gemini/settings.json, after which GEMINI.md holds only Gemini-specific instructions. Codex and Windsurf read the shared file without configuration; for Codex, keep the chain under 32 KiB and use AGENTS.override.md only for temporary local overrides, and if you use Codex for GitHub code review, add a ## Code Review Rules section to the AGENTS.md closest to the code it governs, which is the mechanism OpenAI documents.

What cannot be shared

Instruction files are prose for the model. Everything that is enforced by the tool rather than suggested to the model stays in that tool’s own configuration, and it is different for every tool:

Anthropic’s memory page says it plainly: Claude treats CLAUDE.md as context, not enforced configuration, and to block an action regardless of what the model decides you use a PreToolUse hook or a permissions.deny rule. The same is true of every file in this guide. Write the rule in AGENTS.md so every agent knows it, then enforce the ones that matter in the tool’s settings and in CI.

Monorepo precedence: root versus package-level files

Every tool in the table supports a root file plus nested files, and every tool merges them slightly differently. This is where a shared AGENTS.md strategy either holds up or falls apart.

Two rules fall out of that table. First, write every nested AGENTS.md so it is correct whether or not the root is also in context. Copilot’s documentation does not promise a merge, Codex may truncate, and Claude Code loads the nested file only when the agent actually touches that directory. Repeat the one or two boundaries that would be catastrophic to miss, and never contradict the root; Anthropic’s advice that the model “may pick one arbitrarily” when instructions conflict applies to every agent. Second, keep the root short. Anthropic’s 200-line target and Codex’s 32 KiB cap are the two numbers that bound your design, and a root file that stays under roughly 10 KB leaves room for two or three package files before Codex starts dropping them.

For teams with dozens of packages, Claude Code’s large codebase guidance recommends a two-level split, root plus one file per package, each maintained by that package’s owner, with claudeMdExcludes for packages you never work in. That ownership model maps directly onto nested AGENTS.md files for every other tool.

What belongs in the shared file versus tool-specific files

The test I apply to every line: if a developer switched tools tomorrow, would this instruction still be true? If yes, it belongs in AGENTS.md. If it only makes sense inside one product, it belongs in that product’s file.

Governance: ownership, review, versioning, secrets, testing

Ownership. Add AGENTS.md, the adapter files and the sync script to CODEOWNERS, with the platform or developer-experience team as owner of the root and each package team as owner of its nested file. Anthropic’s monorepo guidance makes the same recommendation for per-directory CLAUDE.md files: each directory’s owner maintains its file.

Review. Every change to an instruction file goes through a pull request like code. Claude Code gives you a helper here: /doctor prompt-audit (v2.1.283 or later) checks CLAUDE.md, CLAUDE.local.md and AGENTS.md files plus rules and skills for references to files or commands that do not exist, instructions written for older models, and files that contradict each other, and proposes edits without changing anything until you accept. Run it before you merge a change to the shared file, even if Claude Code is not the tool that prompted the change.

Versioning. The files live in Git, so they are versioned. What teams forget is to version the generated copies deliberately: commit .github/copilot-instructions.md and let CI fail when it is out of date, rather than regenerating it silently at build time where nobody sees the diff.

Secrets. Never. These files are injected into model context by every tool on every developer’s machine, sent to whichever vendor that tool calls, and copied by generators. A connection string in AGENTS.md is a connection string in five vendors’ request logs. The personal files, CLAUDE.local.md and ~/.codex/AGENTS.override.md, are gitignored but still go into context, so they are not a place for secrets either. Point agents at the environment or a secret manager, and back the rule with enforcement: a Claude Code permissions.deny rule such as Read(./.env) blocks the read regardless of what the model intends.

Testing the instructions. Treat a change to the shared file like a change to a build script and smoke-test it in each tool. Confirm loading first: /context in Claude Code lists the files under Memory files, /memory show in Gemini CLI prints the combined context, Copilot Chat on GitHub.com lists .github/copilot-instructions.md in its References when it used the file, and OpenAI suggests codex -c log_dir=./.codex-log to write a log you can audit. Then run a fixed set of prompts (“what command runs the tests?”, “where do database queries belong?”) and compare the answers across tools. A disagreement is drift you caught before a developer did.

Templates

A short, realistic set you can copy. The repository is a fictional payments platform; replace the specifics.

AGENTS.md (the source of truth)

# AGENTS.md: Payments Platform

## Project
Node 22 / TypeScript 5.6 monorepo using pnpm workspaces.
Services live under `services/`, shared libraries under `packages/`.

## Commands
- Install: `pnpm install --frozen-lockfile`
- Build: `pnpm -r build`
- Test: `pnpm -r test` (run before every commit)
- Lint and format check: `pnpm lint && pnpm format:check`

## Conventions
- TypeScript strict mode. No `any` without a comment explaining why.
- Database access goes through `packages/db`. No raw SQL in route handlers.
- Commit subjects: `<package>: <imperative summary>`, for example `api: add idempotency keys`.

## Boundaries
- Never edit files under `**/generated/`. Run `pnpm codegen` instead.
- Never modify a migration that has merged. Add a new one.
- Never commit secrets or `.env*` files. Configuration comes from the environment.
- Changes under `services/payments/` require a human reviewer from the payments team.

## Pull requests
- Title format: `[<package>] <summary>`. Run lint and tests before opening the PR.

## Code Review Rules
- Flag any new dependency without a justification in the PR description.
- Flag raw SQL strings outside `packages/db`.

CLAUDE.md (thin adapter)

@AGENTS.md

## Claude Code

- Use plan mode for any change under `services/payments/`.
- Permissions, hooks and MCP servers are configured in `.claude/settings.json`. Do not duplicate them here.

.cursor/rules/testing.mdc (Cursor-specific, glob-scoped)

---
description: Testing conventions for the payments monorepo
globs: "**/*.test.ts"
alwaysApply: false
---

- Use Vitest. Never add Jest.
- Wrap database tests in a transaction that rolls back.
- Shared project rules live in AGENTS.md; this file holds Cursor-specific behaviour only.

.gemini/settings.json (point Gemini CLI at the shared file)

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

scripts/sync-agent-instructions.sh (generate the Copilot copy)

#!/usr/bin/env bash
set -euo pipefail
{
  echo "<!-- GENERATED from AGENTS.md. Edit AGENTS.md and run scripts/sync-agent-instructions.sh. -->"
  cat AGENTS.md
} > .github/copilot-instructions.md
# In CI, fail when the committed copy is out of date:
git diff --exit-code -- .github/copilot-instructions.md

Rollout plan for a team

1. Week 1: inventory. List every instruction file in every repository, for example with git ls-files | grep -Ei 'claude\.md|agents\.md|cursorrules|cursor/rules|copilot-instructions|instructions\.md|gemini\.md|windsurf'. Record who wrote each one and when it last changed. Pick one actively developed repository as the pilot.
2. Week 2: consolidate. Merge the pilot’s files into one AGENTS.md using the “would this be true in any tool?” test. Claude Code’s /init reads existing Cursor and Copilot files and, with CLAUDE_CODE_NEW_INIT=1 set, AGENTS.md, Windsurf and Cline files as well, and proposes a consolidated draft; use it as a starting point, not the result. Write the thin CLAUDE.md, the Gemini setting and the Copilot sync script. Delete .cursorrules and any duplicated prose.
3. Week 3: pilot. Three to five developers who between them use every tool the team has. Each runs the loading checks and the fixed prompt set, then works normally for a week and logs every instruction the agents ignored or got wrong. Fix the file, not the developer.
4. Week 4: institutionalize. Add CODEOWNERS entries, the CI sync check and a repository template. Decide what moves to the organization layer: Claude Code’s managed CLAUDE.md and managed settings, Cursor Team Rules, Copilot organization instructions and Windsurf system rules are where rules that must apply to every repository belong. Then roll the pattern to the next repositories, one pull request each.

What to do about it

1. Inventory every instruction file across your repositories and name an owner for each.
2. Create a root AGENTS.md that holds commands, layout, conventions, boundaries, security rules and PR conventions, and keep it under 200 lines.
3. If a CLAUDE.md exists, make @AGENTS.md its first line and move everything that is not Claude-specific out of it.
4. Set context.fileName to include AGENTS.md in a committed .gemini/settings.json if anyone uses Gemini CLI.
5. Generate .github/copilot-instructions.md from AGENTS.md and add a CI check that fails when it is stale.
6. Delete .cursorrules; keep .cursor/rules/*.mdc for glob-scoped, Cursor-only behaviour.
7. Add nested AGENTS.md files per package, self-contained, never contradicting the root, with the critical boundaries repeated.
8. Move permissions, hooks and MCP registrations into each tool’s settings and enforce the rules that matter with deny rules and CI.
9. Search every instruction file for secrets, remove them, and add a deny rule for .env reads.
10. Add the files to CODEOWNERS, run /doctor prompt-audit before merging changes, and smoke-test each tool after every change.

Frequently asked questions

What is the difference between AGENTS.md and CLAUDE.md? AGENTS.md is the vendor-neutral file stewarded by the Agentic AI Foundation under the Linux Foundation and read by Codex, Cursor, Copilot’s agents, Gemini CLI and Windsurf. CLAUDE.md is Claude Code’s own file, with @path imports, a managed policy layer, CLAUDE.local.md and path-scoped rules the shared format does not have. Shared conventions go in AGENTS.md; a short CLAUDE.md imports it and adds Claude-specific instructions.

Does Claude Code read AGENTS.md? Yes, from v2.1.277, but only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above it. With both files present it reads only CLAUDE.md unless Project instructions is set to claude-md-and-agents-md. The portable fix is an @AGENTS.md import on the first line of CLAUDE.md.

Should I use .cursorrules or .cursor/rules? Use .cursor/rules/*.mdc or a plain AGENTS.md. Cursor’s current documentation covers .mdc project rules, Team Rules and AGENTS.md in the root and subdirectories; it no longer documents .cursorrules.

Does GitHub Copilot read AGENTS.md? Copilot cloud agent, code review on GitHub.com, Copilot Chat in VS Code and Copilot CLI do. Copilot Chat on GitHub.com, in Visual Studio and in JetBrains IDEs does not and relies on .github/copilot-instructions.md, so generate that file from AGENTS.md.

How do nested AGENTS.md files work in a monorepo? The specification says the closest file wins and explicit prompts override everything. Codex concatenates root-down with nearer files stronger and stops at 32 KiB by default; Cursor combines nested files with parents; Windsurf auto-scopes them by glob; Copilot applies the nearest file. Write nested files so they never contradict the root.

If your team is also packaging reusable agent behaviour rather than just instructions, the gh skill GitHub CLI guide covers how skills are installed and pinned across Copilot, Claude Code, Cursor, Codex and Gemini CLI; the same one-source discipline applies.

Need a second pair of hands? Big Hat Group provides application development consulting for organizations in the United States and Canada, from a two-week AI coding agent configuration review to a full multi-agent rollout across your repositories. Book a discovery call to talk through your environment.

Sources

• How Claude remembers your project (CLAUDE.md, imports, rules, AGENTS.md), Claude Code documentation
• Settings files and precedence, Claude Code documentation
• Set up Claude Code in a monorepo or large codebase, Claude Code documentation
• AGENTS.md specification, Agentic AI Foundation
• Custom instructions with AGENTS.md, OpenAI Codex documentation
• Adding repository custom instructions for GitHub Copilot, GitHub Docs
• Support for custom instructions in GitHub Copilot, GitHub Docs
• Rules, Cursor documentation
• Provide context with GEMINI.md files, Gemini CLI documentation
• Rules and memories, Devin Desktop (Windsurf) documentation