If you've picked up OpenAI Codex, OpenCode, or half a dozen newer coding agents, you've met AGENTS.md: a plain Markdown file at your repo root that tells the agent how your project works. No frontmatter, no schema, no special syntax — which is exactly why most of them are bad. When anything is valid, nothing forces you to write the parts the agent actually uses.
This post covers how the file is resolved, a four-section structure that holds up in practice, and the specific writing mistakes that make agents quietly ignore your rules.
Who reads AGENTS.md (and who doesn't)
AGENTS.md started as the instructions file for OpenAI Codex and has become the closest thing agent tooling has to a shared standard — OpenCode reads it natively, and a growing list of editors and agents either read it directly or accept it as a rules source. The pattern is converging because the content problem is identical everywhere: the agent needs to know what this project is, how to run its checks, and what it must not touch.
Two practical notes before you assume portability:
