TL;DR
AGENTS.md is an open standard that lets you write your project's rules once and have most AI coding tools read them automatically — Copilot, Cursor, Kilo Code, Devin Desktop, Aider, and 30+ others. This article covers what goes in the file, what most guides skip, and the one popular tool that genuinely doesn't read it the way you'd expect.
The problem: instruction drift
If you use more than one AI coding tool, you've probably hit this.
You write a copilot-instructions.md for GitHub Copilot. A teammate uses Cursor, so you add a .cursorrules/ file with the same rules. Someone else is on Cline, so you add .clinerules/. Then your CI uses Codex CLI, so you write another file for that.
Six months later you have five near-identical instruction files, none of them agree, and updating a single convention means editing five places.
This is instruction drift — and it's the problem AGENTS.md was built to solve.
What AGENTS.md is
AGENTS.md is a plain markdown file that lives at the root of your repository. No YAML frontmatter, no special syntax, no schema to learn.
It was released by OpenAI in August 2025 and handed to the Linux Foundation's Agentic AI Foundation to steward as an open standard. By mid-2026, it had been adopted in over 60,000 open-source repositories.
Where a README explains your project to humans, AGENTS.md explains it to agents.
Who actually reads it (and who doesn't)
This is the part most AGENTS.md guides skip, and it matters before you write a single line.
Tools that read it natively (no setup required):
Cursor, Devin Desktop, Aider, Amp, OpenCode, Gemini CLI, Codex CLI, Kilo Code, GitHub Copilot, and 30+ others listed on the official AGENTS.md site. Copilot reads it straight from your repo root. Kilo Code has AGENTS.md support enabled by default.
The one honest exception: Cline
Cline's native rule format is .clinerules/ — its own folder, its own file structure. Project-root AGENTS.md isn't auto-detected the way it is in most other tools. Cline does read a global ~/.agents/AGENTS.md, but that's separate from your per-project file. This isn't a bug — it's just how Cline works today, and it's worth knowing before you assume one file covers everything.
What to actually put in the AGENTS.md file
Here's a real example for a Next.js project:
# AGENTS.md
## Project
Next.js 16 e-commerce storefront with a Postgres database.
App Router, TypeScript, Tailwind CSS, shadcn/ui, Prisma ORM, deployed on Vercel.
## Architecture
- `/app/` — Next.js App Router pages and layouts
- `/components/` — shared UI components, named exports only
- `/app/api/` — REST API routes
- `/lib/` — utilities, db client, auth helpers
- `/db/` — Drizzle schema and migrations
## Commands
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
- Lint: pnpm lint && pnpm tsc --noEmit
- Build: pnpm build
## Conventions
- Server components are the default — add "use client" only when strictly necessary
- All form validation uses Zod
- TypeScript strict mode — never use `any`, prefer `unknown` for external data
- Named exports only, no default exports in components
- Absolute imports via `@/` alias, never relative paths across modules
## Hard constraints
- Never modify files in `/db/migrations/` without explicit approval
- Never commit `.env` or `.env.local`
- Never use `useEffect` for data fetching — use server components or TanStack Query
- API endpoints without authentication must be explicitly marked as public in a comment
Why each section matters
Commands are the highest-value section. They eliminate the most common agent mistake: using npm when your project uses pnpm, or running pytest when you're on vitest. Every tool needs to know how to install, run, test, and build your project.
Conventions need to be specific, not vague. "Use functional components" is not a convention — it tells the agent nothing actionable. "Named exports only, no default exports in components" is a convention the agent can check every file it writes against.
Hard constraints should use the word "never". Not because there's a mechanical distinction between sections — the agent doesn't parse your headers. What it does is weight explicit negatives more heavily than preferences. "Named exports only" is a preference. "Never use default exports" is a stronger signal. Same idea, different weight.
What the research actually says
A February 2026 ETH Zurich study (Gloaguen et al.) tested context files across 138 real GitHub tasks. The finding cuts against what most guides assume: context files in general often reduced task success compared to no context file at all. Hand-written files were the exception — a modest 4% improvement on average.
The catch: even that gain came with up to 19% more steps and token cost, because the agent did more work before acting. Auto-generated files from /init performed worse than nothing in most settings tested.
The takeaway isn't "skip the file." It's: write less, write only what the agent can't already discover from reading your code, and write it yourself rather than generating it.
Keep it under 200 lines
Anthropic's own Claude Code documentation is explicit: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. The same principle applies to AGENTS.md — past a certain length, rules toward the bottom get proportionally less weight. If you're overflowing, the content belongs in a skill or a scoped instructions file.
Treat it as public
Don't paste real API key formats, don't include example tokens that look real, don't document your internal auth secrets. Write where secrets live — ".env.local, never committed" — and stop there. Treat the file as if it could leak, because it might.
Three patterns most AGENTS.md guides skip
1. Nested files — closest wins
Most developers think AGENTS.md = one file at the root. It doesn't have to be.
Per the official agents.md specification, the agent reads the file closest to whatever it's editing — closest wins, root file is just the fallback. OpenAI's own Codex repository ships 88 separate AGENTS.md files across its directory tree.
my-project/
├── AGENTS.md ← global rules: stack, commands, conventions
└── packages/
└── legacy-service/
└── AGENTS.md ← overrides: "use yarn here, not pnpm"
You don't need 88 files for a side project. But the moment one part of your codebase genuinely has different rules — a legacy package, a vendored folder — drop a second AGENTS.md there instead of cramming exceptions into the root.
2. A Context Budget section
Agents don't know when to stop reading. Left alone, they'll open your entire schema.prisma, every constants file, files they don't need — burning context and time before writing a line of code.
Tell them how to search instead:
## Context Budget
- Search for the relevant symbol or route before opening a full file
- Read the file that defines something before files that only consume it
- Don't re-read files already in context unless they may have changed
- Avoid loading large generated or schema files in full unless the task needs it
3. A Fast Routing Map
A table directly in AGENTS.md mapping task type to exact file path:
## Fast Routing Map
| Need | Read first |
|----------------|------------------------------------------|
| Auth logic | `lib/auth.ts`, `lib/auth-client.ts` |
| DB schema | `prisma/schema.prisma` (sections only) |
| Server actions | `server/actions/` — search symbol first |
This eliminates an entire category of hallucinated file paths. The agent stops guessing where things live and starts checking the map first.
One Codex CLI-specific feature (not universal)
If you're on OpenAI's Codex CLI specifically, there's an AGENTS.override.md file that takes priority over your regular AGENTS.md at the same directory level — useful for temporary situations like a release freeze without touching your real rules file. Codex CLI also caps context loading at 32 KiB by default, with the file closest to the current directory winning when the total exceeds the cap.
These are Codex CLI-specific behaviors — not something Copilot or Claude Code do. Flagging explicitly so you don't go looking for them somewhere they don't exist.
A Definition of Done section
## Definition of Done
Before declaring any task complete, run in order:
1. pnpm tsc --noEmit
2. pnpm lint
3. pnpm test
Fix all failures. Do not declare done if any command exits non-zero.
One honest caveat: this section is advisory. The agent reads it and generally tries to follow it — it's not a guarantee, and a well-behaved agent can still skip a check it judges unnecessary. That's a bigger topic (hooks, enforcement mechanisms) for Part 2B.
Key takeaways
-
AGENTS.mdlives at your repo root. Plain markdown, no schema, no frontmatter. - 30+ AI coding tools read it natively. Copilot reads it directly. Kilo Code enables it by default.
-
Cline is the honest exception — its native format is
.clinerules/, not project-rootAGENTS.md. - The Commands section is the highest-value section. Get it right first.
- ETH Zurich research (Feb 2026, 138 tasks): hand-written files help modestly (+4%); auto-generated files tend to hurt. Write it yourself, keep it short.
- Nested AGENTS.md is real — closest file wins. OpenAI's Codex repo uses 88 of them.
- Add a Context Budget and Fast Routing Map — most guides skip these, they're the most useful sections for preventing wasted steps.
- Treat it as public. No real secrets.
What's next
Part 2B wires this into Claude Code's CLAUDE.md properly, Copilot's full toolkit (prompt files, custom agents, the shared skills folder that both tools read), and the honest state of MCP across every tool in your stack.
Link goes in here the moment it's live.
📺 Full course: AI Second Brain for Developers
Top comments (0)