Skip to content
vibespell

How to write an AGENTS.md file

What to put in AGENTS.md so coding agents follow your stack, commands, and boundaries instead of guessing.

What the file is for

AGENTS.md is a markdown file at the root of a repository. Cursor, Codex, Copilot, and a growing set of other coding agents read it before they edit. It is not a README. A README teaches a human how to use the project. AGENTS.md tells an agent how not to make a mess.

Keep it shorter than a style guide. Agents follow a one-page brief better than a twenty-page handbook. Lead with the stack, the commands that must pass, and the mistakes this codebase has already paid for.

What to include

Name the framework and the version assumptions that are easy to get wrong. Say where routes, domain logic, and tests live. List the exact commands for dev, test, and lint, and say what to do when the repo's script differs.

Write prohibitions as concrete lines. 'Do not fetch in useEffect when a server component can load the data' beats 'follow best practices.' Add a done-when list so the agent knows a green test or a named exception is part of the task.

What to leave out

Skip the company history, the product pitch, and rules you do not actually enforce. If the repo has no tests, do not demand a framework you will not review. Nested AGENTS.md files can override the root later for one folder. Start with one file.

Do it in this order

  1. 01

    Start from the stack

    Pick the framework you actually use and generate a first draft instead of a blank file.

  2. 02

    Replace the commands

    Swap in the package manager and scripts this repo really runs.

  3. 03

    Add three local bans

    Write the three mistakes agents repeat in this codebase.

  4. 04

    Start a fresh session

    Open a new agent chat and ask for a small change. Confirm it uses the commands you listed.

Questions

Where does AGENTS.md go?

At the repository root, named exactly AGENTS.md. A nested copy can narrow the rules for one directory.

Can I commit it?

Yes. Commit it so every collaborator and every agent session sees the same rules.

How is this different from a README?

The README explains the product to people. AGENTS.md constrains edits. Agents that read both still need the constraints in AGENTS.md.

Related