How to write an AGENTS.md that coding agents actually follow

An AGENTS.md is a Markdown file in your repository that gives coding agents instructions for your project. A good one is short, specific, and backed by checks. The AGENTS.md format is read by many agents. Codex and Cursor read it, and Claude Code reads it when you have no CLAUDE.md.

Most agents load this file at the start of every session. That is useful, but it also means every line you add is paid for in every session. In this article, I show what belongs in the file, what to leave out, and why agents still ignore rules you wrote down.

What should go in an AGENTS.md?

Include things the agent cannot work out by reading your code:

  • How to build, test, and lint.
    Give the agent exact commands.
  • Conventions that are not obvious.
    Like naming rules or architecture boundaries.
  • Decisions that are specific to your project.
    Like which APIs are off limits in new code.
  • How to verify work.
    So the agent knows which check proves a change is done.

The third point is easy to overlook. In my own projects, one of my first rules was not to use Combine in new code, and to prefer Swift Concurrency over the old Dispatch Queue APIs. I do have agent skills for SwiftUI and Swift Concurrency, but a skill is generic expertise. It does not know what is allowed in my project. That is a project decision, so it belongs in AGENTS.md.

What should you leave out?

Leave out anything that is long, rarely relevant, or already discoverable:

  • Release notes, CI details, and deployment steps that only matter for some tasks.
  • Descriptions of code the agent can read itself.
  • Vague advice like “write clean code” that changes nothing.
  • Copies of documentation. Link to it instead, or load it only when a task needs it.

The reason is cost and accuracy. A long instruction file is re-sent with every call, and a crowded context makes it harder for the agent to find the rules that matter. A task that has nothing to do with releases should not carry release notes.

One huge AGENTS.md starts a session nearly full, while a slim AGENTS.md plus a docs folder that loads only when needed leaves room for the task.

Why does an AGENTS.md get bloated?

Because nobody maintains it for you. Mine got bloated more than once, even when I was already experienced. I often told my agent to “save what you learned in your agents file”. It did, but not with the idea of keeping it compact. After a while, I had a very large file full of notes.

The fix is simple. Start a fresh session and ask the agent to optimize the file and move sections into reference files that are only loaded when needed. Keep the core file short and let the reference files carry the detail.

Why do agents ignore my instructions?

Instructions in an AGENTS.md are suggestions. The agent weighs them against everything else in its context, and in a long session a single line has less influence.

It gets worse when the context is summarized. Imagine you tell an agent in the first session that a page must support both light and dark mode. The context fills up and gets summarized. If the summary drops that requirement, the next session builds a light-only page, and it will feel as if you already said it. Constraints that only live in a chat can disappear. Constraints that live in AGENTS.md, documentation, skills, or linters survive.

If a rule must always hold, do not rely on a sentence alone. Enforce it:

  • Run the check automatically with a hook or a pre-commit step.
  • Make the test or linter fail loudly when the rule is broken.
  • Give the agent the command that proves the rule holds, and require it to run it.

I explain how to set that up in validation loops for agent-written code.

A minimal example

# Project instructions

## Commands
- Build: `npm run build`
- Test: `npm test` (run before finishing any task)
- Lint: `npm run lint`

## Conventions
- API handlers live in `src/api/`. Do not call the database from components.
- Do not edit files in `generated/`.

## Done means
- Tests and lint pass.
- New behavior has a test.

It is short enough to be read every time, specific enough to change what the agent does, and tied to commands that prove the result.

AGENTS.md vs CLAUDE.md

AGENTS.md is the shared format. Codex reads it, and Cursor supports it in the project root and in subdirectories. Claude Code reads it too, but only when there is no CLAUDE.md in your working directory or any directory above it. If a CLAUDE.md exists, Claude reads that file and skips AGENTS.md. This needs Claude Code 2.1.277 or later, according to the memory documentation.

That gives you two clean setups:

  • Only an AGENTS.md.
    Claude Code, Codex, and Cursor all read it. This is the simplest option.
  • Both files.
    Keep the instructions in AGENTS.md and let CLAUDE.md import it, with Claude-specific lines below the import.
@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

A symlink from CLAUDE.md to AGENTS.md also works. Anthropic notes that Claude’s edit tools refuse to write through a symlink, and that a clone on Windows can end up with a one-line text file instead of your instructions. The import avoids both problems.

If you are still choosing between these tools, I compare how they handle instructions in what to compare when choosing an agentic coding tool.

Conclusion

A good AGENTS.md holds what the agent cannot discover itself, stays short, and is backed by checks for the rules that matter. Review it like code, because it grows quietly.

If you want a quick audit, the free token cleanup prompt checks whether you load unnecessary resources into context for every new task. For the full approach to instructions, validation, and context, join the waitlist for the AI Fundamentals course. Feel free to contact me or tweet me on Twitter if you have any additional tips or feedback.

Thanks!

Frequently asked questions

Does Claude Code read AGENTS.md?

Yes, with one condition. Claude Code reads AGENTS.md only when there is no CLAUDE.md in the working directory or any directory above it, and it needs version 2.1.277 or later. If a CLAUDE.md exists, Claude reads that file instead, so import the shared file with an @AGENTS.md line.

What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is a shared, tool-neutral format that Codex, Cursor, and Claude Code can read. CLAUDE.md is the file Claude Code prefers when it exists, and it is the place for Claude-specific instructions.

How do I use one instruction file for several coding agents?

Keep the instructions in AGENTS.md. If you also need a CLAUDE.md, start it with @AGENTS.md and add Claude-specific lines below the import. A symlink from CLAUDE.md to AGENTS.md works too, but Windows clones can end up with a one-line text file.

How long should an AGENTS.md be?

As short as you can make it while still covering the commands, conventions, and definition of done. The file is re-sent in every session, so every line is paid for again each time. Move detail into reference files that load only when needed.

Sources

AI Fundamentals is open

Lifetime access, a new module every week, and a certificate when you finish.

Get the course