Repo-Level AI Instructions (One File, Every Tool)

TL;DR: No filename works natively in every AI coding tool, but AGENTS.md comes closest, and Claude Code, Cursor, GitHub Copilot and Codex each read instruction files differently: some concatenate every file they find, others let the nearest one win. The practical fix is one AGENTS.md at the repo root plus a two-line bridge file for whichever tool doesn't read it directly, rather than five drifting files that say slightly different things.

What Is a Repo-Level AI Instructions File?

It's a plain-text file, sitting in your project's root (or occasionally a subdirectory), that an AI coding tool reads automatically and treats as standing context for every session, without you pasting it in each time. Build commands, coding conventions, which folders are off-limits, how to run tests: the kind of thing you'd tell a new hire on day one, except it only has to be written once and every session picks it up.

The landscape got crowded fast because every vendor shipped its own version before anyone agreed on a shared one. Anthropic's Claude Code reads CLAUDE.md. Cursor reads .cursor/rules/*.mdc files, plus a legacy .cursorrules. GitHub Copilot reads .github/copilot-instructions.md. OpenAI's Codex, along with a growing list of other tools, reads AGENTS.md. If you work across two or three of these in the same repo, you either maintain overlapping files by hand or you pick a pattern that survives the differences. This post is about the second option.

Is There One File Every AI Tool Reads?

Not one filename, no, but the coverage isn't even. Here's what each tool actually reads, verified against that tool's own documentation rather than the adoption claims a spec site makes about it:

The one row that actually surprises people is Claude Code's. Its own documentation is direct about it: "Claude Code reads CLAUDE.md, not AGENTS.md." No hedging, no "primarily." If your repo already has an AGENTS.md for Codex or Cursor and you add Claude Code to the mix, it will not pick that file up on its own.

Does AGENTS.md Actually Work Across Every Tool?

It's the closest thing to a shared standard, but "closest" still leaves real gaps. AGENTS.md's own tagline states it plainly: "A simple, open format for guiding coding agents, used by over 60k open-source projects." The site also states it's "now stewarded by the Agentic AI Foundation under the Linux Foundation" — that's a real governance change worth noting, not a marketing line, since a format with a neutral steward behaves differently over time than one owned by a single vendor. The 60k figure is the format's own adoption claim, not an independently audited count, so treat it the same way as the vendor-support list below: stated by the site, not verified by this post.

Coverage splits into three tiers, and conflating them is where most "AGENTS.md just works everywhere" claims go wrong:

• Native, confirmed on the vendor's own docs: OpenAI Codex, Cursor (root and nested directories), Zed, Warp, opencode, Amp, Factory, VS Code (subfolder support marked experimental), and Google Jules.
• Configurable, not native: Gemini CLI doesn't read AGENTS.md by default, since its own settings reference names GEMINI.md. The AGENTS.md site's own FAQ gives the fix directly: point .gemini/settings.json at it with { "context": { "fileName": "AGENTS.md" } }. Aider is similar, with no native support, but a .aider.conf.yml line (read: AGENTS.md) makes it read the file as a generic instructions source.
• Claimed on the spec site, not verified on the vendor's own pages: Devin, goose, Junie, RooCode, Kilo Code, Windsurf, Augment Code and several others appear on AGENTS.md's own adopter list. That list is the format's own marketing, not each vendor's documentation, so treat it as claimed until you check the tool you actually use.

None of that reaches Claude Code, which sits outside the standard entirely by its own admission.

What Happens When Two Instruction Files Disagree?

This is where the tools genuinely diverge, and it's the part a "just add both files" post usually skips. Two different resolution models are both live today, and assuming the wrong one is how a rule silently gets ignored.

Claude Code concatenates, it doesn't override. Its docs are explicit: "All discovered files are concatenated into context rather than overriding each other." A managed policy file, a user file at ~/.claude/CLAUDE.md, and a project CLAUDE.md all end up in context together, ordered from broadest scope to most specific, with a project instruction appearing after a user instruction rather than replacing it.

AGENTS.md-based nesting works the other way. For a monorepo with a package-level AGENTS.md next to a root-level one, the spec's own FAQ states the rule directly: "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." Not concatenated, not merged: the nearer file simply takes precedence, unless you've said something explicit in chat that contradicts it.

Cursor complicates this further by giving CLAUDE.md special treatment inside Cursor itself. Its help documentation states that "CLAUDE.md files are always applied to every conversation, regardless of any alwaysApply frontmatter setting" — a CLAUDE.md file sitting in a Cursor project behaves like an always-on rule, bypassing the conditional logic that governs Cursor's own .mdc rules.

If your team runs more than one of these tools against the same repo, write down which resolution model applies before you're debugging why a rule silently didn't fire. Guessing costs more time than the ten minutes it takes to check.

Does Claude Code Read AGENTS.md?

No, and it's worth stating exactly why rather than just the fact. Claude Code's own memory documentation gives the bridge directly, in its own words: "If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them." The mechanism is a one-line import at the top of CLAUDE.md:

@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

A symlink works too, for teams that don't need Claude-specific additions:

ln -s AGENTS.md CLAUDE.md

There's a second bridge worth knowing about, and it goes the other direction. Running /init in Claude Code doesn't just scaffold a blank file. Its docs state it "reads Cursor rules, in .cursor/rules/ or .cursorrules, and Copilot rules, in .github/copilot-instructions.md, and incorporates the relevant parts into the generated CLAUDE.md." With the CLAUDE_CODE_NEW_INIT=1 environment variable set, /init also reads AGENTS.md itself, plus .devin/rules/, .windsurf/rules/ (or .windsurfrules), and .clinerules. If you've already written instructions for one tool, /init is genuinely faster than retyping them for Claude Code by hand.

How Do I Write One Instructions File That Works Everywhere?

Given the coverage table above, the pattern that actually holds up is: write AGENTS.md as the base, then add the thinnest possible bridge for whichever tool doesn't read it natively.

1. Write AGENTS.md at the repo root. It's read natively by the widest confirmed set of tools: Codex, Cursor, Zed, Warp, opencode, Amp, Factory and VS Code, with no configuration on your end.
2. Bridge Claude Code with a one-line import, as shown above. It's the only major coding tool in this list that needs one.
3. Bridge Gemini CLI and Aider with their documented config lines if your team uses either: a .gemini/settings.json entry or a .aider.conf.yml read: line, both one line, both shown above.
4. For monorepos, nest a package-level AGENTS.md next to the shared root one, and remember the closest-file-wins rule from the section above — don't assume the root file is a fallback that always applies.
5. Keep Cursor-specific behavior in .cursor/rules/*.mdc, not in AGENTS.md, if you need path-scoped globs or an alwaysApply: false rule that only fires on certain files. AGENTS.md has no frontmatter to scope it that way. Cursor Rules and Prompt Templates has copy-paste .mdc files if you're setting that up from scratch.

For the full mechanics of any one tool, the deep dive already exists: The AGENTS.md Standard Explained covers precedence and vendor support in more depth than fits here.

What Actually Belongs in the File?

Whichever filename you land on, the content discipline is the same, and it's the part people skip because writing more instructions feels like it can only help. It doesn't. Claude Code's own best-practices docs put it about as bluntly as a vendor ever does: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"

Keep entries to things Claude, Codex or Cursor genuinely can't derive from reading the code itself: which package manager the team actually uses, a build quirk that isn't in any README, a folder that looks safe to touch but isn't. Skip anything the tool would find by opening a file. That's the difference between a file that gets read carefully and one that gets skimmed past.

Is Auto Memory the Same Thing as CLAUDE.md?

No, and this is new enough that it's worth being precise about the distinction rather than lumping it in with instruction files. Claude Code now ships a second, separate mechanism called Auto Memory, and it works the opposite way round from everything above: you don't write it, Claude does. Its own docs describe the split cleanly — "Who writes it" is you for CLAUDE.md files and Claude itself for Auto Memory, with Claude saving "four kinds of notes for itself": a user's role and preferences, corrections and confirmed approaches, ongoing project context the code itself doesn't show, and pointers to information that lives outside the repo entirely.

Those notes land in a MEMORY.md index plus separate topic files, and only the index is loaded automatically — capped at 200 lines or 25KB, whichever is smaller, at the start of every session. It's genuinely useful as a backstop for the correction you gave Claude last week that never made it into any file, but it isn't a substitute for CLAUDE.md, and as far as the vendor docs checked for this post show, no other tool in this comparison has shipped an equivalent yet. Treat it as a Claude Code feature, not a second cross-tool standard to plan around.

Repo-level instructions and runtime parameters get confused often enough to flag directly: a CLAUDE.md or AGENTS.md file shapes behavior and context, not sampling settings like temperature or top-p. The LLM Parameter Cheat Sheet covers those separately, since they live in the API call, not the repo.

Writing One Prompt That Survives Every Vendor Isn't New

If this whole exercise feels like writing one instruction set and hoping five different readers interpret it consistently, that's because it is exactly that problem, just at the repo level instead of the single-prompt level. Background Replacement Prompting: A Prompt for Every Tool runs into the identical translation problem for image prompts across models that don't share syntax. The fix is the same shape in both cases: write the portable version once, then keep the per-vendor differences in the smallest possible adapter, instead of maintaining full copies that quietly drift apart.