og.cc.cd / guides / what-is-agents-md

What Is AGENTS.md? How to Write One That Coding Agents Actually Follow

By og.cc.cd · Published · Updated · 4 min read

TL;DR: AGENTS.md is a plain Markdown file at the repo root that tells AI coding agents how to build, test and work in your project — a README written for agents; keep it short, concrete and command-first.

Updated · All sources ↓

AGENTS.md is a plain Markdown file that tells AI coding agents how to work in your repository: how to build and test, which conventions to follow, and what not to touch. Think of it as a README written for agents instead of humans.

Generate an AGENTS.md →All guides

Where it came from and who reads it

The format emerged from collaboration between OpenAI Codex, Amp, Google’s Jules, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. The official site, agents.md, says it is used by more than 60,000 open-source projects and lists compatible tools including Codex, Jules, Cursor, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Gemini CLI, GitHub Copilot’s coding agent, Windsurf and others.

Claude Code reads AGENTS.md too (from v2.1.277) when the project has no CLAUDE.md; see CLAUDE.md best practices for how the two interact.

The rules of the format

  • No required fields. It is standard Markdown; use any headings you like.
  • Location: the repository root. In a monorepo, add more files inside packages — agents read the nearest file in the directory tree, so the closest one takes precedence.
  • Conflicts: the closest AGENTS.md to the edited file wins; explicit instructions in the chat override everything.
  • Commands get run. If you list test or lint commands, agents will try to run them and fix failures before finishing.

How Codex layers the files

OpenAI’s Codex docs describe the precise discovery order, which is a good mental model for the format in general:

  1. Global: ~/.codex/AGENTS.override.md if present, otherwise ~/.codex/AGENTS.md.
  2. Project: from the Git root down to your current directory, one file per directory (AGENTS.override.md, then AGENTS.md, then any configured fallback names).
  3. Merge: files are concatenated root-first, so deeper files appear later and effectively override broader guidance.

Codex stops adding files once the combined size reaches project_doc_max_bytes — 32 KiB by default. That is a useful hint for everyone: long instruction files get truncated or diluted. Keep yours tight.

What to put in it

Write what you would tell a new teammate on day one, in a form an agent can check. The sections the official site recommends — and that agents benefit from most — are:

  • Project overview — one or two sentences on what the code does.
  • Build and test commands — exact, copy-pasteable commands.
  • Code style — concrete rules (“named exports only”), not adjectives (“clean code”).
  • Testing instructions — where tests live and what must pass before a change is done.
  • Security and boundaries — files the agent must not edit, secrets it must never print, commands it must not run.
  • PR and commit conventions — title format, checks to run first.

A complete example

# AGENTS.md

## Project
Invoice API: FastAPI service that creates and sends PDF invoices.

## Setup and commands
- Install: `uv sync`
- Run locally: `uv run uvicorn app.main:app --reload`
- Test: `uv run pytest -q`
- Lint + types: `uv run ruff check . && uv run mypy app`

## Layout
- `app/api/` — HTTP routes only, no business logic
- `app/services/` — business logic
- `tests/` — pytest, mirrors `app/`

## Conventions
- Type hints on every public function.
- Money is `Decimal`, never `float`.
- New endpoints need a test in `tests/api/`.

## Boundaries
- Never edit `migrations/` by hand; use `uv run alembic revision --autogenerate`.
- Never commit `.env` or print values from it.

## Before you finish
Run lint, types and tests; all must pass.

Notice what is not there: a long architecture essay, a dependency list the agent can read from pyproject.toml, or motivational advice. Every line is either a fact the agent can’t easily discover or a rule it can verify.

Monorepos and overrides

In a monorepo, keep shared rules at the root and put package-specific commands next to the package. The agent working in services/payments/ then sees the root rules followed by the payments rules:

repo/
├── AGENTS.md                  # shared: lint, commit format, boundaries
├── services/
│   ├── payments/
│   │   └── AGENTS.override.md # Codex: replaces payments/AGENTS.md if both exist
│   └── search/
│       └── AGENTS.md          # search-specific test command
└── web/
    └── AGENTS.md              # frontend conventions

Codex also checks AGENTS.override.md before AGENTS.md in each directory, which is handy for a temporary rule without editing the shared file. For Codex code review on GitHub, OpenAI suggests a ## Code Review Rules section in the AGENTS.md closest to the code it governs. The official site notes that the main OpenAI repository alone had 88 AGENTS.md files at the time of writing.

Common mistakes

  • Vague rules. “Write good tests” gives the agent nothing to check. “Every new endpoint needs a test in tests/api/” does.
  • Stale commands. If npm test became pnpm test six months ago, the agent will waste a turn on the old one. Update the file in the same PR that changes the tooling.
  • Duplicating the README. Link to human docs instead of pasting them; length dilutes the rules that matter.
  • Secrets in the file. AGENTS.md is committed and read into prompts. Never put tokens, passwords or internal URLs you would not publish in it.

Making other tools read it

  • Gemini CLI: set {"context": {"fileName": "AGENTS.md"}} in .gemini/settings.json.
  • Aider: add read: AGENTS.md to .aider.conf.yml.
  • Claude Code: reads it automatically when there is no CLAUDE.md; otherwise put @AGENTS.md at the top of CLAUDE.md.
  • Migrating an old file: the official FAQ suggests renaming and symlinking, e.g. mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

Check that it loaded

With Codex, run codex --ask-for-approval never "Summarize the current instructions." from the repo root; it should echo your rules in precedence order. Treat the file as living documentation: whenever an agent makes the same mistake twice, add a line.

Prefer a form to a blank page? The AGENTS.md generator builds this structure from a few fields, with Next.js, Python and Go presets.

Sources

Vendor features and prices were checked against these official pages on 2026-10-18. Products change; if something here no longer matches, the official page is right.

Related guides