AGENTS.md: A Standard for AI Coding Agents
If you’re using AI coding agents—and who isn’t these days—you’ve probably noticed each tool wants its own configuration file. Cursor reads .cursor/rules, Claude looks for CLAUDE.md, and every new agent seems to invent yet another convention. This proliferation of tool-specific files is annoying.
Enter AGENTS.md: a unified standard that consolidates project context for AI agents in one predictable location.
The Problem #
Modern development environments are heterogeneous. You might use Cursor for rapid prototyping, your buddy uses Claude for architectural discussions, and open-source contributors prefer Aider or GitHub Copilot. Each agent needs to understand your project structure, build commands, coding conventions, and architectural decisions. Maintaining separate configuration files for each tool means duplicating content and inevitably letting some documentation drift out of sync.
The Standard #
AGENTS.md follows the same principle as README.md, but targets AI agents instead of human contributors. Place it at your repository root and include:
- Project overview and architecture
- Setup and build commands
- Testing procedures
- Coding standards and conventions
- Domain-specific context
Don’t overload it though, less than 200-300 LOC would be ideal. Reference other files if you need more.
Practical Usage #
Create an AGENTS.md in your repository root with project-specific instructions. That’s it.
For stubborn holdouts that insist on their proprietary configuration files, use a symlink:
ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md
Some tools let you configure which file to use. For example, Gemini CLI can be configured via .gemini/settings.json:
{
"contextFileName": "AGENTS.md"
}
Yes, if you use multiple holdout tools, you’ll still have multiple files in your repository. But here’s the key difference: there’s no content duplication. All those symlinks and config files point to the same source. Update AGENTS.md once, and every agent sees the changes immediately.
Note on nested files: Tools supporting AGENTS.md read the nearest file—typically the one in your current directory or repository root. Claude Code’s CLAUDE.md, however, merges contexts upward from the directory tree, so subdirectory CLAUDE.md files layer on top of parent ones. Keep this in mind if you’re using subdirectory-specific instructions.
Why This Matters #
Standards win by being simple and solving real problems. AGENTS.md does both. Instead of managing multiple configuration files, you maintain one canonical source of truth. Instead of wondering which agent has stale context, you know they’re all reading the same file.
The heterogeneous AI agent landscape isn’t going away—if anything, we’ll see more tools emerge. Having a standard way to communicate project context makes that diversity manageable rather than chaotic.