I'm an active contributor to — what belongs in the file, why it rots, how to keep it true. This is the story of actually writing one against a real, active codebase, and what ended up in the version that got merged.
The problems that pushed me to write it
This wasn't a theoretical exercise. A few weeks of using different AI coding agents on this repo made the case on their own:
GitHub Copilot was burning through AI credits fast. Because it had to figure out the same project details for every task, like build commands, coding conventions, and where files were located.
Other agents hallucinated constantly. They suggested test commands that didn't exist, made up capability names, and assumed the wrong folder structure.
Agents refactored code nobody asked them to touch. "Fix this bug" would come back with unrelated files reformatted or restructured along the way.
Version numbers got bumped without being asked. More than once, an agent decided a small fix was also a good moment to cut a version bump.
Architectural files changed more than they should have.composer.json,composer.lock— config an agent has no business touching unless explicitly told to — got edited in the course of "just fixing a bug or while introducing a new feature."
Some PRs became unreviewable. A few agent-generated PRs touched around 40 files and added close to 7,000 lines in one go. Reviewing that by hand took far longer than the change deserved, and even GitHub Copilot's own PR review fell over on diffs that large — it couldn't give useful, focused feedback on a change that size.
Every one of those is a symptom of the same root problem: the agent had no source of truth for the project, so it was guessing, and guessing agents are expensive and destructive in roughly equal measure.
What AGENTS.md actually is, and why it's not just another README
AGENTS.md is a single Markdown file at the root of a repository that briefs AI coding agents on how to work in that specific codebase — the real build and test commands, where things live, which conventions are non-negotiable, and which changes need a human in the loop before they happen. It's become something of an open, tool-agnostic standard: most of the major coding agents (Copilot, Claude Code, Cursor, Codex, and others) look for it by default.
The distinction that matters most is this: README.md is for humans, AGENTS.md is for the agent. A README explains what the project is and why it exists — the pitch, the features, the installation steps for an end user. AGENTS.md answers a completely different question: how do I work in this repo without breaking it? The real test commands. The directories that matter. The things that must never be touched without asking first.
It's necessary for a very practical reason: without it, an agent has to reconstruct all of that context from scratch, every single time, by reading through files and guessing at conventions. That's slow, it burns tokens/credits, and worse — a guess that looks plausible is exactly how you get a hallucinated test command or an invented capability name that quietly breaks something. A short, accurate AGENTS.md turns "figure out the project" into "read one file," and turns "guess and hope" into "follow the rule that's written down."
The project
. It's short, every command in it runs, and the next contributor — human or agent — gets the thirty-second version of everything it took me an afternoon of reading real config files to learn.
SOCIAL SHARE CARD GENERATOR