The same premise, two takes. Here is where each one helps, where each one falls short, and why you might use both.
Full disclosure up front: AGENTS.md is the established convention. It is used by 60k+ open-source projects, it is plain open Markdown, and it already describes itself as "a README for agents." AGENT-README.md shares that premise. This page is not a takedown; it is an honest account of the differences so you can choose well.
What AGENTS.md does well
Adoption and predictability. With tens of thousands of repositories using it and several agent tools looking for it by name, an agent does not have to guess whether guidance lives in README.md, CONTRIBUTING.md, or docs/.
Repository-specific guidance. A natural home for preferred test commands, coding conventions, architectural constraints, and "do not touch this subsystem" notes.
Less prompt repetition. Encode "always run tests before committing" once, in the repo, instead of re-typing it every session.
Minimalism. No required schema, no YAML, no JSON: just Markdown. That low bar is a large part of why it spread, and it avoids locking a project into any one vendor's format.
Nested files. Large repositories can place an AGENTS.md per directory, and the nearest file to the code being edited wins. Different parts of a monorepo can carry different rules.
Open and vendor-neutral. One filename any tool can support, rather than a separate file per assistant.
Tradeoffs that apply to both
These are not weaknesses of AGENTS.md specifically. They are inherent to any file that guides an agent, and AGENT-README.md carries them too.
Advisory, not enforcement. An agent can ignore or misread the file. It complements, and does not replace, CI, linters, branch protection, and tests.
It can go stale. A wrong build command or an outdated architecture note can lead an agent to confidently do the wrong thing. It needs the same upkeep as any documentation.
Prompt-engineering bloat. Both formats invite a failure mode: filling the file with generic "AI psychology" ("think deeply", "never hallucinate", "be an expert"). That advice ages badly as models improve and tends to have diminishing returns. Repository-specific facts have a much longer shelf life.
Where AGENT-README.md leans differently
The goal is not a different premise; it is a more opinionated take on the same one.
A self-describing name next to README.md. It reads as "a README, but for agents," and sorts alphabetically beside README.md. (In fairness, AGENTS.md uses the same tagline, so this is a matter of emphasis, not exclusivity.)
A light, recognizable structure. The draft spec names a small set of headings (Purpose, Setup & commands, Conventions, Guardrails, Architecture, Contacts) and elevates ## Guardrails as the section an agent should honor first. It stays plain Markdown, with no required schema.
An optional metadata header. A tiny, flat Key: value block (deliberately not YAML) for identity and pointers, never for instructions.
Beyond repositories. The convention also defines serving the file at a website root (/agent-readme.md), so a site, not only a repo, can describe itself to visiting agents.
Philosophy over procedure. Agents are already good at discovering build commands. They are worse at inferring a project's values. The convention encourages capturing durable principles ("performance matters more than brevity", "every storage-internals claim must be reproducible") alongside the commands.
The honest concern: fragmentation
A standard only helps if people converge on it. Introducing another filename risks worsening the very sprawl this space complains about (CLAUDE.md, GEMINI.md, COPILOT.md, CURSOR.md, and so on). Our position:
If you already use AGENTS.md, keep it. AGENT-README.md is compatible and can reference or alias it (a one-line pointer in either direction).
The aim is one file that any agent understands, not another vendor silo. If the ecosystem settles on a single name, that is a win regardless of which name it is.
Ideas folded in from review feedback
Four external reviews of the draft (ChatGPT, Google Gemini, GitHub Copilot, and a top contributor on Stack Overflow for Agents) surfaced improvements that are now part of the v0.1 spec:
Facts vs. Preferences. Separate the non-negotiable ("Database is SQL Server", "Use NUnit") from the negotiable ("prefer CTEs over nested subqueries", "British spelling"), so an agent can reason about them differently. The review feedback tightened this to "facts first, keep it short". (Spec §4.2.)
A "surprises" section. The tacit knowledge experienced contributors carry ("this table has no foreign keys by design", "never rename this procedure; customers call it directly") is exactly what a new contributor, or an agent, does not know. (Spec §4.)
Nested, per-directory files. The same nearest-wins model AGENTS.md uses, so a database folder and a web frontend can carry different rules. (Spec §2.)
An explicit stance against prompt filler. The spec now discourages generic model-steering text in favor of repository-specific knowledge. (Spec §9.)
Explicit operating boundaries. Guardrails can declare filesystem, network, command, and operation limits, while staying advisory. (Spec §4.1.)
A "current state" section. A place to record active refactors and known-failing areas, so an agent does not try to "fix" work in progress. (Spec §4.)
MCP and context endpoints. The Architecture section can point an agent at the MCP servers or context sources a project depends on. (Spec §4.)
A consumer algorithm. An explicit "how an agent should discover and use this file" sequence, so adoption means the same thing across tools. (Spec §6.1.)
Migration and coexistence. Guidance for projects that already have an AGENTS.md or .cursorrules: keep the existing file as a pointer, avoid duplicated guidance, do not break tooling. (Spec §7.)
Versioning and a changelog. An optional Version field and a ## Changes section, so an agent can spot recently changed guidance. (Spec §5.2 and §4.)
Adoption signals. A README badge and a predictable, linkable file location. (Spec §10.)
Guardrails ordered for execution. An agent reviewer argued that a first screen of caution text "reads like policy, not an execution manual". Guardrails now sit directly after ## Setup & commands, above ## Conventions: how to run the project, then how not to break it, then style. (Spec §4 and §4.1.)
Repo-specific over generic guardrails. The same review noted that "never edit schema.generated.ts" is operationally decisive while "ask before deleting files" is generic advice most agents already follow. The spec now tells authors to lead with repo-specific rules and keep generic caution to a minimum. (Spec §4.1.)
Single source of truth, made explicit. The reviewer's core point: a second file only helps if it is the canonical agent-facing document, with other surfaces reduced to a pointer. Additive-alongside guidance recreates the fragmentation the convention is meant to remove. This reinforces the migration guidance in §7.
Further feedback raised in review (not yet in the spec)
A later review on the same Stack Overflow for Agents thread, from a second top contributor writing from the agent's side, agreed with the execution-first ordering and the single-canonical-file position, and raised four points we are still weighing rather than adopting into v0.1:
A machine-readable command block. Exact commands are the single highest-value part of the file, and burying them in prose forces unreliable extraction. The suggestion is a short structured block (a small table) near the top listing the package manager and the build, test, lint, and deploy commands, so an agent can parse them directly rather than infer them. This sits in tension with the current rule that commands live in the readable body and not in the metadata header (§5), so it would need a design that keeps a single source of truth.
A checkable definition of done. "Tests pass and --help output is accurate" is a gate an agent can verify; "write good code" is not. The Purpose section already asks for a definition of "done"; the refinement is to state it as concrete, checkable criteria so an agent neither over-delivers nor ships incomplete work.
Documented failure modes. Agents most need guidance exactly where it is usually absent: when the build is broken on main, or when install fails. The file could state the expected behaviour for these common breakages.
Escape hatches. If an agent cannot run the test suite (a missing dependency, a broken environment), the file should say what to do instead, for example stop and report versus proceed with an explicit caveat.
A further reply, from an agent that carries its own Skills and persistent Memory, raised a distinct question the draft does not address directly:
Precedence against an agent's own Skills and Memory. A stateful agent already holds portable technique (Skills) and remembered facts (Memory), which the file cannot see. The reviewer proposed a fixed ladder (Skills > Memory > AGENT-README) and asked the file to reference the Skills a repository relies on. Our position: the file should indeed point at relevant Skills and not restate what they cover (this matches §9's no-duplication and single-source-of-truth aims), but a fixed source-based ladder is the wrong rule. Precedence should follow specificity, as §6 already states: a repo-specific instruction ("never modify .hermes/", "do not run migrations here") is more specific and more restrictive than a portable Skill and should win on that basis, while an operator safety policy always wins. Skills (portable technique) and the file (repo-specific operational fact) are largely different axes; when they conflict it is usually because the repository is non-standard, which is exactly when the repo-specific instruction should be believed.
An open question we are holding a position on
The same reviewer questioned whether a new filename is worth it when AGENTS.md already has adoption momentum. Our position: the filename should describe the file. AGENT-README.md reads immediately as "the README for agents", the way README.md reads as "read this first". Current adoption measures momentum, not which design is clearer over the long run, so we would rather argue for the self-describing name and let adoption follow. The reviewer's underlying concern still holds, and we accept it: whichever name a project picks, there must be exactly one canonical file and the rest must point at it.
At a glance
Dimension
AGENTS.md
AGENT-README.md
Maturity
Established, 60k+ projects
New, draft v0.1
Tool auto-discovery
Recognized by several tools
None yet
Format
Plain Markdown, no schema
Plain Markdown; optional flat metadata header
Structure
Freeform
Recommended named sections; Guardrails first
Nested files
Yes, nearest-wins
Yes, nearest-wins (v0.1)
Scope
Repositories
Repositories and website roots
Framing
"README for agents"
"README for agents", human-first emphasis
Enforcement
Advisory
Advisory
Which should I use?
Want maximum tool compatibility today? Use AGENTS.md.
Want the structure, guardrail priority, and metadata ideas here? Use AGENT-README.md, and consider keeping an AGENTS.md that points at it (or the reverse).
Either way: keep the file repository-specific, keep it current, and leave the generic AI pep talk out.
External design reviews of the AGENT-README.md draft (ChatGPT, Google Gemini, GitHub Copilot, and Stack Overflow for Agents). ChatGPT contributed the Facts-vs-Preferences, newcomer-surprises, nested-files, and anti-prompt-filler ideas. Gemini contributed the explicit tool-access boundaries, the "current state" section, and MCP/context-endpoint pointers. GitHub Copilot contributed the consumer algorithm, migration/coexistence guidance, structured guardrails, versioning/changelog, and adoption signals. A top contributor on the Stack Overflow for Agents review thread contributed the execution-first ordering (guardrails after commands), the repo-specific-over-generic emphasis, and the single-source-of-truth argument. A second top contributor on the same thread, reviewing from the agent's side, reinforced the execution-first ordering and the single-canonical-file position, and raised further feedback still under consideration: a machine-readable command block, a checkable definition of done, documented failure modes, and escape hatches for when commands cannot run. A further reply, from an agent with its own Skills and persistent Memory, raised the question of how the file should relate to an agent's built-in capabilities, which we address through specificity-based precedence (§6) rather than a fixed source-based ladder.