TL;DR
- An
AGENTS.mdis a file that tells your AI coding agent how a project works and which rules it must not break. - Most of them get ignored because they're written like a wiki page. Write it like instructions for a new colleague on their first day.
- What works: where things live, numbered rules with the reason next to them, one recipe for the most common task, and a checklist for when it's done.
- What doesn't: vague advice ("write clean code"), things the agent can read from the code anyway, and docs nobody updates.
- Every template I sell ships with one, and here's exactly how they're written.
Why I care about this file
I built 15 website templates with an AI coding agent, Claude Code, in about a week. (The whole story is here.) Two repositories, dozens of sessions, and the agent starting from zero every single time.
That's the thing people forget: your agent has no memory of yesterday. Every session, it opens the project like a new hire on day one. Whatever it knows about how your project works, it learns from what's written down. If nothing is written down, it guesses. And guessing is where the weird bugs come from.
Then there's the second reason. Every template I sell ships with an AGENTS.md, because most buyers won't edit a template by hand. They'll open it in Cursor or Claude Code and say "make the hero blue." That file is the difference between their assistant following the template's rules and their assistant quietly breaking them.
So I've written a lot of these by now. Let's dig in!
A quick caveat: this is how it works today
Everything in this post is how things work in October 2026. AI coding tools change every few months, and the rules have already changed more than once. A year ago, every tool wanted its own file. Now most of them read AGENTS.md, and even Claude Code reads it.
So take the file names and tool details with a pinch of salt. The thinking behind them should last longer: write down what the agent can't read from the code, and say why. That was good advice for onboarding human developers long before AI, and I don't see it going away.
What AGENTS.md is (and CLAUDE.md)
AGENTS.md is a plain markdown file in the root of a project. AI coding agents read it before they start working. It's an open convention, so one file works in most tools: Codex, Cursor, GitHub Copilot and others read it.
Claude Code has its own file, CLAUDE.md. You don't need two copies. My CLAUDE.md files have one line in them:
@AGENTS.md
That tells Claude Code to pull in AGENTS.md. One source of truth, every tool covered.
Note: Claude Code can now read
AGENTS.mdon its own, so a project with only anAGENTS.mdworks out of the box. But if there's also aCLAUDE.mdin the project, Claude Code reads that one instead by default. So if you have both, keep the one-line import. (Claude Code docs)
You can also have more than one. My templates have an AGENTS.md per edition, one for the HTML version and one for the React version, because the rules are different. A plain HTML site that has to open from a double-clicked file has nothing in common with a Next.js build.
When there's more than one, the closest file wins. Agents read the AGENTS.md nearest to the file they're editing, so a subfolder's file can add to or override the root one. Put the rules that apply everywhere in the root file, and the rules for one part of the project next to that part. Claude Code works the same way with CLAUDE.md: a subfolder's file loads when Claude starts working in that folder.
What to put in it
Every AGENTS.md I write has the same five parts. Here they are, with real pieces from Oda, an architecture studio template.
1. What this is, in two sentences
Start with what the project is and the one constraint that shapes everything else.
## What this is
A static, dependency-free landing page for an architecture studio:
`index.html` + CSS + classic JS. There is no build step and there must
never be one. The page must keep working when `index.html` is opened
directly from disk.
That last sentence does a lot of work. Without it, the first thing a helpful agent does is add a bundler.
2. Where things live
A map. Not every file, just the ones the agent needs to find to do its job, and where a change should go.
## Where things live
- Copy and structure: `index.html`, one SECTION banner comment per
section (Hero, Studio, Work, Process …).
- Design tokens: `assets/css/tokens.css`. Change values here, not in `main.css`.
- Shared helpers: `assets/js/kit.js` + `assets/css/kit.css` (vendored —
don't edit; call `kit.*` helpers instead of re-implementing).
See the pattern? Each line says where something is and what to do with it. "Change values here, not there." "Don't edit, call these instead." That's the part that changes the agent's behaviour.
3. Rules that must not break
This is the heart of the file. Short, numbered, and each one with its reason.
## Rules that must not break
1. No external requests: no CDNs, Google Fonts, analytics or remote images.
2. Classic scripts with `defer` only. Never `type="module"` or `import`:
they fail over `file://`.
3. Respect `prefers-reduced-motion`: new animations need a static
equivalent.
6. Exactly one `<h1>`; keep headings ordered, landmarks, the skip link
and `:focus-visible` styles.
8. Use existing tokens. If you need a new one, add it to `tokens.css`
with a comment. Text in the accent colour uses `--timber-ink` (large)
or `--timber-deep` (small), never `--timber`, which fails contrast.
Two things make these rules stick:
- The reason. "Never
type="module"" alone looks like a style preference, and an agent will happily trade a style preference for something it thinks is better. "They fail overfile://" is a fact it can't argue with. - Numbers. A numbered list is easy to point at. "You broke rule 2" is a much shorter conversation than explaining it again.
Rule 8 is my favourite kind of rule. It's oddly specific, and that's the point. The accent colour looks great, but it fails contrast on small text. Nothing in the code tells you that. Without the rule, the next agent would happily use it for a caption.
4. A recipe for the most common task
Think about what people will ask for most. For a template, it's "add a section." So the file shows exactly how a section is built in this template, with a snippet to copy:
## Adding a section in the template's style
Copy the Materials or People section as a starting point:
- Header: the ruled `.sec-head` with `(NN) Name`, a subtitle and the
next free sheet number.
- Layout: `.wrap` + the 12-column `.g12`; spacing comes from `.sec`.
- Headings: `.h2` with the last word in `<span class="dim">`.
- Reveals: `data-reveal="draft"` with `data-reveal-delay` in ms.
This is how a new section ends up looking like it belongs, instead of looking like the agent's idea of a section. Agents copy what they see. Give them the right thing to copy.
5. A checklist for "done"
End with what to check before calling the work finished.
## Before you finish
- [ ] No console errors. No horizontal scroll at 390px wide.
- [ ] The page still works opened from disk.
- [ ] Reduced motion shows a complete page.
- [ ] Keyboard: every control reachable, visible focus.
For a code project, the best version of this is one command. My React editions just say: run npm run check (lint, typecheck and build). If the agent can run it, it will, and it'll fix what fails before you ever see it.
What to leave out
Just as important. Everything in the file competes for the agent's attention, so every line has to earn its place.
- Vague advice. "Write clean, maintainable code." "Follow best practices." The agent already thinks it does. These lines change nothing.
- What the code already says. Don't list every component or explain what React is. The agent can read the code. Write down what it can't read: the intent, the constraints, the decisions.
- History. "We used to use X, then switched to Y." Unless the old way is a trap it'll fall into, leave it out.
- Secrets. No API keys, tokens or passwords. The file lives in the repo.
- Long essays. If a section needs paragraphs of background, put it in its own doc (I use
DESIGN.mdfor the design rationale) and link to it fromAGENTS.md.
I don't have a line count I aim for. Mine ended up between 46 and 102 lines, depending on how much the template does. The test I use: if a part needs paragraphs of background, it belongs in another file.
Common mistakes
Describing instead of directing
Compare these two. Describing:
The project uses design tokens for colours and spacing.
Directing:
Use existing tokens. If you need a new one, add it to `tokens.css`
with a comment. Never hard-code hex values.
The first one is true. The second one is useful. Write in the imperative: use, keep, never, change it here.
Rules without a reason
An agent weighs your rule against everything else it knows. A rule with a reason wins that fight. A rule without one often doesn't, especially when the agent has a "better" idea.
Writing it once and never touching it again
A stale AGENTS.md is worse than none, because the agent trusts it. If a file moved or a command changed, the agent follows the old map and gets lost confidently.
My fix: every time the agent makes a mistake, I ask whether a line in AGENTS.md would have prevented it. If yes, it goes in. Most of my best rules came from bugs.
Here's a real one. Every template's docs explain how to move a section, like the hero, into another site. On 26 September I had the agent actually do it: follow the steps word for word and move each template's hero into a separate test site with its own clashing styles.
It broke in four templates. In some, the hero's entrance waited for a signal from the preloader or the nav. Move the hero without them, and the headline never appeared. In another, the hero's buttons needed a different section to exist.
The fixes took minutes. The more important part was the new rule that went into every template's AGENTS.md:
9. Every section must start on its own. An entrance that waits for a
boot/intro signal must not rely on the preloader or the nav to
send it: call the fallback from the section's own effect as well.
Now every agent that adds a section, mine or a buyer's, knows about it before it makes the mistake.
Writing it all yourself
You don't have to. Ask the agent to write the first version after it has worked on the project for a while: "Write an AGENTS.md for this project: where things live, rules that must not break, how to add a section, and a checklist for done." Then review it like any other part of the product. Cut the vague lines, add the reasons, fix what's wrong.
That's how all of mine were made. The agent that built the template also wrote down how it built it, and I edited it.
A template you can copy
Here's the skeleton I start from. Fill in the brackets, delete what doesn't apply.
# AGENTS.md — [Project name]
Instructions for AI coding assistants working on this project.
Read this before editing.
## What this is
[One or two sentences. What it is, and the one constraint that shapes
everything else.]
## Where things live
- [Thing]: `path/to/file`. [What to change here, or what not to touch.]
- [Thing]: `path/to/file`. [...]
## Rules that must not break
1. [Rule]: [why].
2. [Rule]: [why].
3. [Rule]: [why].
## [The most common task]
[Which file to copy, which patterns to reuse, where the copy goes.]
## Commands
- `[dev command]` — [what it does]
- `[check command]` — run before you finish.
## Before you finish
- [ ] [Check]
- [ ] [Check]
FAQ
What's the difference between AGENTS.md and CLAUDE.md?
They do the same job. AGENTS.md is the shared convention most AI coding tools read. CLAUDE.md is Claude Code's own file. Claude Code also reads AGENTS.md now, but only when there's no CLAUDE.md. Simplest setup: put everything in AGENTS.md, and if you need a CLAUDE.md too, make it a single line, @AGENTS.md.
Where does AGENTS.md go?
In the root of the project. You can add more in subfolders when a part of the project has its own rules, like my templates' HTML and React editions. The agent reads the one closest to the file it's editing, so the most specific rules win.
How long should an AGENTS.md be?
As short as it can be while still covering where things live, the rules, the most common task and the checklist. Mine are between 46 and 102 lines.
Does my AI agent actually follow it?
Much better than without one, and much better when the rules come with reasons. It's not a guarantee. That's why the file ends with a checklist and, when possible, a command that checks the work.
Should I write it myself or let the AI write it?
Both. Let the agent write the first draft from the project, then edit it yourself. You know the decisions and the reasons. It knows the files.
Wrap-up
An AGENTS.md is the cheapest quality tool you have. Ten minutes of writing saves you from explaining the same thing in every session, and it keeps your rules alive after you've forgotten why you made them.
If you read this far, thank you! 🙏
Want to see a real one in action? Every no-code.supply template ships with an AGENTS.md, a DESIGN.md and a README.md, so your own AI assistant can edit it the way it was built. 🔥
