What is an AGENTS.md file

AGENTS.md is a Markdown file that tells coding agents how to work in a repository.

Think of it as a README for the agent. The README explains the product to people. AGENTS.md tells the agent which commands to run, which files not to touch, and which traps to avoid while it changes the project.

There is nothing special about the format. It is plain text in the repository root. What makes it work is that the knowledge lives next to the code, so every session reads it.

Durable repo memory is one habit that survived in what I learned using agentic AI.

Why the file exists

A new agent session starts with no memory of yesterday’s chat.

So it guesses the package manager, runs the wrong test command, edits a generated file, or misses a deployment constraint you explained last week. And you explain it again.

AGENTS.md is where those corrections go once, so you stop repeating them:

repeated correction -> durable rule -> every future task sees it

The agent spends less time discovering how the project works, and you spend less time fixing mistakes it did not need to make.

The free AI Fundamentals course explains how durable rules fit with prompts, context, tools, and verification.

Create the first file

Put AGENTS.md in the repository root.

Start small:

# Project instructions

## Setup

- Install dependencies with `npm install`.
- Run the development server with `npm run dev`.
- Run the complete check with `npm test`.

## Code

- Application code lives in `src/`.
- Generated files live in `dist/`. Do not edit them.
- Use two spaces for indentation.

## Before finishing

- Run `npm test`.
- Report any test you could not run.

That is already useful. The agent knows how to run things, where the code is, what not to touch, and what to do before it finishes.

You do not need to document the whole system. Add the facts that would otherwise cost the agent a wrong guess.

What belongs in AGENTS.md

An instruction earns its place when it is still true next month, when it is specific to this project, and when it tells the agent what to do rather than what to think about.

Commands that really work

List the exact commands an agent should run:

## Commands

- `npm run dev`: start the site on port 3000.
- `npm run check`: validate Astro and TypeScript.
- `npm test`: run the test suite.
- `npm run build`: build the production site.

Explain unusual requirements beside the command. If tests need Docker or a local database, say so.

Do not write “run the tests” when the repository has five test commands. Name the command that proves the change is safe.

A short architecture map

Point to the important boundaries:

## Architecture

- UI components live in `src/components/`.
- HTTP routes live in `src/pages/api/`.
- Database access goes through `src/data/`.
- Do not query the database from UI components.

That last line is the valuable one. A folder list the agent can discover by itself. A rule about which layer may call which, it cannot.

Project conventions

Record choices that cannot be inferred from the language:

## Conventions

- Use `npm`, not `pnpm` or Yarn.
- Keep public API errors free of internal details.
- Add a migration for every schema change.
- Add a 301 redirect when deleting or renaming a public page.

A formatter can enforce spacing. AGENTS.md should focus on choices a formatter cannot make.

Safety boundaries

State actions that need special care:

## Safety

- Never print or commit secrets.
- Never write to the production database from local tests.
- Do not deploy unless the user explicitly asks.
- Ask before adding a production dependency.

These lines are not a substitute for permissions or sandboxing. An agent can still ignore them. They tell a well-behaved agent what you consider dangerous in this project.

What does not belong

Do not put secrets in AGENTS.md. The file normally lives in version control and may be sent to an AI service with the task.

Do not put temporary status there:

- We are fixing checkout this week.
- Sara is reviewing pull request 42.
- The staging server is down today.

That information expires. Put it in a ticket, work log, or current task.

Do not copy entire manuals into the file. Link to stable project documentation when the agent only needs the detail occasionally:

## Deployment

- Follow `docs/deployment.md` for releases and rollback.
- Never force-push a release branch.

Do not fill the file with rules a tool already enforces. If Prettier or Biome formats the code, the agent does not need a bullet about indentation. Let the tool own it.

How scope works

Support differs between coding agents, so check the documentation for the tool you use.

Codex builds its instruction chain in two parts.

It first checks the Codex home directory, normally ~/.codex/, for global guidance. AGENTS.override.md wins when it exists. Otherwise Codex reads AGENTS.md.

It then starts at the project root and walks down to the current working directory. In each directory, it checks AGENTS.override.md before AGENTS.md and reads at most one instruction file. Instructions from deeper directories appear later, so they can override broader project guidance.

The combined project instructions have a size limit. Codex uses 32 KiB by default. If a large root file is approaching that limit, move detailed procedures into focused documents and link to them instead of assuming every line will be loaded.

This lets a monorepo define a general rule at the root and a narrower rule inside one package:

shop/
├── AGENTS.md
├── apps/
│   ├── storefront/
│   │   └── AGENTS.md
│   └── admin/
└── packages/
    └── payments/
        └── AGENTS.md

The root file might say:

- Use `npm` workspaces.
- Run `npm test` before finishing.

packages/payments/AGENTS.md can add:

- Treat amounts as integer minor units.
- Run `npm test --workspace payments` after payment changes.
- Never log payment payloads or webhook secrets.

Keep shared rules at the root. Add a nested file only when a subtree has genuinely different commands or constraints.

Some agents only read the root file. If a nested rule is critical across tools, keep a short version at the root and link to the detailed file.

Resolve conflicts deliberately

Instructions can disagree.

Imagine the root says:

- Use PostgreSQL for application data.

A nested test fixture says:

- Tests in this folder use SQLite. Do not replace it.

The narrower rule makes sense because its scope is clear.

Accidental conflicts are different. If one section says npm test and another says tests must never run locally, the agent has to guess which instruction is current.

Remove old rules instead of stacking exceptions on top:

- Run `npm test`, except in old projects, unless CI is active, but only...

When a rule needs that many conditions, move the logic into a script. Give the agent one command.

Write for execution

An agent reads the file to decide what to do next. A rule it cannot act on is noise.

Compare these two. The first sounds careful and changes nothing:

- Be careful with content.

The second tells the agent exactly what to check, and why:

- Before deleting an image, search `src/posts/` for references.
- A missing referenced image makes the production build fail.

Same problem here:

- Follow best practices.

Nobody knows which practices you mean. Name the choice:

- Validate request bodies at the route boundary with Zod.
- Return `400` for invalid input.

Short bullets work best. Add the reason only when it changes how the agent applies the rule, like the build failure above.

Include verification

Every important rule should have a way to check it.

For example:

## Content checks

- Run `npm run content:check` after editing posts.
- Run `npm run build` after adding images or internal links.
- Confirm future-dated posts do not link to later drafts.

Now the agent knows what to do and how to check the result. This catches changes that look done in the editor but fail during the build, like a post that links to a missing image.

Maintain the file from real mistakes

Do not try to predict every future problem.

Use a simple maintenance loop:

1. Notice a correction you had to repeat.
2. Decide whether it is durable project knowledge.
3. Put it at the narrowest useful scope.
4. Remove any older instruction it replaces.
5. Test it on the next relevant task.

Repeated corrections are strong candidates. One unusual task is not.

Review the file when commands, deployment, or architecture changes. A stale instruction is worse than a missing one because it sounds authoritative.

Common mistakes

The file gets long. Every rule seemed worth adding, and now the agent reads two thousand words before it looks at the task. Keep the main file short enough to scan, and move long procedures into docs/ with a link.

Preferences get written like hard rules. “Prefer small functions” is guidance. “Never run migrations against production” is a boundary. If every line sounds equally severe, the agent cannot tell which ones matter.

Facts stay in chat. You corrected the agent, it acknowledged, and the next session makes the same mistake. If a fact must survive a new session, it goes in the repository.

Commands rot. Someone renamed npm run check to npm run lint and nobody updated the file. Run each command yourself after adding it, and again when scripts change. A file with broken commands teaches the agent to ignore the file.

Tool-specific behavior gets written as if it applied everywhere. Nested-file discovery and precedence differ between agents. When something only applies to Codex or Cursor, say so.

How I use AGENTS.md

I use AGENTS.md as the memory of the repository.

I put the build commands there, but the most valuable lines are usually the strange ones: a configuration name that must match a hosted project, a folder that looks generated but is not, or a redirect rule that must stay at the end of a file.

Those facts are easy to forget after three months. They are also expensive for an agent to rediscover by breaking something.

I do not use the file as a daily to-do list. Plans and current work belong elsewhere. AGENTS.md is for the facts I still expect to be true next month.

It is a poor fit for product documentation meant for customers. If an agent needs the site’s actual content, I can point it at Markdown versions of the site or the source files. AGENTS.md tells it how to work, not what every page says.

A practical final template

Use this as a starting point:

# Project instructions

## Setup

- Install with `npm install`.
- Start development with `npm run dev`.

## Project map

- Application code: `src/`
- Tests: `tests/`
- Operational docs: `docs/`
- Generated output: `dist/` — do not edit.

## Rules

- Keep changes inside the requested scope.
- Never commit secrets or `.env` files.
- Ask before adding production dependencies.

## Verification

- Run `npm test` after code changes.
- Run `npm run build` after routing or content changes.
- Report skipped checks and the reason.

Delete the lines that do not apply, and add your own project facts as the corrections come up. That is the whole job of the file: the agent should not have to learn the same lesson twice.

Want me to talk about your product? You can sponsor this site.