Every coding agent starts a session knowing nothing about your repository. It does not know that tests need a local Postgres, that npm is banned in favor of pnpm, or that the legacy/ folder must not be touched. So it guesses, and you correct it, and the next session it guesses again.

AGENTS.md is the fix that most of the industry has converged on: one Markdown file in the repository that tells agents how to work on the project. OpenAI released it in August 2025 together with other agent builders, more than 60,000 open-source projects had adopted it by December 2025, and in December 2025 it was donated to the new Agentic AI Foundation under the Linux Foundation, next to MCP and goose.

The format is trivial; writing a good one is not. This cheatsheet covers placement and precedence, what to include and omit, a realistic example, monorepos, tool support as of early February 2026, and maintenance.

1. What AGENTS.md is (and is not)

Term Meaning Why it matters
AGENTS.md A plain Markdown file with instructions for coding agents, usually at the repository root One predictable place for setup, commands, conventions and rules. No schema, no required fields.
"README for agents" The project's own framing: README.md is for humans, AGENTS.md is for agents Keeps agent-specific detail (exact commands, gotchas, boundaries) out of the human quick start.
Nested AGENTS.md Extra files inside subdirectories or packages Lets each part of a monorepo carry its own commands and rules.
Precedence The closest file to the code being edited wins; an explicit user prompt overrides everything Tells you where to put a rule so it applies where you want and nowhere else.
Tool-specific files CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/ Older or richer per-tool formats. Several tools read both their own file and AGENTS.md.

What it is not:

  • Not a security boundary. It is text in a prompt. A "never run rm -rf" line lowers the odds; sandboxing, permissions, branch protection and CI enforce it. Put real limits in real controls.
  • Not a place for secrets. It is committed, read by every agent and every contributor, and often sent to a hosted model.

2. Where files go and which one wins

The general rule from agents.md: the closest file to the edited code wins, and explicit chat prompts override everything. Codex documents its discovery order most precisely, so it makes a good reference model:

Scope Location Behavior in Codex
Global ~/.codex/AGENTS.md (or $CODEX_HOME) Personal defaults for every repository. AGENTS.override.md in the same folder replaces it if present.
Project root AGENTS.md at the Git root Shared, committed rules for the whole repository.
Each directory down to the working directory AGENTS.md in every folder on the path One file per directory, checked in the order AGENTS.override.md, AGENTS.md, then any configured fallback names.
Merge All of the above Concatenated from global to root to the current directory. Later files override earlier ones because they come later in the prompt.
Size cap project_doc_max_bytes Stops adding project files once their combined size reaches 32 KiB by default. Content past the cap is truncated (Codex only logs a warning).

Two details that bite people:

  • Codex walks from the Git root down to the directory you start in, not into sibling folders. A rule in services/payments/AGENTS.md does not load if you start the session in services/search/.
  • An AGENTS.override.md anywhere on the path replaces the regular file in that directory. If an agent ignores your edits, look for a forgotten override.

Configuration and a quick check, from the Codex docs:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

# Ask Codex what it actually loaded
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

3. What to put in

Write for a new engineer who follows instructions literally. GitHub's review of more than 2,500 agents.md files found that the effective ones cover six areas: commands, testing, project structure, code style, git workflow and boundaries. They also put commands early, show examples instead of describing style, and spell out boundaries.

Section What to write Why it matters
Commands Exact install, build, test, lint, typecheck and format commands, including how to run a single test The agents.md FAQ notes that agents will try to run the checks you list and fix failures. Wrong commands produce confident, wrong verification.
Project layout Top-level folders and what lives where, entry points, generated code Saves exploration time and keeps edits out of generated or vendored code.
Conventions Only the ones a linter does not enforce: error handling, naming of domain concepts, where new modules go The things a newcomer gets wrong in review.
Examples One short snippet or a pointer to a file that shows the preferred pattern One real example beats a paragraph of description.
Boundaries Always do, ask first, never do The highest-value section. Agents are eager; tell them where to stop.
Git and PR rules Branch naming, commit message format, what a PR description must include Agents open PRs. Make them reviewable.
Definition of done The exact sequence of checks that must pass before the task is complete Turns "done" from a feeling into a command.
Gotchas Required services, environment variable names, flaky tests What costs a human an afternoon costs an agent too.

Rules that make instructions followable:

  • Imperative, specific, checkable. "Run pnpm test --filter api after changing apps/api" beats "make sure things are tested".
  • Commands in code spans, copy-pasteable, with the working directory if it matters.
  • Say why for surprising rules, so the agent does not "fix" them.
  • Prefer pointers over copies. "API conventions: see docs/api.md" keeps one source of truth.

4. What to leave out

Leave out Why Instead
Rules your linter or formatter already enforces Duplicates a deterministic check with a probabilistic one, and drifts when the config changes "Run pnpm lint --fix before finishing."
Secrets, tokens, internal URLs with credentials The file is committed and sent to model providers Name the variable (DATABASE_URL) and where developers get it.
Long essays on architecture or history Every session pays for it in context, and it buries the commands A five-line summary and a link to the design doc.
Stale instructions An agent will run a removed script and then "fix" the failure Test the commands in CI or review the file with each tooling change.
Personal preferences Not team rules Your global file, or a git-ignored local file.
Vague virtues "Write clean, maintainable code" changes nothing A concrete rule or an example file.

The context budget is real: Codex caps combined project files at 32 KiB by default, and every tool loads them on every session. A short file that is fully read beats a long one that is truncated or skimmed.

5. A realistic AGENTS.md

A root file for a TypeScript web app with a Python worker. Roughly 60 lines, commands first, boundaries explicit:

# AGENTS.md

## Project
Invoice app. `apps/web` (Next.js, TypeScript), `apps/api` (Fastify, TypeScript),
`workers/billing` (Python 3.12), `packages/ui` (shared React components).
Generated code lives in `packages/db/generated/`: never edit it by hand.

## Setup
- Node via `.nvmrc`, package manager is pnpm. Never use npm or yarn.
- `pnpm install`
- `docker compose up -d postgres redis` (tests need both)
- Copy `.env.example` to `.env`. Ask a maintainer for real values; never invent them.

## Commands
- Build all: `pnpm build`
- Typecheck: `pnpm typecheck`
- Lint and format: `pnpm lint --fix`
- Unit tests, one package: `pnpm test --filter api`
- One test file: `pnpm vitest run apps/api/src/invoices/totals.test.ts`
- Python worker: `cd workers/billing && uv run pytest -q`
- Regenerate DB client after editing `packages/db/schema.prisma`: `pnpm db:generate`

## Conventions
- Money is integer cents (`amountCents: number`). Never use floats for money.
- API errors: throw `AppError` from `apps/api/src/errors.ts`; do not return error objects.
- New API routes follow `apps/api/src/invoices/` as the reference example.
- Dates are stored in UTC and formatted only in `apps/web`.

## Definition of done
1. `pnpm lint --fix && pnpm typecheck`
2. Tests for every package you changed pass
3. New behavior has a test; bug fixes include a test that failed before the fix
4. Summarize what you changed and how you verified it

## Git and PRs
- Branch: `agent/<short-topic>`
- Commits: Conventional Commits (`fix(api): round tax per line item`)
- PR description: what, why, how verified, anything you could not verify

## Boundaries
Always:
- Run the definition of done before saying a task is complete
- Keep changes scoped to the task

Ask first:
- Adding or upgrading a dependency
- Changing `packages/db/schema.prisma` or any migration
- Touching CI config in `.github/workflows/`

Never:
- Commit `.env` files, keys or tokens
- Edit `packages/db/generated/` or `legacy/`
- Disable, skip or delete failing tests to make a run pass
- Push to `main` or force-push shared branches

No lint-enforced style rules, no history, no aspirations: every line is a command, prevents a known mistake, or defines done.

6. Monorepos: nested files

Put shared rules at the root and package-specific commands and rules next to the code:

repo/
  AGENTS.md                  # setup, global commands, boundaries, PR rules
  apps/
    web/AGENTS.md            # Next.js routing, UI test commands, Storybook
    api/AGENTS.md            # API conventions, integration test setup
  workers/
    billing/AGENTS.md        # Python toolchain, uv, pytest markers
  packages/
    db/AGENTS.md             # "schema changes need a migration and pnpm db:generate"

A nested file only needs what differs from the root:

# workers/billing/AGENTS.md

This package is Python, not TypeScript. Ignore pnpm commands from the root file here.

- Install: `uv sync`
- Tests: `uv run pytest -q` (integration tests: `uv run pytest -m integration`, needs Postgres)
- Lint: `uv run ruff check --fix . && uv run ruff format .`
- Types: `uv run mypy src`
- Currency math uses `decimal.Decimal`, never `float`.

Practical rules for nesting:

  • Do not repeat the root. Duplication wastes budget and drifts.
  • State overrides explicitly ("ignore the root test command here") instead of relying on the agent to infer it.
  • Start sessions in the package when the tool loads files by working directory (Codex), so the right file is on the path.

The agents.md site points out that, at the time of writing, the main OpenAI repository has 88 AGENTS.md files. Nesting scales; a single giant root file does not.

7. Tool compatibility (early February 2026)

Support changes quickly. This is what each tool's own documentation said as of early February 2026:

Tool Native file Reads AGENTS.md? Notes
OpenAI Codex AGENTS.md Yes, natively Global, root and nested files; AGENTS.override.md; fallback names; 32 KiB default cap.
GitHub Copilot coding agent .github/copilot-instructions.md, .github/instructions/*.instructions.md Yes, since August 2025 Nearest AGENTS.md takes precedence. Also accepts a single root CLAUDE.md or GEMINI.md.
VS Code (Copilot Chat) Same as above Yes, at the workspace root GitHub's docs note that AGENTS.md files outside the workspace root are off by default and need a setting.
Cursor Project Rules in .cursor/rules/ (.mdc), User Rules Yes Rules add scoping by path and manual invocation. .cursorrules is legacy.
Gemini CLI GEMINI.md (global, ancestors, subdirectories) Configurable Set context.fileName in settings.json to a list, for example ["AGENTS.md", "GEMINI.md"]. Supports @file.md imports.
Aider None by default Configurable Add read: AGENTS.md to .aider.conf.yml.
Claude Code CLAUDE.md (managed, project, user, local) plus .claude/rules/ Not listed in its memory docs Supports @path imports up to 5 hops deep. Bridge with an import or a symlink (below).
Others (Jules, Factory, Amp, Zed, Warp, Devin, Windsurf, goose, opencode, JetBrains Junie and more) Varies Listed as compatible on agents.md Check each tool's docs for nesting and precedence.

If your team uses a mix of tools, keep one source of truth and point the other files at it:

# Claude Code: a CLAUDE.md that imports AGENTS.md, plus anything Claude-specific
printf '@AGENTS.md\n\n# Claude Code specifics\n- Use /memory to check loaded files.\n' > CLAUDE.md

# Or a plain symlink when no tool-specific additions are needed
ln -s AGENTS.md CLAUDE.md

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

Prefer the import: symlinks can misbehave on Windows checkouts, and an import lets you add tool-specific notes without forking the main file. Verify once per tool by asking which instruction files were loaded (/memory in Claude Code and Gemini CLI).

8. Anti-patterns

Anti-pattern Symptom Fix
The wall of text Agent ignores rule 47 of 60 Cut to commands and boundaries; move the rest to linked docs or nested files.
Commands that do not run Agent "fixes" a missing script or reports a false pass Run every listed command in CI, or at least before merging changes to the file.
Restating the linter Rules drift from .eslintrc or pyproject.toml Tell the agent to run the linter instead.
Treating it as a guardrail A "never" rule is broken once and causes damage Enforce with permissions, sandboxing, branch protection and CI.
Five tool files with different content Agents behave differently per tool One AGENTS.md, others import or link to it.
Generated once, never read Draft lists made-up conventions Treat /init output as a draft.

9. Maintenance checklist

Treat AGENTS.md as code, because it changes how code gets written:

  • Review it in PRs like any other config. CODEOWNERS on the file is reasonable for larger teams.
  • Update it when the agent repeats a mistake. A correction you give twice in chat belongs in the file. A correction you give once probably does not.
  • Update it in the same PR as tooling changes.
  • Prune regularly. Delete rules that nobody can explain and rules the linter now covers.
  • Watch the size. If it approaches your tool's limit (32 KiB combined by default in Codex), split or trim.

Why this matters

  • Agents start from zero every session. The instruction file is the only onboarding they get, so its quality caps the quality of their work.
  • Verification beats description. Exact commands and a definition of done turn "looks right" into "the checks passed".
  • Boundaries save the most time. One "ask first" line about migrations is worth more than a page of style advice.
  • One file, many tools. With AGENTS.md now under neutral stewardship and read by most major agents, a single well-kept file serves the whole team regardless of tool.
  • Short and current beats long and complete. Every line costs context on every session, and a stale line is worse than a missing one.

Final Thoughts

AGENTS.md succeeded because it asks for almost nothing: a Markdown file in a known place. That simplicity is also the trap. It is easy to write one in five minutes, let an agent generate the rest, and never look at it again.

The teams that get the most out of coding agents treat this file like a build script: small, specific, tested, and changed in the same pull request as the thing it describes. Start with your commands and your "never" list, then let the agent's mistakes tell you what to add next.

Sources