AGENTS.md, Explained
AGENTS.md is the open, tool-agnostic file agents read to understand your project. Here's what goes in it, how it relates to CLAUDE.md, and where a single file per repo stops being enough.
AGENTS.md is the cross-tool answer to a simple question:
when an AI agent opens your repo, how does it know how to build, test,
and behave the way your team expects? It's a plain Markdown file at the
repo root — an open standard, now stewarded under the Linux Foundation,
that a growing list of agents read directly.
What it is
A Markdown file with no schema — instructions in prose. Agents treat it as always-true project context, so it's the right place for the facts you'd otherwise re-explain on every task: how to build, how to test, the code style, the shape of the repo, and the handful of rules that never change. Unlike a vendor-specific file, the same AGENTS.md is read across tools, so you write it once for every agent on the team.
Who reads it
AGENTS.md emerged as a shared convention precisely so teams wouldn't keep
a separate context file per tool. Agents and IDEs across the ecosystem —
OpenAI Codex, Cursor, Gemini CLI, Sourcegraph, and more — converged on
it, which is why it now sits under neutral stewardship rather than any
one vendor. Claude Code reads CLAUDE.md; many teams keep an
AGENTS.md as the canonical file and have CLAUDE.md defer to it.
What belongs in it (keep it tight)
- Commands first. Install, build, test, lint — the agent should never guess these.
- Conventions, not history. "Use 2-space indent, single quotes" belongs here. "We switched off X last quarter because…" does not.
- Repo layout. Where things live, so the agent navigates instead of searching.
- Hard rules. The few things always true — never edit generated files, always run the formatter.
If it's longer than a screen, the durable parts probably belong somewhere shared — read on.
Why one file per repo stops scaling
AGENTS.md has the same ceiling as any single context file. It lives inside one repository, so it can't express a decision that spans services, and a team working across 15+ repos ends up copy-pasting the same conventions into a dozen files that immediately drift. It's also a flat config: it can't say why a cross-cutting choice was made or who owns it.
This is where a shared context tree comes in.
First-Tree is an open-source platform for engineering teams running humans and agents side by side. Its memory pillar gives your team a context tree: a Git repo where cross-cutting decisions and ownership live in Markdown nodes that every agent, in every repo, reads — Codex, Cursor, Claude Code, your in-house agent. AGENTS.md (and CLAUDE.md) stay tight and per-repo; the tree holds the shared knowledge that would otherwise drift across a dozen files. One source of truth instead of N copies, built around running AI agent teams that stay coherent across a whole codebase.
If you're choosing between formats, see AGENTS.md vs CLAUDE.md, and the companion guide on writing a CLAUDE.md that works.