168 Upvotes for One Line of Code: The Fight Over What to Name Your AI Config File
Open a modern project root and you might find CLAUDE.md, AGENTS.md, .cursorrules, and .github/copilot-instructions.md sitting side by side. The contents are nearly identical. The files are not. If you use more than one AI coding agent — and most working developers now do — this is your Tuesday. That low-grade annoyance has accumulated into a GitHub issue with 168 upvotes, and the request is smaller than you’d expect.
One caveat up front: there hasn’t been a fresh wave of discussion on this in the last 30 days. What follows is built on the structure of the standard itself and the arguments that have piled up over time, not a snapshot of today’s discourse temperature.
What AGENTS.md Actually Is
It’s a markdown file that tells an AI coding agent how your project works. Build commands. How to run tests. Code style rules. Commit message conventions. Think of it as the README for machines, sitting next to the README for humans.
The format is the boring part. There’s no schema, no required fields, no validation step — it’s plain markdown. The only thing anyone agreed on is the filename: AGENTS.md. That sounds like nothing. That nothing is precisely the point.
Around that one name, a coalition formed: OpenAI’s Codex, Cursor, the JetBrains tooling, Devin. Tens of thousands of open source repositories already ship the file. It became the de facto standard the way standards usually do — quietly, by adoption rather than announcement.
Anthropic’s Case for CLAUDE.md
Claude Code reads CLAUDE.md from the project root. It also walks up the directory tree to pick up parent CLAUDE.md files, and reads a global one from your home directory. The @path syntax pulls in other files by reference. Drop a separate CLAUDE.md into a subdirectory and it loads only when you’re working in that scope.
So CLAUDE.md isn’t just a different name on the same idea. Hierarchy, imports, scoped loading — it’s a distinct feature set. Anthropic has a defensible line here: we do more than AGENTS.md specifies.
The counterargument is at least as strong, and it’s the reason those 168 votes exist. None of those features have anything to do with the filename. You can read AGENTS.md and still support hierarchical loading and imports. Technically, there is no reason the name has to carry the functionality. The name is doing no work.
The Symlink Workaround, and Why It’s Ugly
Developers already route around this. The most common fix is a symlink:
ln -s AGENTS.md CLAUDE.md
AGENTS.md stays the source of truth; CLAUDE.md becomes a pointer. Claude Code's own documentation mentions the approach. It works. It also has sharp edges.
On Windows, creating a symlink requires Developer Mode or administrator privileges. Depending on your Git config, the link can get committed as a plain text file containing a path — a bug that surfaces weeks later on someone else's machine. And eventually a new hire clones the repo and asks why CLAUDE.md has a little arrow next to it. **A solution that requires an explanation isn't a good solution.**
The other workaround is worse: put a single line inside CLAUDE.md saying "please read AGENTS.md." Now whether your configuration loads depends on whether the model chooses to follow an instruction. Configuration files should not be probabilistic.
## Lock-In, or Just Bad Timing?
This is where the argument splits.
The hard-line reading: branding the filename is a retention strategy. Put CLAUDE.md in a repo and you've added friction to switching agents. Small friction, multiplied across every project, is a moat.
The charitable reading: CLAUDE.md predates the AGENTS.md convention. Adopting a name that arrived later means migrating every existing user's file, and shipping a breaking change to a config surface that already works. It's a **timing problem**, not a conspiracy.
Honestly, litigating intent isn't productive. What matters is the outcome. Right now developers maintain the same content twice, and when someone updates only one copy, two agents start writing code against two different rulebooks. Whatever the intent, the user pays the cost.
Supporting both isn't zero-sum, either. Read AGENTS.md. Read CLAUDE.md. If both exist, prefer CLAUDE.md or merge them — pick a rule and document it. The actual ask in that issue was never "kill CLAUDE.md." It was "**also read AGENTS.md**." The people upvoting it think this is a fallback branch, not a roadmap item.
## What This Argument Is Really About
It looks like bikeshedding over a filename. The question underneath is whether the AI coding agent ecosystem ends up **portable**.
Today, switching tools means rewriting your configuration and rebuilding your prompting instincts from scratch. If that hardens, developers stop choosing tools and start choosing camps. Web development went through this — the browser wars, then convergence on standards, then an explosion of tooling built on top of the shared layer. AI agents will get there. The open question is how many years of duplicated config files we burn on the way.
A filename is trivial. But standards almost always start from trivial agreements. `package.json` was trivial. `.gitignore` was trivial. Once the name converged, an entire tooling ecosystem stacked on top of it. That's the whole mechanism.
## One Fallback Branch
168 votes is not a large number in absolute terms. For a feature request that amounts to "please standardize a filename," it's a meaningful signal. If Anthropic ships the fallback, it's roughly a day of work. If it doesn't, that's an answer too — just a slower one.
So: how many agent config files are in your project root right now? How many of them say the same thing? It's worth counting. Those 168 votes came from people who already did.
Comments
Loading comments...