How to write an AGENTS.md file for your AI coding agents

Your coding agent starts every session with total amnesia. It doesn't know that your tests need a flag, that the legacy/ folder is quarantined, or that you stopped using that helper six months ago. So it does the reasonable thing: it guesses, from whatever files it happens to read first.

Usually the guess is plausible. Sometimes it's a 300-line diff in a style you don't use, in a directory you didn't want touched. The fix isn't a better prompt. It's writing the house rules down once, in a file the agent reads before it does anything else.

What AGENTS.md actually is

It's a plain Markdown file in your repo root that AI coding agents read automatically at the start of a session and treat as standing instructions. There's nothing magic about it: the contents get prepended to the agent's context, the same as if you'd typed them yourself. The magic is that you only type them once.

Think of it as a README written for a reader who works very fast, never asks a second question, and takes everything completely literally.

The filename depends on the tool: Codex and a growing list of agents look for AGENTS.md, while Claude Code has long read CLAUDE.md. The conventions are still moving, so check your tool's current docs, but the content is portable. Worst case, keep one real file and make the other a single line pointing at it. In a monorepo, one file rarely covers it: give each package its own, and keep the root file for rules that are true everywhere.

What belongs in it

One test for every line: would a competent contractor on their first day need this to avoid an obvious mistake? If yes, it goes in.

• How to run things. The exact commands for install, dev server, tests, linter, build. Agents burn real time and tokens rediscovering that your test command isn't the default one.
• The shape of the project. Where code lives, what the top-level folders are for, and which directories are generated and must never be hand-edited.
• Conventions a random file won't teach. Naming, error handling, the patterns you actually use, especially where your codebase disagrees with the framework's defaults.
• Hard boundaries. Never edit a migration that already ran. Never commit straight to main. Don't add dependencies without asking. Absolute rules are where this file earns its keep.
• Your definition of done. Run the formatter. Update the tests. Keep the change scoped to what was asked.

Write it in short imperative sentences ("Use X." "Run Y before you finish.") not prose. You're writing config, not documentation.

What to leave out

This is the half most guides skip, and it matters just as much. Everything in this file is re-read at the start of every session and every task. It's rent, and you pay it constantly.

• Anything the code already says. Don't paste your file tree or restate your dependency versions. The agent can read package.json faster than you can keep a copy of it accurate.
• Aspirations. "We practice strict TDD" when you don't makes the file a liar, and an agent that catches the file lying starts trusting the rest of it less.
• Novels. If you can't skim it in a minute, the important rules are already buried under the nice-to-haves. Thirty to sixty lines covers most repos.
• Secrets. It's a committed file. Obviously.

Treat it like code, because it is

The good context files aren't written in one sitting: they accumulate. Every time an agent does something you have to undo, ask whether one line in this file would have prevented it, then add that line. Correcting the same mistake twice in chat is a bug you refused to fix.

That habit compounds quietly. Six weeks in, the file encodes the specific ways your project surprises people, and it should get shorter over time as you delete rules that stopped earning their place.

It's also the cheapest quality lever you have. A lot of what makes reviewing AI-generated code exhausting isn't bugs, it's stylistic churn, guesses that aren't wrong, just not yours. Move those guesses upstream and the diff arrives closer to what you would have written, which makes the review faster and more honest.

It matters more once you're running a fleet

One agent making one wrong assumption is a small correction. Several agents running in parallel making the same wrong assumption is four diffs drifting in four directions, each one plausible on its own. A shared context file is what keeps them consistent, the closest thing to a team style guide when most of the team is machines.

That's the workflow SanuDesk is built around. It's a desktop app where your Claude Code and Codex sessions tile into a single grid, each workspace pointed at a project folder, with a Kanban board the agents take their work from. The two briefs stack neatly: AGENTS.md is the standing brief for the repo, and the card you deploy from the board is the brief for this one task. The agent shows up knowing both the house rules and the job, and it drives the agent accounts you already pay for, so nothing here is metered by us.

The file pulls double duty for recurring automation, too. A Loop firing a nightly cleanup runs with nobody watching, so whatever guardrails live in your context file are the guardrails.

Start with ten lines

Don't try to write the perfect version. Open your repo, create the file, and put in the command to run your tests plus the two rules you'd tell a new contractor on day one. Commit it. Add a line every time an agent surprises you.

It's the highest-leverage ten minutes you'll spend on your setup this month: every session after it starts smarter than the last one did.

Download SanuDesk free and point a workspace at your repo, or see how the grid, the board and Loops fit together on the features page.