Patterns
Pattern 08 of 26
agents.md
The file that tells every agent how to behave here
AGENTS.md is a Markdown file you put at the root of a repository to tell AI coding agents how to behave in your project. What it is, how it is structured, what the agent should and should not touch. OpenAI adopted it for Codex, Anthropic uses it as CLAUDE.md for Claude Code, Google adopted it for Gemini CLI. Over 60,000 repos have one. The Linux Foundation now maintains the spec.
Why it matters
Every project I work on has a CLAUDE.md. Without it, the agent guesses at conventions and it is wrong enough to be annoying. With it, I write the constraints once and every session benefits automatically. It is behavioral configuration that lives in the repo, not in some chat box no one else can see.
Deep Dive
AGENTS.md is robots.txt for the agent era, with one important difference: robots.txt tells crawlers where not to go. AGENTS.md tells agents what to do and how to do it. A well-written AGENTS.md file covers the project structure, the tech stack, the commands to run before committing, the files to never touch, and the conventions the team has agreed on. The agent reads this file at startup. Everything downstream benefits from it. The file was independently adopted by multiple vendors before it was formalized: OpenAI for Codex, Anthropic for Claude Code (as CLAUDE.md), Google for Gemini CLI. The Linux Foundation brought all of those under a single spec in December 2025.
The practical value is that it eliminates a class of agent errors. Without a spec file, the agent infers project conventions from context. It often infers them wrong. It will use the wrong package manager, modify files in the generated directory, skip the test suite before committing, or write TypeScript in a style the team has explicitly banned. With AGENTS.md, you declare the constraints explicitly: do not use CSS modules, run npm test before committing, never modify files in /generated. The agent reads this once and uses it to constrain every subsequent decision in the session.
CLAUDE.md, which is what Claude Code reads by default, extends the base concept with project-specific instructions, custom slash commands, and style guides. The file accumulates over time. It starts as a few lines about the stack and grows into a document that encodes months of hard-won conventions. Because it lives in the repository and gets committed alongside code, it gets reviewed in pull requests. New team members read it. The agent reads it. It becomes the source of truth for how work should be done in this project. That is qualitatively different from instructions scattered across unversioned prompt boxes.