By the end of 2025, AI coding agents stopped being a toy. Claude Code, Codex, Cursor, Copilot and opencode are now doing real work in real repos — and teams are discovering that the difference between an agent that ships clean PRs and an agent that breaks your build is one file: AGENTS.md.
If you haven't seen it yet: AGENTS.md is a markdown file, committed to your repo root, that tells AI agents how your repo actually works. Commands, conventions, architecture, gotchas. The agent reads it at session start — before it touches a single file.
This post is a practical, opinionated guide: what to put in the file, what to leave out, and the exact template I use in production repos.
Why AGENTS.md exists
Agents don't have intuition. They have context windows. Without instruction, an agent in a fresh repo will:
