AGENTS.md: What It Is and Which Coding Agents Read It

November 11, 2026 · 12 min read

AGENTS.md: What It Is, Which Agents Read It and How to Write One

AGENTS.md is a plain Markdown file in your repository that tells AI coding agents how to work on your project. It lists the commands that build and test the code, the conventions to follow and what to leave alone. Codex, Cursor, GitHub Copilot, opencode and Claude Code all read it, but each finds and combines the files differently.

What Is AGENTS.md For?

The project site at agents.md calls it a README for agents. Your README explains the project to people. The AGENTS.md file holds the details that would clutter it: setup steps, exact test commands, code style and pull request rules. Our README Markdown guide covers the human-facing side.

Unlike most config files, this agent Markdown file has no schema and no required fields. Any headings work, because the agent simply reads the text. The format is open: the spec repository on GitHub is MIT-licensed, and the site says AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation.

It's an ordinary .md file, so if you've never made one, creating a Markdown file takes a minute in any editor. Don't confuse it with llms.txt, which a website publishes for language models that read the site. If that's what you need, our llms.txt generator builds one.

Where Does the AGENTS.md File Live? Root, Nested and Global Files

Start with one AGENTS.md at the repository root. In a monorepo, you can add more files inside packages. Agents that support nesting then apply the file closest to the code they're editing, on top of or instead of the root one. The project site says the main OpenAI repo had 88 of them at the time of writing.

my-app/
├── AGENTS.md            shared rules: package manager, CI, PR format
├── package.json
└── packages/
    ├── api/
    │   └── AGENTS.md    API only: database setup, test command
    └── web/
        └── AGENTS.md    web only: component conventions

This tree shows a root file for rules that apply everywhere, plus one file per package for rules that apply only there.

Some agents also read a personal, global file that applies to every project on your machine. Codex reads ~/.codex/AGENTS.md, or the same file in the folder set by CODEX_HOME. opencode reads ~/.config/opencode/AGENTS.md. These hold your own habits, such as how you like commit messages worded, and they never go into the repo.

Which Coding Agents Read AGENTS.md?

Most major coding agents read the file out of the box, and the rest need one config line. This table comes from each tool's own documentation as of November 2026.

AgentReads AGENTS.md by default?When there are several filesNotes
OpenAI CodexYesJoins every file from the project root down to your working folderAGENTS.override.md beats AGENTS.md in the same folder
GitHub Copilot cloud agentYesThe nearest file in the directory tree takes precedenceAlso accepts a single root CLAUDE.md or GEMINI.md instead
CursorYesNested files combine with parent folders, and the more specific one winsPlain Markdown with no metadata
opencodeYesCombines the global file with every AGENTS.md from your folder up to the project root, plus nested files as it reads codeVersion 2 reads only AGENTS.md, with no CLAUDE.md fallback
Claude CodeYes, in recent versionsReads files above your working folder at start, subfolder files as it opens files thereSkipped when a project CLAUDE.md or CLAUDE.local.md exists
Gemini CLINo, it reads GEMINI.mdJoins every context file it findsAdd AGENTS.md to context.fileName
AiderNoLoads only the files you listAdd read: AGENTS.md to .aider.conf.yml

Copilot and Cursor also have their own instruction formats, .github/copilot-instructions.md and .cursor/rules, but AGENTS.md works in both without them. The agents.md site lists more tools that support it, including Jules, Factory, Zed, Warp, VS Code, Devin, Junie, Amp and Windsurf. If you need the tool-specific formats, our guides to Copilot instructions and Cursor rules cover them.

For Gemini CLI, list the file names in .gemini/settings.json:

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

With this setting, Gemini CLI loads AGENTS.md as context and still picks up any GEMINI.md you already have.

How Agents Combine Several AGENTS.md Files and Settle Conflicts

No shared spec defines precedence, so the same tree of files can behave differently from tool to tool. Two models cover most agents.

Nearest file wins. The agents.md FAQ says the closest AGENTS.md to the edited file wins, and explicit prompts in chat override everything. GitHub Copilot follows this rule. Cursor merges a nested file with its parents and lets the more specific one take precedence, which has much the same effect.

Concatenate from the root down. Per the Codex docs, Codex starts at the project root, usually the Git root, and walks down to your current directory. It takes at most one file per folder and joins them with blank lines. Closer files land later in the prompt, so they win when instructions clash. Codex skips empty files and stops adding text once the combined size reaches project_doc_max_bytes, which is 32 KiB by default.

If your repo already uses another file name, Codex can treat it as an instructions file:

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

With this config, Codex checks each folder for AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md and .agents.md, in that order, and the size cap rises to 64 KiB.

opencode also concatenates its files and, per its docs, doesn't resolve conflicts between them. The upshot works under every model. Put shared rules at the root and package rules in the package, and never let two levels contradict each other.

What Should You Put in an AGENTS.md File? An Example You Can Copy

Put in what an agent can't work out from the code. That means install, build and test steps, the conventions you enforce in review, and folders it must not touch. Here's an AGENTS.md example for a small TypeScript monorepo:

# AGENTS.md

TypeScript monorepo: Next.js web app in packages/web, Node API in packages/api.

## Setup
- Use pnpm, not npm or yarn. Run `pnpm install` at the repo root.
- Node 22 is required (see .nvmrc).

## Build and test
- `pnpm turbo run build` builds everything.
- `pnpm turbo run test --filter=api` runs the API tests only.
- `pnpm lint` must pass before you commit.

## Code style
- TypeScript strict mode. No `any` without a comment explaining why.
- Named exports only. No default exports.

## Pull requests
- Title format: [api] or [web], then a short summary.
- Add or update tests for every behaviour change.

## Gotchas
- Never edit src/generated/. It's rebuilt from the OpenAPI spec on deploy.
- The API tests need Docker running for the Postgres container.

The one-line summary tells the agent where things live without a long file map. Setup states the non-default package manager, which agents otherwise guess wrong. Exact commands beat prose because the agents.md FAQ says agents try to run the checks you list and fix failures before they finish. The Gotchas section usually saves the most wasted runs. Deeper material, such as architecture notes, belongs in your regular Markdown documentation, with one line in AGENTS.md pointing to it.

Below is a starter version in a live editor, so you can see the headings and lists render. Edit it into your own file.

AGENTS.md

TypeScript monorepo: a Next.js web app and a Node API.

Setup

  • Use pnpm, not npm
  • pnpm install at the repo root

Build and test

  • pnpm turbo run test --filter=api
  • pnpm lint must pass before you commit

Code style

  • TypeScript strict mode
  • Named exports only

Pull requests

  • Title format: [api] Short summary
  • Add or update tests for every change

Do not touch

  • src/generated/ is rebuilt on deploy
82 words431 characters21 lines
Markdown

The preview shows how the file looks to a person browsing your repo. Agents read the raw text, not the rendered view, and nothing in our editor sends the file to them. When it looks right, download it as a .md file, rename it to AGENTS.md and put it at your repo root.

AGENTS.md vs CLAUDE.md: Keep One File for Every Agent

Claude Code has its own instruction file, CLAUDE.md, but recent versions also read AGENTS.md. The catch is that any project-level CLAUDE.md takes priority. According to Anthropic's docs, a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working folder or any folder above it makes Claude Code skip AGENTS.md. Your personal ~/.claude/CLAUDE.md doesn't count. Our CLAUDE.md file guide maps where each of those files lives.

If your project needs both files, keep AGENTS.md as the source of truth and import it at the top of CLAUDE.md:

@AGENTS.md

## Claude Code only
- Ask before running database migrations.

Claude Code pulls in AGENTS.md through the import, then reads the Claude-only lines below it. A symlink (ln -s AGENTS.md CLAUDE.md) also works, but Anthropic's docs recommend the import if anyone clones the repo on Windows. There, a committed symlink can check out as a one-line text file. Claude Code also ignores AGENTS.override.md, AGENTS.local.md and anything under .agents/, so Codex-style overrides don't carry over.

Starting from nothing? You can generate an AGENTS.md from a form. The tool renders AGENTS.md, CLAUDE.md, .cursorrules and .github/copilot-instructions.md from one project description in your browser. It doesn't scan your repository, so it only knows what you type in.

AGENTS.md Best Practices Backed by Evidence

Most advice about these files comes from experience, not measurement, but there's now a study. In "Evaluating AGENTS.md" (arXiv 2602.11988), Gloaguen and colleagues tested coding agents on SWE-bench tasks with LLM-generated context files, and on issues from repos that ship their own. Context files didn't generally improve task success, and they raised inference cost by over 20% on average. That held for generated and developer-written files alike.

Agents did follow the instructions. Repository overviews, though widely recommended, just didn't help. The authors conclude that the files are useful for specifying non-standard coding practices. That points to a handful of rules:

  • Write only what the agent can't infer. A non-standard package manager, an unusual test command or a generated folder earns a line. "This is a React app" doesn't.
  • Commands over descriptions. pnpm turbo run test --filter=api is unambiguous, while "run the relevant tests" isn't.
  • Skip long file maps. Paths go stale as code moves, and the study found overviews didn't help.
  • Nest instead of growing one file. Package rules belong in that package's own AGENTS.md.
  • Update it when an agent repeats a mistake. A recurring error is the clearest sign of a missing line.
  • Hard rules need real guardrails. Claude Code's docs describe instruction files as context, not enforced configuration, so block risky actions with the agent's permission or hook settings. For Claude Code, our Claude folder structure guide shows where those settings live.

We prefer a hand-written root file that fits on about one screen, with package files for the rest. That's our habit, not a rule from any spec. The limitation is real too: no shared standard covers precedence or size, so test your file in each agent your team actually uses.

Should AGENTS.md Be Committed to Git?

Yes, commit the repository's AGENTS.md. It's team documentation, like a README, and opencode's docs tell you to commit project instruction files. Everyone, human or agent, then works from the same rules, and changes go through review.

Personal preferences belong in the global files, which live outside the repo. For a temporary change in Codex, an AGENTS.override.md takes priority over AGENTS.md in the same folder, so delete it when you're done. One trap: in Claude Code, adding an uncommitted CLAUDE.local.md for your own notes stops it reading AGENTS.md, unless you change its Project instructions setting.

Never put secrets, tokens or private URLs in the file. Anyone with access to the repo can read it, and so can every agent you run there.

A good AGENTS.md is short and specific: commands the agent can run, conventions it can't guess and folders it must leave alone. Start with one root file, add package files only where a package truly differs, and check how each of your agents loads them. Draft and preview yours in the editor, then save it as AGENTS.md at the root of your repo.