Six months ago, AGENTS.md was a convention some coding agents happened to share. Then, on December 9, 2025, OpenAI and Anthropic donated it to the Linux Foundation under the newly formed Agentic AI Foundation — and it stopped being anyone's product feature and became the closest thing the agent ecosystem has to a standard (agents.md). If AI agents touch your codebase, this one Markdown file is now the highest-leverage document in the repository. Here's what it is, what belongs in it, and how to write one that actually improves agent output.
What AGENTS.md is
AGENTS.md is a plain Markdown file in the root of a repository (optionally nested deeper for path-specific guidance) that tells AI coding agents how to work in your codebase — think of it as a README whose audience is machines doing work rather than humans reading about it. It grew out of an industry working group whose contributors included OpenAI, Google, Sourcegraph, Factory, and Cursor, and the cross-vendor support is the whole point: GitHub Copilot's coding agent reads it, Claude Code reads it alongside its own CLAUDE.md, and the majors have converged on the same file rather than fragmenting into per-vendor formats — the convergence we flagged in our Copilot vs Claude Code comparison. Write it once, and every agent that enters the repo gets better.
What belongs in it
The file is freeform Markdown — there is no schema to validate against — but the content that reliably earns its keep falls into five groups:
- Build and test commands. Exactly how to install, build, run the tests, and lint — the literal commands. This is the single highest-value section: an agent that can verify its own work stops shipping guesses.
- Conventions. Code style beyond what the linter enforces, naming patterns, preferred libraries (“use our internal HTTP client, never raw fetch”), error-handling idioms.
- Architecture orientation. Where things live, which modules own what, what's deprecated-but-present, which directories are generated and must not be hand-edited.
- Boundaries. What agents must not do: files never to touch, migrations never to run, secrets never to read, APIs that are rate-limited or production-facing.
- Definition of done. What a finished change includes — tests, docs, changelog entry — so the agent's pull request arrives review-ready instead of review-starting.
How to write one that works
Start from agent failures, not from a template. The best AGENTS.md files are casebooks: every time an agent gets something wrong — wrong package manager, missed test command, touched a generated file — the correction becomes a line in the file. Treat it like onboarding documentation that gets a pull request whenever onboarding fails.
Be literal and testable. “Write clean code” does nothing. “Run pnpm test — do not use npm” changes behaviour. If a rule matters enough to write down, it's usually deterministic enough to also enforce in CI — the file instructs, the gate enforces, and together they're reliable.
Keep it short enough to be read whole. The file is loaded into the agent's context on every task; a 2,000-line manifesto crowds out the actual work. A few hundred focused lines beat completeness. Nest additional AGENTS.md files in subdirectories when a monorepo genuinely needs different rules per area.
Version it, review it, own it. It lives in the repo, so it gets the same treatment as code: pull requests, review, blame. Teams at higher agentic-SDLC maturity assign it an owner the way they assign CODEOWNERS.
AGENTS.md, CLAUDE.md, copilot-instructions — which one?
The practical answer in 2026: AGENTS.md is the portable baseline — the shared truth every agent reads. Vendor-specific files still exist for vendor-specific features (Claude Code's CLAUDE.md, Copilot's instructions files for path-scoped rules), and the sane pattern is to keep the substance in AGENTS.md and let the vendor files stay thin or simply point at it. What you should not do is maintain three divergent copies of your conventions — that's how agents get contradictory instructions and humans stop trusting any of the files.
Why this file matters more than it looks
Agents amplify clarity and punish ambiguity: a vague repo produces a confident, wrong pull request. AGENTS.md is the cheapest clarity you can buy — no platform migration, no new tooling, one file and a habit of updating it. In the maturity assessments we run, whether a team maintains instructions files is one of the sharpest single predictors of whether their agent rollout is compounding or stalling. It's also the on-ramp: before spec-driven development, before custom agents, before orchestration, there's a Markdown file that teaches the agent your house rules.
Deop helps engineering teams make their repositories agent-ready — instructions files, review gates, and governance — as a Microsoft partner specialized in Agentic DevOps with GitHub. Read the agentic SDLC field guide or book a discovery.