If you've worked across a few different AI coding assistants, you've probably noticed each one seems to want its own instructions file with its own filename. CLAUDE.md for Claude Code, .cursorrules for Cursor, AGENTS.md as an emerging cross-tool convention. It's easy to assume this fragmentation is a real problem worth solving carefully. In practice, it matters far less than the content of the file itself.
What each convention actually is
CLAUDE.md is read automatically by Claude Code at the start of a session, scoped to the directory it's placed in, with support for nested files in subdirectories for more specific context. .cursorrules serves a similar function for Cursor, historically as a single file, more recently expanded to support rule directories with more granular targeting. AGENTS.md has emerged as a tool-agnostic convention that several assistants have adopted support for, aiming to reduce exactly the fragmentation this article is about.
Functionally, all three are solving the identical problem: giving an assistant persistent, automatically-loaded context about a codebase's specific conventions, without a human re-explaining it every session.
Photo by Yusuf Çelik on Pexels
Why the filename matters less than people assume
Teams sometimes spend real time debating which convention to standardize on, or maintaining near-duplicate files under multiple names to cover every tool anyone on the team might use. This is reasonable defensive engineering, but it's solving a much smaller problem than the one that actually determines whether an assistant follows your rules: whether those rules are specific, well-prioritized, and current.
A perfectly named, perfectly placed file full of vague, contradictory, or stale rules performs worse than a slightly awkwardly-named file with sharp, specific, current ones. If you're optimizing effort, spend it on the content first.
A pragmatic approach to multi-tool teams
If your team genuinely uses multiple assistants, a reasonable pattern is maintaining one canonical file with the actual rules, then using a symlink or a simple build step to generate the tool-specific filenames from that single source, rather than manually keeping three near-identical files in sync by hand. Manually-synced duplicate files are a classic source of drift, where one gets updated after an incident and the others quietly fall behind.
Some teams go simpler still: pick the tool the majority of the team actually uses, maintain that file properly, and accept that anyone on a different tool either doesn't get automatic loading or manually references the canonical file. This is a reasonable tradeoff for smaller teams where perfect multi-tool parity isn't worth the maintenance overhead.
Where nesting and scoping actually help
Beyond the top-level filename question, several of these tools support nested or scoped instructions, a root-level file with broad conventions, plus more specific files in subdirectories for context that only applies to that part of the codebase. This is worth using deliberately rather than cramming everything into one root file, since a rule that only applies to the payments module doesn't need to compete for attention in every unrelated task the assistant works on elsewhere in the codebase.
The Anthropic documentation on Claude Code covers this nested pattern directly, and it's a good example of tooling catching up to a real need, since teams were clearly already trying to scope instructions before the feature formally existed to support it cleanly.
Standardization is coming, slowly
The AGENTS.md convention specifically exists because enough people ran into this exact fragmentation problem that a shared standard started to form organically. Whether it fully consolidates the ecosystem or just becomes a fourth convention alongside the others remains to be seen, but it's a reasonable bet for teams starting fresh today who want to minimize future migration work if their tooling choices change.
Following an emerging convention like this one is lower-risk than it might seem, since the actual content, the specific rules about your codebase, transfers over regardless of what the file happens to be named or which tool reads it first.
What happens when a team switches tools mid-project
A common scenario worth planning for: a team standardized on one assistant, wrote a solid instructions file for it, then switched tools eight months later for unrelated reasons, pricing, features, team preference. If the content lived in a tool-specific format tightly coupled to one assistant's particular quirks, that migration means rewriting from scratch. If the content was written as portable, tool-agnostic rules from the start, the migration is closer to a rename and reformat, which is a meaningfully different amount of work.
This is the practical argument for writing rule content in a way that doesn't assume any particular tool's specific syntax or feature set, even if you're only using one tool today. Plain, direct, specific language about your codebase's conventions transfers cleanly regardless of which file it eventually lives in.
Version control matters more than people expect
Whatever filename convention you land on, treat the instructions file as source code, in version control, reviewed the same way a meaningful code change would be reviewed, not edited casually outside the normal process. This matters more than it might seem because the file directly shapes an assistant's behavior across the entire team, so an unreviewed change to it has a similar blast radius to an unreviewed change to a shared configuration file.
Teams that treat the file this way tend to catch problems, an overly broad new rule, an outdated reference to a removed feature, before they cause confusion across every session that reads the file afterward. Git's own documentation is a reasonable place to start if your team hasn't formalized a review process for configuration and documentation changes specifically, as opposed to application code.
A note on tooling that reads multiple formats
Some newer tooling has started supporting multiple instructions file formats simultaneously, reading whichever one is present rather than requiring a specific name. This reduces the practical cost of the fragmentation problem somewhat, though it doesn't eliminate the maintenance burden of keeping content synchronized if you genuinely need more than one file present for different tools your team uses in parallel.
Even with this kind of flexibility, the underlying advice doesn't change: pick a canonical source for the actual rule content, and treat any additional format-specific files as generated or synced from that source rather than independently maintained originals that can drift apart from each other over time.
The actual lesson here
Don't let the multi-tool filename question become a distraction from the harder and more valuable work: writing rules specific enough to be checkable, prioritized so the highest-stakes ones aren't buried, and maintained as your codebase's real conventions change. That work pays off regardless of which filename convention your team lands on, and it's the difference between an instructions file that actually shapes assistant behavior and one that exists mostly for show.
Community discussion threads on sites like the Stack Overflow engineering community occasionally rehash the filename debate at length, and it's worth reading a few of those threads once for context, then consciously deciding not to spend more of your own team's time on the question than the actual stakes justify.
For the deeper dive on what actually makes an instructions file effective once you've settled on where it lives, 137Foundry has the full breakdown covering structure, specificity, and how to keep the file from going stale as the codebase evolves.
Top comments (0)