The rise of Agents.md, an open standard and single source-of-truth for AI coding agents

As AI coding agents proliferate the workforce, refactoring code, writing tests, and creating new features, this gives rise to a new dilemma: how do we keep them truly aligned with how humans build software?

Agents, after all, are only as good as the instructions they’re given. Too often, these agents dig through bloated READMEs or outdated docs, guessing at build steps and coding conventions. That guesswork slows them down and makes their output unreliable.

Moreover, different AI coding platforms have created their own ways to store instructions (e.g. claude.md for Claude Code and gemini.md for Gemini CLI) which fragments guidance across multiple files. The same setup steps and style rules get duplicated in different formats, and the moment your project changes, those files drift out of sync.

Enter AGENTS.md, a collaborative effort first started by the folks at Sourcegraph, and which now includes big-name supporters including OpenAI and Google.

AGENTS.md: A shared playbook for AI coding agents

AGENTS.md is a lightweight, Markdown-based standard that serves as a common instruction file for AI coding agents. Instead of scattering the same instructions across multiple tool-specific files, projects can maintain one AGENTS.md with setup commands, build steps, code conventions, and testing workflows. Every supported agent knows to look there first.

To get started, users create an AGENTS.md at the root of their repository and structure it with clear sections for environment setup, testing, security considerations, and pull request guidelines. The key is to keep it concise, well-organized, and easy for both humans and agents to parse.

Yes, it’s much the same as existing tool-specific instruction files, except AGENTS.md is vendor-neutral, recognized across platforms, and sits alongside README.md as the one predictable place coding agents will always look.

It’s also worth noting that developers aren’t limited to a single AGENTS.md at the root. Developers can add AGENTS.md files in subdirectories (e.g. /frontend, /api); agents always use the nearest one by walking up the directory tree, so each part of a monorepo can have its own instructions.

Migrating to AGENTS.md… or not.

Those wishing to transition to AGENTS.md simply have to rename their existing agent instruction file (be it CLAUDE.md or GEMINI.md) as AGENTS.md and create a symlink for backward compatibility:

mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md

With this in place, new tools will read AGENTS.md, while older ones that still expect the old filename will keep working.

That all said, not everyone will necessarily want to migrate to AGENTS.md – for example, those only using the one AI coding tool; those who already have a robust working setup across tools; or team setups, where changing established workflows could prove a sticking point.

And then there is the Anthropic-sized elephant in the room.

For sure, a cursory glance at the list of compatible agents reveals a promising future for the standard. GitHub recently announced support for its Copilot coding agent, while OpenAI and Google also introduced formal support via their respective coding agents.

Throw into the mix Cursor, Amp, Factory, RooCode, Zed, Warp, and a host of others, then it’s clear that AGENTS.md is fast becoming the default standard for how coding agents interact with projects.

But there is one glaring absence… Claude Code.

What the community is saying about AGENTS.md

Anthropic’s Claude Code repository has been inundated with requests to support AGENTS.md, and it’s perhaps only a matter of time before it joins its rivals – after all, developers don’t want to maintain one set of instructions for Claude, and another for everything else.

"Claude.md feels too specific to Claude Code,” one user noted. “It doesn’t work as well when collaborating with other developers who aren’t using Claude Code.”

Another user suggested Anthropic could adopt a dual-file approach, defaulting to CLAUDE.md when it’s present but falling back to AGENTS.md if it isn’t. This ensures Claude Code retains its tailored features, while still working out-of-the-box on the thousands of repos that already use the open standard.

If Anthropic doesn’t add support, well, it could find itself rather isolated in the long run.

“Currently, if a developer using Claude Code clones a repository that provides an AGENTS.md file, that context is ignored,” the user wrote. “The developer must manually create a CLAUDE.md file and duplicate the instructions, creating unnecessary friction and a missed opportunity for Claude Code to be instantly effective on a new project.”

The Claude Code conundrum aside, online communities have been awash with chatter about what AGENTS.md might mean for developer workflows. But one author on the Kilo Code blog came to a particularly interesting conclusion – maybe, just maybe, AGENTS.md is less about helping AI agents and more about tricking us into writing better documentation.

“As software developers, we have a dirty secret: we don’t quite like writing documentation,” the author, going by the name of Darko, wrote. “We'll spend hours optimizing a function to save milliseconds, but ask us to write a README and suddenly we're ‘too busy’. Say hello to AGENTS.md — a documentation standard that has the potential to convince even the most documentation-averse developers to actually document their code.”

The reason, Darko argues, is that AGENTS.md is all about writing for AI coding assistants, rather than humans.

“You get immediate feedback & results – you write it once, and your AI assistant immediately becomes more useful,” Darko wrote. “The feedback loop is much longer with READMEs.”

In other words, the payoff for writing AGENTS.md comes instantly: developers can see their assistant generate cleaner code, follow project conventions, or respect architectural guidelines the very next time they invoke it. That’s a powerful incentive compared to traditional documentation, which often languishes unread or only proves useful weeks or months later when a teammate onboards.

So while vendor-specific files like CLAUDE.md or GEMINI.md may well create a similar nudge toward better docs, the arrival of a shared standard compounds the effect. What’s framed as “for the AI” ends up being good for engineering too: the same structure that improves assistants also reduces duplication, saving teams from copy-pasting the same instructions across tools.

Ultimately, this immediacy flips the psychology: instead of documentation being a chore with a distant or uncertain reward, AGENTS.md makes it a direct productivity boost.