AGENTS.md: what to put in it, with a free template

What AGENTS.md is

A coding agent starts every task knowing nothing about your project. AGENTS.md is where you tell it what a new teammate would need on day one: how to run the tests, what the folders hold, what must never happen. The people behind the format call it a README for agents.

It is an open format, not one company's file. It came out of work by OpenAI, Google, Cursor, Amp and Factory, and the Agentic AI Foundation, part of the Linux Foundation, now looks after it. The format's site lists more than 20 tools that read it, among them Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Jules, Devin, Windsurf and Zed, and says over 60,000 open-source projects carry one.

There are no required fields. It is ordinary Markdown: use the headings you like, and the agent reads the text. That is from agents.md, checked on 11 November 2026.

Where the file goes, and how Codex reads it

For most agents the answer is one line: put AGENTS.md at the root of your repository. A big project can add one inside a subfolder, and the file closest to the code being changed wins.

Codex, OpenAI's coding agent, reads the files in a fixed order when a run starts:

Three details save an afternoon of confusion:

• Codex stops at a size limit. By default it stops adding files once they reach 32 KiB together, about 32,000 characters of plain English. The files closest to your work come last, so they are the first to be left out.
• It reads once per run. Changed the file? Start Codex again.
• It walks down, not up. Codex reads from the repo root to the folder you start it in, at most one file per folder, and stops there.

The order, the limit and the override file are from OpenAI's Codex docs on AGENTS.md, checked on 11 November 2026.

What to put in AGENTS.md

My test for a line: would I have to say it again in the next task? If yes, it goes in. In practice that comes down to five parts.

1. How to work. Think before coding and say what you assume. Ask when something is unclear. Change only what the task needs. Prove every change with a test.
2. The commands. How to run the app, the tests and the formatter, exactly as you would type them. An agent that finds test commands in the file runs them and fixes what fails.
3. Where things live. One line per important folder, so the agent doesn't guess.
4. The rules that protect production. No commits straight to the main branch. No secrets in code. The test coverage below which the build fails.
5. Where the details are. Point to your docs instead of pasting them: "Before you change the logs, read docs/logs.md."

Write every rule so it can be checked. "Run npm test before committing" works. "Test your changes" doesn't, because the agent can't tell when it has done enough.

An AGENTS.md template

This is the shape of the file I start a project with. Replace the parts in angle brackets.

# AGENTS.md

## How to work
- Think before coding. State your assumptions. If something is unclear, ask.
- Simplicity first: the least code that solves the task. No features nobody asked for.
- Change only what the task needs. Don't reformat or "improve" other code.
- Prove each change: write a test that fails, then make it pass.

## Commands
- Run the app: <command>
- Run the tests: <command> (they must pass before every commit)
- Format: <command>

## Where things live
- <folder>: <what is in it>
- docs/: read the doc for an area before you change it

## Rules that protect production
- Never commit to main. Every change: branch, commit, pull request.
- Never put secrets in code, logs or this file.
- Test coverage under <N>% fails the build.
- Tools or libraries not in docs/stack.md: ask first.

## Code Review Rules
- Flag any change that reads or writes customer data without a test.
- Flag a new dependency that docs/stack.md doesn't list.

## Answer format
1. What is done. 2. What is not done. 3. What must be done next.

The Code Review Rules heading is one Codex looks for: when it reviews a pull request on GitHub, it applies the rules under that heading in the AGENTS.md closest to the changed code.

The full rules, with the 16 chapters they point to (stack, tests, security, releases and more), come with the free playbook for Codex. The rules are about 6 KB, roughly a sixth of what Codex reads by default. The chapters are far larger, so they live in a skill that Codex opens only when a task needs it: see how Codex skills work.

How to check that Codex loaded it

Don't assume. Ask Codex from the root of your repository:

codex --ask-for-approval never "Summarize the current instructions."

It should repeat your rules back, the ones from your home folder first and the project's after them. If a rule is missing, the usual causes are an empty file, an AGENTS.override.md somewhere above, or the size limit.

Mistakes to avoid

• Everything in one file. Past the size limit your most specific rules drop out without a warning. Keep the file to what every task needs, and move long procedures into skills.
• Vague rules. "Write clean code" gives the agent nothing to check. Say what clean means for you.
• Rules that contradict each other. A rule in a subfolder beats the one at the root. Read the files together whenever your setup changes.
• A forgotten override. AGENTS.override.md is meant for a temporary change. Left behind, it hides the real file.
• Secrets. The file goes into the repository and into every run. Keys and passwords never belong in it.

AGENTS.md and CLAUDE.md

Claude Code reads CLAUDE.md. To keep one set of rules for every agent, write them in AGENTS.md and put a single line in CLAUDE.md: @AGENTS.md. A team can then use Codex and Claude Code on the same project without the rules drifting apart. More on that file in what to put in CLAUDE.md.

Questions about AGENTS.md

Next: Codex skills. All guides: articles.