A new convention is emerging in the open-source ecosystem: AGENTS.md, a straightforward and open format designed to assist AI coding agents in software development. Already adopted by more than 20,000 repositories on GitHub, the format is being positioned as a companion to traditional documentation, offering machine-readable context that complements human-facing files like README.md.
The concept is straightforward. While READMEs are optimized for developers—covering project introductions, contribution guidelines, and quick starts—AGENTS.md serves as a predictable, structured location for agent-specific instructions. These include setup commands, testing workflows, coding style preferences, and pull request guidelines.
By isolating this information, projects can reduce noise in their READMEs while giving agents a clear path to follow. The format is designed to be portable across the growing ecosystem of AI-assisted development tools, including OpenAI’s Codex, Google’s Jules, Cursor, Aider, RooCode, and Zed.
The flexibility extends to large monorepos, where nested AGENTS.md files can provide package-level instructions. Agents automatically read the nearest file in the directory tree, ensuring subprojects receive tailored guidance. For example, the OpenAI organization’s repositories currently maintain dozens of AGENTS.md files across subcomponents.
Early adopters highlight the format’s practicality: rather than introducing a proprietary configuration file, its markdown-based approach ensures accessibility while fitting neatly into existing project structures. As the maintainers explain, the goal was to provide precise, agent-focused guidance that complements existing README and docs without locking developers into a specific ecosystem.
Still, developers caution that AGENTS.md will not eliminate the need for human oversight.
I think they will always need special guidance for things like business logic. They will never know exactly what it is that you are building and why, what the end goal of the project is, without you telling them. Architectural stuff is also a matter of human preference… the real bottleneck will be in how humans read and interpret the changes.
Others are more skeptical of the split between human- and agent-facing documentation. As one Hacker News user argued:
I am still not convinced that separating README.md and AGENTS.md is a good idea.
By standardizing how projects communicate with AI assistants, AGENTS.md aims to reduce friction in human–AI collaboration. For many, it is being compared to the early days of README.md—an initially simple convention that has since become foundational across open source.
