Maintain one AGENTS.md file that any coding agent can read, instead of diverging per-tool rule files — with tested content and a review loop that keeps it current.
- A repository where at least one coding agent works
- A build and test command that already passes
- Five minutes to write the first version
Every coding agent reads instructions from somewhere: Claude Code reads CLAUDE.md, Cursor reads .mdc rules, Codex-style tools read AGENTS.md. When each tool gets its own file, the rules drift, and nobody can say which one the agent actually followed. AGENTS.md is the open answer: a plain Markdown file at the repository root that tells any agent how to build, test, and change the project.
In December 2025 the standard was donated to the Agentic AI Foundation under the Linux Foundation — the same neutral home as MCP — so it is no longer any single vendor’s convention. Adopting it means writing the rules once.
What belongs in the file
AGENTS.md has no required sections; the useful contract is short:
- Project map: where the code, tests, and documentation live.
- Commands: how to install, run, test, and lint — exact, copy-pasteable, and true.
- Boundaries: what an agent may never change without a human (public APIs, migrations, generated files, secrets).
- Definition of done: the checks that must pass before a change is handed back.
- Style constraints: only the ones that differ from default — an agent that must read three paragraphs of taste notes will not.
A rule that cannot be checked by a command is a wish. Prefer one test over three adjectives.
Keep one source of truth
If your tools expect other filenames, derive them from the single source instead of duplicating:
- Keep
AGENTS.mdas the canonical text. - Where a tool cannot read it, import or symlink the same content rather than rewriting it.
- Review the file like code: when a command or boundary changes, the file changes in the same commit.
The FlyPython repository publishes reviewed AGENTS.md and agent-rules templates you can copy as a starting point — the same templates the site’s homepage exposes for .cursorrules and system prompts.
Verify the file the way an agent does
An AGENTS.md file is only as good as its worst stale line. Each time you change the build or test path, run one agent session that only follows the file — if it fails to install or test, the file lied, and that is the bug to fix. Treat a misleading instruction as a production defect: it will be executed verbatim by every future session.
Sources
Every primary reference in this guide is linked where it is used: the AGENTS.md specification site for the file format, the Agentic AI Foundation for the governance announcement, and the FlyPython templates directory for reviewed starting points.
Verification record
Editorial review against the AGENTS.md specification site and the Agentic AI Foundation governance announcements. Verified 2026-09-06.
About the author
Organizational byline for FlyPython guides, verification records, and corrections. Editorial standards and contact details →