What to Put in AGENTS.md (With a Real Example From My Repo)

You ask an AI agent to add a contact form endpoint. It creates a Next.js API route. Looks great, builds fine, and then does absolutely nothing in production, because the site is a static export and API routes don't exist there.

The agent isn't dumb. Nobody told it.

That's the problem AGENTS.md solves. It's a plain Markdown file at the root of your repo, written for AI coding agents instead of humans. Codex, Cursor, Jules, Zed and a growing list of other tools look for it automatically. Claude Code reads its own CLAUDE.md, but that file can simply point at AGENTS.md, so you only maintain one.

I've kept one in this site's repo since January. Here's what I've learned about what goes in it, what doesn't, and the one mistake that cost me the most.

README vs AGENTS.md

Your README explains the project to a person who's deciding whether to use it. AGENTS.md explains the project to someone who's about to change it.

Different reader, different content. A README says "run npm install and open localhost". AGENTS.md says "never hardcode the domain, use absoluteUrl() from src/lib/site.ts, because the sitemap and RSS feed both depend on it".

That second kind of sentence is the stuff that normally lives in a senior developer's head and gets passed on through code review. An agent has no access to any of it unless you write it down.

What actually belongs in it

After a lot of trial and error, mine boils down to five kinds of information.

1. The stack, with versions. Not "React", but "Next.js 16, App Router, Tailwind 4, TypeScript everywhere". Agents trained on older code will happily write Pages Router patterns otherwise.

2. Hard constraints and the reason behind them. This is the most valuable part. The reason matters because it lets the agent handle cases you didn't list.

- Static export (`output: 'export'`). API routes do NOT run in
  production. Backend logic is PHP.

With the reason attached, the agent doesn't just avoid API routes. It also stops suggesting server actions, middleware and anything else that needs a Node server.

3. Where things live. A short map of the directories that matter. Agents waste a lot of time (and your tokens) grepping around a codebase they don't know.

4. The traps. Every project has a few things that look wrong but are deliberate, or look fine but break something. Mine include:

- Must use WordPress API v1.2. v1.0 omits active_installs.
- MDX: angle brackets compile as JSX. Write `git clone [url]`,
  not `git clone <url>`.
- Page-level openGraph objects REPLACE the layout's object
  wholesale. Define every field you need.

Each of those cost me at least one confusing bug before it went into the file. Now no agent repeats it.

5. How to verify work. The exact commands: type check, build, and whatever checks you run on the output. If npm run lint is broken, say so, or the agent will spend ten minutes trying to fix your ESLint config instead of the task you gave it.

What to leave out

Things the agent can figure out on its own in seconds. It can read package.json. It can see your folder names. Listing every component wastes space and goes stale fast.

Generic advice too. "Write clean code" and "follow best practices" change nothing. Every line should be something the agent would get wrong without it.

And secrets. Obviously. But I've seen API keys in these files, so it's worth saying.

The stale line that misled my agents

Here's the mistake I mentioned. Early on, this site deployed to a /freshstart/ subdirectory, so my AGENTS.md said exactly that, along with a rule about accounting for the basePath in every asset path.

Then the site moved to the domain root. I updated the config. I didn't update AGENTS.md.

For months, every agent session started by reading a confident, specific, wrong instruction. And because it sounded authoritative, agents trusted it over what the code actually said. It only came to light when an agent's own investigation of the deploy contradicted the file and it flagged the mismatch.

The lesson: a wrong AGENTS.md is worse than no AGENTS.md. Without the file, an agent at least reads the code. With a stale one, it believes you.

What I do now:

• Any commit that changes a constraint updates AGENTS.md in the same commit.
• The file has a "Last updated" line at the bottom, so stale sections are easy to spot.
• When an agent makes the same mistake twice, that's a missing line. I add it right away.

How long should it be?

Mine is a bit over 100 lines and I'd treat 150 as the upper end. Every line costs context in every single session, so density matters more than coverage.

A useful test: read each line and ask, "would an agent get this wrong without it?" If the answer is no, cut it.

A starter template

If you're starting from zero, this skeleton covers most projects:

# AGENTS.md

## Project
One paragraph: what this is and who it's for.

## Stack
Framework + version, language, styling, key libraries.

## Hard constraints
Rules that must never be broken, each with a one-line reason.

## Layout
The 5 to 10 directories that matter and what lives in each.

## Gotchas
Things that look wrong but are deliberate, and vice versa.

## Verify
Exact commands to type check, build and test.
Note anything that's currently broken.

Fill in the constraints and gotchas first. They're where the value is. The rest is supporting detail.

Is it worth the effort?

Honestly, yes. It takes an hour to write a good first version, and it changes how agents behave in your repo almost immediately. They stop suggesting things you banned months ago. They stop rewriting patterns you chose on purpose. They start acting like someone who read the onboarding docs.

Just keep it true. That's the whole job.

Keep Reading

• Git CLI Crash Course: From Zero to Version Control Hero: the commands worth documenting in your own AGENTS.md.

• Why I Still Prefer PHP in a JavaScript-Obsessed World: the backend half of this site's static-plus-PHP setup.