May 2, 2026 · 8 min read

What is AGENTS.md, and why is every AI coder suddenly reading it?

In late 2025, OpenAI, Anthropic, GitHub, and Cursor quietly aligned on a shared file format their coding agents read automatically. It's called AGENTS.md. It's the biggest agent-tooling shift since GPT-4. And almost nobody is talking about it yet.

The problem it fixes

If you've used Cursor, Copilot, Claude Code, or ChatGPT for more than a weekend, you've felt this: somewhere around hour ten on a project, the AI starts forgetting what it built. It hallucinates folders that don't exist. It uses an old auth pattern you replaced last week. It reinvents a function that's already in /lib. New chats know nothing. You start over.

The reason isn't the model. It's that the model has no memory of your project. Every chat starts at zero. The clever fix the industry settled on is dumb in retrospect: put the project memory in a file. Tell the AI to read it first. Done.

What AGENTS.md actually is

An AGENTS.md file lives at the root of a project. It's plain Markdown. It contains the things a senior engineer would tell a new hire on day one — but written for an AI:

What the project is, who uses it, what it absolutely cannot break.
Folder structure: where models live, where routes live, where tests live.
The conventions: naming, error handling, logging, test style.
The tooling: package manager, build command, run command, lint command.
The forbidden list: old patterns, deprecated files, things "done" that must not be touched.

That last bullet is where most templates fail. Free AGENTS.md files online say "be helpful, write clean code." That's a horoscope. A useful AGENTS.md tells the AI what not to do — because that's the actual content of project-specific knowledge.

Who reads it

As of mid-2026, every major AI coding tool reads AGENTS.md or a sibling format automatically:

OpenAI Codex reads AGENTS.md on every session.
Claude Code reads CLAUDE.md (same idea, slightly different tag).
Cursor auto-loads .cursorrules and increasingly AGENTS.md.
GitHub Copilot reads .github/copilot-instructions.md.
Aider, Cline, Continue, Roo, and the long tail of indie agents all converged on AGENTS.md.

So the practical move is to ship all four formats — same content, four file names — so any tool a teammate uses Just Works.

What a good AGENTS.md looks like

Three rules:

Be specific. "Use modern patterns" is useless. "Server actions for mutations; never client-side fetch in a Server Component" is useful.
Forbid more than you allow. Models are good at default behavior. They fail when there's a project-specific exception they can't guess. Write the exceptions down.
Keep it scannable. 200–500 lines, headings, lists. The AI re-reads it on every session — long prose burns context.

How to write one in 30 minutes

Open your AI. Ask: "based on this repo, list 10 conventions a new contributor would need to know."
Throw out the obvious ones. Keep the project-specific ones.
Add a "Done — do not touch" list of files or features that are stable.
Add a "Modern patterns / forbidden patterns" section for whatever stack you're on.
Save it as AGENTS.md at repo root. Restart your AI. Watch it stop hallucinating.

Why a paid pack exists

Writing the first AGENTS.md takes 30 minutes if you know what you're doing. It takes a week if you don't, and the result is usually the "be helpful" template. Our pack ships hand-tuned AGENTS.md, .cursorrules, copilot-instructions.md, and CLAUDE.md files for the six most popular project types — Next.js, Astro, SvelteKit, FastAPI, Django, and Rails — plus four prompt templates (feature, bug, refactor, review). It's $19, one-time, with a 7-day refund. Skim the free Next.js sample first.