In short
AGENTS.md is a plain markdown file in your repo that tells AI coding agents how to work on the project: how to set it up, run the checks, where things live and the rules to follow. OpenAI Codex reads it for every task, and a growing list of other agents read it too. Below: the structure, a short example, and two complete templates: a full project file and a design rules section.
Updated
Where the file goes
Put AGENTS.md in the root of your repo. In a monorepo you can add more in sub-folders; the nearest one to the files being changed applies.
AGENTS.md template: structure
Overview
What the project is and the stack, in two lines.
Setup and checks
Install, build, lint and test commands. Agents run them to prove their change works.
Project map
Where routes, components and helpers live.
Code style and design
The conventions and design rules every change must follow.
Pull requests
How to scope a change and what to put in the description.
A short example
# AGENTS.md ## Setup and checks - npm install · npm run build · npm test (all must pass) ## Project map - app/ routes · components/ shared UI · lib/ helpers ## Rules - Reuse components before creating new ones. - One task per pull request.
Writing an AGENTS.md, step by step
Start with the commands. Codex runs tasks on its own and needs to know how to install, build, lint and test, because those commands are how it proves a change works.
Add a short project map and the conventions that are not obvious from the code: where components live, how data is fetched, how files are named.
Add design rules: the template to follow, the colour tokens, the type scale, and the rule to reuse components. Without them, each task invents its own UI.
Finish with pull request rules and a definition of done, so every task comes back scoped, checked and easy to review.
Keep AGENTS.md under review like code. When a task comes back with the same problem twice, add one line to fix it at the source; when a rule no longer matters, remove it so the important ones stay visible.
Ready-made AGENTS.md files
Complete files you can copy into your project and fill in. Each one works with the BrowserMoon design templates, so what the tool builds also looks professional.
Full AGENTS.md template
A complete AGENTS.md for a web app: overview, setup and test commands, project map, code style, design rules and pull request rules.
AGENTS.md (full project file)# AGENTS.md ## Overview [Product name]: a web app that helps [audience] [main outcome]. Next.js, TypeScript, Tailwind CSS, [database]. ## Setup and checks - Install: npm install
AGENTS.md design template
A design section for AGENTS.md. Codex reads it on every task, so each pull request follows your template and passes the same design checks.
AGENTS.md# Design rules for agents Every task that touches UI must follow these rules. Read design/template.html before you start. ## Design source of truth - Match the BrowserMoon template in design/template.html for fonts, spacing, colours, corner radius, shadows and components. When in doubt, open it and copy what it does. - Never invent a new style. If something is not in the template, use the closest thing that is.
Using AGENTS.md with a design template
Commit your design template to design/template.html and name it in AGENTS.md. Every Codex task then builds UI to the same design, even when tasks run in parallel.
Because Codex returns pull requests, design drift shows up in review; the AGENTS.md rules stop it before it starts.
SaaS landing page · Pricing section · Account settings · Analytics dashboard · Login page · Onboarding steps
Best practices
- ·Put the check commands near the top. Codex runs them before it finishes a task.
- ·Keep it short and specific; it is read on every task.
- ·Add a definition of done so agents know when to stop.
- ·If you also use Claude Code, keep CLAUDE.md and AGENTS.md in step, or point one at the other.
Common mistakes and how to fix them
No check commands
List install, build, lint and test commands so Codex can verify its work.
Writing it for people
Keep the README for people; AGENTS.md is direct instructions for agents.
No definition of done
Say exactly what must pass and what the PR description must include.
Out of sync with CLAUDE.md
If you use both tools, keep the rules the same, or have one file point to the other.
AGENTS.md vs CLAUDE.md
These files tell ChatGPT Codex how to work. A design template tells it what to build. Use both.
ChatGPT Codex templatesFrequently asked questions
What is AGENTS.md?
A markdown file in your repo with instructions for AI coding agents: setup, checks, project map and rules. Codex reads it on every task.
Which tools read AGENTS.md?
OpenAI Codex reads it, and many other coding agents support it too. Claude Code reads CLAUDE.md instead, so many teams keep both.
Where does AGENTS.md go?
In the repo root, with optional extra files in sub-folders for parts of a monorepo.
What is the difference between AGENTS.md and README.md?
README is for people: what the project is and how to start. AGENTS.md is for agents: exact commands, rules and a definition of done.
Should AGENTS.md mention the design template?
Yes. Name the template file and the design rules in AGENTS.md so every Codex task that touches UI builds to the same design without being told.
Can AGENTS.md include examples?
Yes. Short examples of the patterns you want, such as a component or a test, help agents copy your style. Keep them brief and link to real files for longer examples.
Does Claude Code read AGENTS.md?
Claude Code reads CLAUDE.md. Many teams keep both, or write the rules once and reference them from the other file.
Can AGENTS.md be in a sub-folder?
Yes. In a monorepo, the AGENTS.md nearest to the changed files applies.
How long should AGENTS.md be?
Short enough to read in full on every task, usually under 150 lines.
Should AGENTS.md include design rules?
Yes, if agents build UI. A design section is what keeps every task's UI consistent.
ChatGPT Codex templates by category
Related