AGENTS.md — the guide

What is AGENTS.md?

The idea is simple: every coding agent needs the same orientation before it touches a codebase — how to build it, how to test it, what to leave alone — so that guidance goes in one predictably named markdown file at the repository root instead of being repeated per session or per tool. Governance has since moved to the Linux Foundation's Agentic AI Foundation (AAIF), which also stewards MCP, contributed by Anthropic, and goose, contributed by Block.The Linux Foundation's announcement puts adoption at more than 60,000 open-source projects.

Which tools read AGENTS.md?

Per the Linux Foundation announcement · verified Jul 9, 2026

Claude Code and Windsurf are widely reported to read AGENTS.md too, but neither appears on the Linux Foundation's list. That list is the only official roster, so we keep the two groups separate — LF-listed above, reported-but-unlisted noted here — until an equally authoritative source settles it. When the foundation updates its list, this page updates the same week.

How does Codex use AGENTS.md?

That description is deliberately conservative. Codex now spans several surfaces — CLI, IDE extensions, cloud, and the ChatGPT desktop app — and behavior details such as nesting, precedence between multiple instruction files, and interaction with per-user config deserve verification against real sessions rather than paraphrases of other people's posts. As we verify each behavior, it gets documented here with a date on it.

What goes in a starter AGENTS.md?

# AGENTS.md

## Project overview
[One or two sentences: what this project is, primary language and framework.]

## Commands
- Install dependencies: `[your install command]`
- Build: `[your build command]`
- Run tests: `[your test command]`
- Lint / format: `[your lint command]`

## Conventions
- Code style: [formatter or linter, and where its config lives]
- Commit messages: [your convention]
- Layout: [where source, tests, and assets live — one line each]

## Boundaries
- Do not edit: [generated files, vendored code, lockfiles, migrations]
- Secrets live in [location]; never hard-code or commit them.
- Ask before: [deleting files, changing public APIs, altering CI]

This is a generic template, not sample output from any tool. Replace the placeholders, delete sections that do not apply, and resist the urge to pad it — a short file that is always true beats a long one that drifts out of date.

AGENTS.md vs CLAUDE.md vs copilot-instructions

Three files, one job: standing instructions for a coding agent, versioned with the repo. The difference is scope — one is a cross-tool standard with a foundation behind it, and two are tool-specific conventions.

People already treat these as one decision — "agents.md vs claude.md vs copilot-instructions.md" comes straight from Google autocomplete (pulled live July 9, 2026). The convergence point is AGENTS.md: it is the only one of the three with a standards body behind it and a published multi-vendor reader list.

Do you need an AGENTS.md file to use Codex?

No. AGENTS.md is a convention, not a requirement — Codex and every other tool on the Linux Foundation's list run fine without it. The file earns its place on any project you return to more than once: it replaces the project context you would otherwise paste into every session, and it is version-controlled alongside the code it describes.

Is AGENTS.md an OpenAI product?

OpenAI initiated the convention in August 2025, but it no longer belongs to OpenAI. The Linux Foundation's Agentic AI Foundation governs it as an open standard, alongside MCP (contributed by Anthropic) and goose (contributed by Block), per thefoundation's announcement. That neutral home is the point: the same file is meant to work across competing coding agents.

Changelog for this page

Every edit to this reference, newest first. This is what "living document" means.