AGENTS.md

AGENTS.md is “a simple, open format for guiding coding agents” — a markdown file in a repo holding “the extra, sometimes detailed context coding agents need: build steps, tests, and conventions,” keeping READMEs human-focused. It’s the context-standard counterpart to the capability-standard agentskills-spec: where skills package what an agent can do, AGENTS.md packages what it needs to know about this project. Source: agents.md.

Why it matters here

• Cross-tool convergence (the real signal): “over 60k open-source projects,” read by *OpenAI Codex, Google Jules, Aider, goose, VS Code, Devin, GitHub Copilot, JetBrains Junie, Cursor, Zed, Warp” and ~20 more — now stewarded by the Agentic AI Foundation (Linux Foundation). This is the same open-standard-as-industry-attractor pattern the synthesis tracks for agentskills-spec, but for project context rather than capability.
• It’s the generalized, vendor-neutral sibling of tool-specific memory files (e.g. CLAUDE.md), and the reviewable-context substrate that spec-driven-development and agent-guardrails (the AGENTS.md contract in agents-never-do-alone) build on.

What the spec actually says

Per agents-md-spec (the format’s own site), it’s plain Markdown with flexible headings, suggesting — not mandating — sections for project overview, build/test commands, code style, testing, security, commit/PR guidelines, and deployment. The role split with the README is deliberate: the README serves humans, AGENTS.md holds the “extra, sometimes detailed context coding agents need.”

The mechanism that makes it work across a large codebase is the nearest-file rule — “agents automatically read the nearest file in the directory tree, so the closest one takes precedence.” So context composes hierarchically: a repo-root file sets defaults, subproject files override locally. OpenAI’s main repository carries 88 nested AGENTS.md files agents-md-spec, the clearest evidence the convention scales to monorepos rather than degrading into one bloated file.

Does it work? The first controlled test says no (added 2026-08-03)

Everything above documents adoption — 60k projects, 30-odd tools, a Linux Foundation steward. None of it is evidence that the files improve what agents produce, and this wiki carried the convention for two months without any.

context-files-ablation-paper supplies the first controlled measurement, and it is a null. Across two frontier agents (Claude Code sonnet-4-6, Codex CLI gpt-5.5), 17 tasks mined from merged PRs in 3 Python repositories, and 288 gold-test-evaluated runs, context-injection strategy does not measurably move correctness — every Claude pairwise difference ≤2.3pp, bounded to ≤10pp (Claude) and ≤15pp (Codex). Deleting the AGENTS.md entirely scored 53.3% for Claude against 55.6% with it always in the system prompt. On the borderline tasks picked to have room to move, the no-context arm scored higher (58% vs 42%).

The mechanism matters more than the number. A triage of near-miss failures found the agents losing on implementation skill — feature design, pattern selection, exact wiring — and not on repository knowledge a context file could supply. A pre-registered probe re-ran the two convention-closest near-misses on both agents across 36 cells: the real, unmodified AGENTS.md never converts a near-miss to a pass on either agent. The author’s phrasing is careful — the manipulation is not inert, it “simply does not supply the implementation skill that gates these tasks.”

What did move was process, not outcome. On the one repository whose file warns that the test suite takes over 20 minutes, Claude’s blind full-suite pytest runs fell monotonically with more context (3.67 → 2.44 → 1.67 per cell) and wall-clock time with them. That saving came from a single warning about a cost the agent could not observe for itself — not from the conventions, style guides or architectural notes that make up most of a real AGENTS.md.

Read narrowly, since the study is small (MDE >30pp; a 10pp effect would need 120–200 tasks), Python-only, and a snapshot of two model versions. What it establishes is a bounded null with a mechanism, which is enough to stop treating adoption as evidence of effect. See synthesis for how it sits against the spoke’s other measured results.

Related

agents-md-spec · agentskills-spec · agent-skills · spec-driven-development · agent-guardrails · agents-never-do-alone · claude-agent-sdk · context-files-ablation-paper · agent-specific-task-difficulty · agent-evals · context-driven-development