📜One file to govern all your agents · master AGENTS.md

The exact moment you need it

The need shows up the day your project has rules and more than one artificial brain passes through it. Maybe you use Claude Code to build, another tool to review, and every so often you open Cursor or Copilot for something one-off. Or maybe tomorrow you switch agents to save credits. In every one of those cases there's knowledge that doesn't live in the code: how the environment is started, what command runs the tests, which folders are sacred and off-limits, how you want the save messages written. Today that knowledge lives in your head — and every new agent starts from zero, knowing none of it.

The pain it's born from · context that evaporates

The pain is silent and it's paid in installments. Today's session with your AI knows exactly how your project works because you spent hours explaining it. But that knowledge isn't saved anywhere: when you close the conversation, it evaporates. Tomorrow you open a new session — or switch models to spend less — and you're back at square one, repeating "remember the tests run with this command", "don't touch the payments folder", "commits go in this format".

Why does this happen? Because every agent starts out blind: it only sees your code, not your rules or your habits. And since each tool used to store its instructions its own way — Claude in one file, Cursor in another, Copilot in another — you had to keep the same knowledge written three or four times. A mess that desyncs on its own: you change a rule in one file and forget it in the rest.

What is AGENTS.md? (in plain terms)

AGENTS.md is a README for agents. Just as the good old README tells a human what your project is about, AGENTS.md tells any coding AI how to behave inside it. It's a plain-text (Markdown) file you drop in the root of your project, and that's it. No weird config, no code, no ceremony.

What makes it powerful isn't the format — it's that it became an open standard read today by more than 25 different tools: OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Google Jules, Aider, Zed, Windsurf, Devin, JetBrains Junie, Warp, goose and more. Over 60,000 open source projects already use it. You write your rules ONCE, and they work with the AI you use today and the one you use tomorrow. You stop being married to a single tool.

The real anatomy · what's inside

Here's the best news: there's no rigid format to learn. AGENTS.md is plain, ordinary Markdown — titles with #, lists with dashes, text. It doesn't need that technical header full of colons and braces (what programmers call YAML frontmatter): none of that is required. You write in sections named however you like, and the agent reads whatever you put there. Period.

That said, there are five blocks that nearly every good AGENTS.md includes — because they're exactly the knowledge that evaporates between sessions. Think of them as the five drawers of the job handbook:

The habit · write it once, keep it alive

This resource isn't one of those you apply every day — it's one you do well once and touch up now and then. The consistency here isn't in the frequency, but in two specific moments where you can't forget about it:

The nuance almost nobody explains · AGENTS.md vs CLAUDE.md vs .cursorrules

This is where people get tangled up, so let's be clear. Before the standard existed, every tool invented its own rules file: Claude Code reads a CLAUDE.md, Cursor read a .cursorrules, and so on. The obvious problem: if you used three tools, you maintained three files with the same knowledge, desyncing on their own. AGENTS.md was born precisely to end that mess: a single source of truth that all of them read.

# CLAUDE.md

# Project rules live in AGENTS.md (single source of truth).
# Claude Code loads them with this import line:

@AGENTS.md

# Below, only the Claude Code-specific stuff that does NOT apply
# to the other agents (if there's anything at all).

When to use which? Easy: AGENTS.md for everything you want any agent to obey (95% of your rules). A tool's own file (CLAUDE.md, .cursorrules) only for what's exclusive to that tool — a command only it understands, a setting only it can use. When in doubt, it goes in AGENTS.md. The mental rule: write for everyone by default; write for just one by exception.

Point & counterpoint · what if the spec already says what to build?

If you come from the idea of writing a specification before building (the what you want built), AGENTS.md is the other half of the pair — and they don't overlap, they complement each other. The spec governs WHAT gets built: the feature, the goal, the result. AGENTS.md governs HOW any agent behaves while building it: with which commands, what rules, what not to touch. One is the blueprint of the building; the other, the site's safety rules. You need both.

The master prompt · generate your perfect AGENTS.md

Here's the shortcut. You don't have to write the file by hand or think through every section: you give this prompt to your coding agent inside your project, and it drafts it for you by looking at how your code is actually built. You just review and adjust. Copy it as-is, fill the brackets with what you know, and let it work:

I want to create an AGENTS.md file in the root of my project: the "README for agents" from the open standard (agents.md) that AI coding tools read. It's plain Markdown, WITHOUT a YAML header. Guide me in simple language, assuming I'm not a programmer.

First, EXPLORE my project for real (look at the folder structure, the package.json or equivalent, and how it's organized) so you DON'T make anything up. Then draft an AGENTS.md with these sections, in clean Markdown:

1. Project overview — 2 or 3 sentences on what it is and what technologies it uses (deduce it from the code).
2. Set up the environment — the real commands to install and start the project from scratch.
3. How it's tested — the exact command for the tests and for the error/type check, so any agent verifies its work before calling it good.
4. Style rules — the code's language and the conventions you detect (quotes, names, formatting).
5. Commits and PRs — this is my commit message format: [describe it, or tell me if I don't have one and propose a good one].
6. Limits · what NOT to touch — mark these sacred folders/files as UNTOUCHABLE without explicit permission: [list the sensitive stuff here: payments, secrets, config, migrations… whatever you have]. Make it clear that an agent must STOP and ask before modifying them.

Rules for drafting it:
- Only state things you can verify by looking at my code. If you don't know something, put a [TO CONFIRM] marker instead of inventing it.
- Keep it concise and actionable, not a novel. An agent reads the whole thing before working.
- If my main tool already has its own rules file (for example CLAUDE.md), do NOT duplicate the content: make that file import AGENTS.md with a single line, and leave AGENTS.md as the single source of truth.

When you're done, show me the whole file and explain in one sentence what you put in each section, so I can review it.

The easiest path · by chat vs. by hand

As in the whole series, there are two ways to do this and neither forces you to touch the terminal if you don't want to:

If you go the manual route, here's the minimal template, ready to copy and fill in. Change it to your taste: remember there's no mandatory format.

# AGENTS.md

## Project overview
[What it is and what it's built with. 2-3 sentences.]

## Set up the environment
[Commands to install and start from scratch.]

## How it's tested
- Tests: [exact command]
- Error/type check: [exact command]
> Run this and get it green before calling a change done.

## Style rules
[Code language, naming/formatting conventions.]

## Commits and pull requests
[Your commit message format. Example of a good one.]

## Limits · do NOT touch without permission
- [Sacred folder or file 1 — why it's sensitive]
- [Sacred folder or file 2]
> For any of these: STOP and ask before modifying.

The golden routine · the summary you take away