AGENTS.md for AI coding and platform agents

AI coding agents need guidance to operate safely and effectively. Without clear instructions they may make unwanted changes, run unsafe commands or drift from architectural conventions. AGENTS.md is an open standard that addresses this. It is a markdown file placed at the root of a repository (and optionally in subdirectories) that gives coding agents the context and instructions they need. This post explains what AGENTS.md is, which tools read it, how it relates to other memory files and the current state of adoption.

What is AGENTS.md

The AGENTS.md project describes the file as a simple, open format for guiding coding agents, and as a README for agents: a dedicated, predictable place to provide the context and instructions that help AI coding agents work on your project. Where a traditional README explains a project to humans, AGENTS.md tells an agent how to build, test and run the software, along with environment requirements and coding conventions. It is just standard Markdown with no required fields, so you can use whatever headings suit your project, and it lives alongside your code in version control.

The format supports nesting. In a monorepo you can place another AGENTS.md inside each package, and agents automatically read the nearest file in the directory tree, so the closest one takes precedence. This gives granular control over agent behaviour without duplicating global instructions in every folder.

Supported tools

AGENTS.md has been adopted across a wide range of agents and editors. The project site lists a broad and growing set of supporting tools, including Codex, Jules, Cursor, Windsurf, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Gemini CLI, the GitHub Copilot coding agent and Augment Code, among others. These tools read AGENTS.md automatically when it is present. For example, Codex loads AGENTS.md from its home directory, the project root and each directory down to the working directory, concatenating them with closer files overriding more distant ones. Kiro also recognises AGENTS.md and, unlike its regular steering files, always includes it.

The breadth of adoption is significant: the project site reports tens of thousands of open source projects using AGENTS.md (over 60,000 at the time of writing). Because the format is open and human readable, new tools can implement support easily, so treat any specific count as a moving figure.

Relationship to other memory files

AGENTS.md is one of several mechanisms for providing context to AI agents. It differs from CLAUDE.md (used by Claude Code) and steering files (used by Kiro) in scope and intent. AGENTS.md holds operational policy and explicit build and test commands, whereas CLAUDE.md holds instructions and context specific to Claude Code, and steering files record conventions and patterns for Kiro at the workspace or global level. You can keep an AGENTS.md alongside these other files, and tools that support multiple formats will use the ones they understand. With Codex, for instance, AGENTS.md carries team-wide instructions while its memory feature holds personal preferences.

Current adoption and patterns

A growing number of projects and organisations standardise on AGENTS.md. The most effective files contain command-first instructions with clear done criteria rather than vague prose, because explicit commands and acceptance checks are what agents act on reliably. Adoption is broad but not universal: some tools still rely on their own formats, and there is no single governing body enforcing the standard. Even so, the simple markdown format and wide tooling support make AGENTS.md a practical way to give agents the context they need.

Conclusion

AGENTS.md is a lightweight but powerful way to convey build and run instructions to AI coding agents. By separating operational policy from human documentation, it helps agents act consistently across environments. Many modern tools support it out of the box and adoption continues to grow. Teams should consider adding an AGENTS.md file to their repositories, alongside any other memory mechanisms, to make sure AI agents understand how to build and test their code.