Ai CodingFoundational

AGENTS.md: The File That Stops You Repeating Yourself

What belongs in your repo instructions, what to cut, how to share one file across Claude Code, Cursor and Codex, and when a rule needs a real check behind it.

By Amit UpadhyayPublished 25 OctUpdated 29 Oct 20267 minArticle 2 of 3 in Ai Coding

A root AGENTS.md and a closer package file load in every session, skills load on demand, and rules that must hold are enforced by checks in CI.

On this page

The idea at a glance

The problem

When

Every agent session has to be told the same things about your repo

The obvious move

Correcting the agent by hand each time, or writing down everything you know

Fails because

Corrections disappear with the session, and a huge instructions file buries the rules that matter

The fix

AGENTS.md and repo instructions works by

A short AGENTS.md of exact commands, non-obvious rules and traps, with enforcement in tools for anything that must hold

At the cost of

A file to keep current, and the discipline to cut it back

The scenario every mode follows

“Add an endpoint for listing invoices”

A 12-person team with a pnpm monorepo, using Claude Code and Cursor
~60 agent sessions a week
claude-sonnet-5-5

Where the obvious approach breaks

60 sessions a week × ~5 repeated corrections each

If you no instructions file, so each person corrects the agent by hand.

The same mistakes recur: the wrong test command, edits to generated code, copies of the legacy pattern. The knowledge exists, but it leaves with each session.

Helps to know firstWorking with coding agents

You Keep Telling It the Same Thing

Every session starts the same way. You tell the agent the tests run with pnpm test:unit, not npm test. You tell it not to touch the generated client. You tell it the team stopped using the old repository pattern last year. Then a colleague opens a session and has the same conversation, and the agent still reaches for the old pattern, because it can see forty examples of it in the code.

Repo instructions are the fix, and they are the highest-value file you can add for coding agents. A small Markdown file at the root of the repo tells every session what a new team member would need on their first day. The difference from a README is the audience: it's written for an agent that can run commands, and it covers what humans pick up by osmosis.

You need this if

You repeat the same corrections in every session
Agents copy old patterns from your codebase
The team uses several different coding tools
Your instructions file has grown past the point where anyone reads it

AGENTS.md Is the Shared Format

AGENTS.md is an open format described as a README for agents, used by more than 60,000 open-source projects and now stewarded by the Agentic AI Foundation under the Linux Foundation. It has no required fields, because it is plain Markdown. Tools that read it include Codex, Cursor, GitHub Copilot's coding agent, VS Code, Gemini CLI, Jules, Windsurf, Zed, Devin and JetBrains Junie.

Claude Code uses CLAUDE.md first. From v2.1.277 it reads AGENTS.md directly when no CLAUDE.md applies, so a repo with only AGENTS.mdneeds no extra file. If you have both, keep one source of truth and import it, so the two can't drift apart:

<!-- CLAUDE.md -->
@AGENTS.md

## Claude-specific
Use subagents for broad codebase searches.

Some tools need a nudge. Gemini CLI takes "context": { "fileName": "AGENTS.md" } in .gemini/settings.json, and Aider takes read: AGENTS.md in .aider.conf.yml.

What Belongs in It

# AGENTS.md

## Commands
- Install: pnpm install
- Test one file: pnpm test:unit path/to/file.test.ts
- Before committing: pnpm lint && pnpm typecheck

## Rules
- Never edit src/generated/. Run pnpm codegen instead.
- New data access uses the query layer in src/db/queries. Do not copy the
  repository classes in src/legacy/.
- Migrations are additive. Removing a column takes two releases.

## Gotchas
- Integration tests need Docker running.
- The payments module has its own AGENTS.md. Read it before changing it.

## Pull requests
- Title format: [area] what changed
- Keep each PR to one change.

Every line should pass one test: would the agent get this wrong without it? Commands, things that look safe and aren't, and decisions that the code doesn't reveal all pass. “Write clean code” doesn't. Neither does a description of your folder structure, because the agent can read that itself.

Keep	Cut
Exact commands	General advice about good code
Rules with a reason the code doesn't show	What a linter already enforces
Traps specific to your repo	File-by-file descriptions
Pointers to deeper docs	The deeper docs themselves

Keep It Short

This file loads on every session, so each line competes for attention with the task. A 900-line instructions file is the same mistake as a bloated system prompt: the rule you care about is buried, and the model treats it as a suggestion. I try to stay under a couple of hundred lines. When a procedure only applies to some tasks, move it into an Agent Skill, which loads on demand.

In a monorepo, put another AGENTS.md in each package. The format's rule is simple: the closest file to the code being edited wins, and explicit chat prompts override that repo guidance, though not the higher-priority rules a tool sets for itself.


flowchart TD
    R["AGENTS.md at the root<br/>commands, global rules"] --> A["packages/api/AGENTS.md<br/>API conventions"]
    R --> W["packages/web/AGENTS.md<br/>UI conventions"]
    A --> P["packages/api/payments/AGENTS.md<br/>closest file wins"]
    S["Skills<br/>load on demand"] -.-> R

Make It a Rule, Not a Request

An instruction is advice, and agents will occasionally ignore it. If something must always happen, enforce it with a tool: a linter rule, a pre-commit hook, a CI check, or a harness hook. The instructions file can explain why the rule exists, while the check makes sure it holds. “Never commit secrets” in a Markdown file is a hope. A secret scanner in CI is a control.

What Goes Wrong

⚠️ Common Mistakes

1. Generating it and never reading it

Starting from a generated file is fine, but they tend to be long and generic. Delete everything the agent could work out by itself, then treat what is left like code.

2. Letting it rot

A stale command wastes a turn on every session, and a stale rule teaches the wrong thing with authority. Review it when your tooling changes, and let pull requests touch it.

3. Treating it as trusted when it isn't yours

The agent follows this file, so a poisoned AGENTS.md in a cloned repo or a dependency is a prompt injection with a head start. Read it before you run an agent in a repository you don't trust.

4. Fighting your own codebase

If the code shows forty examples of the old way, one line of instruction may lose. Point at the file that shows the right way, and migrate the examples when you can.

How to Tell Whether Your File Works

Most instruction files are never tested, so nobody knows which lines matter. There's a simple check. Pick a small, real task. Run it in a fresh session with the file, and again without it, and count the corrections you had to make in each. If the numbers are about the same, the file isn't earning its tokens.

You can test one rule the same way. Delete a line and run a task that depends on it. If nothing changes, that line was doing nothing, or the agent could already work it out from the code. Delete it for good.

Read your agent's session logs now and then too. They show where it wasted turns: running the wrong command, searching for a file you could have named, or trying something that was never going to work. Each of those is a candidate for one short line.

Secrets and sensitive paths

This file is committed, and it's sent to a model on every session, so it must never hold credentials, internal hostnames you'd rather not expose, or customer details. Say where things are, not what they are. If some paths must stay off limits, put that in your tool's permission settings, because a sentence asking the agent to keep out is only a request. Permissions enforce it.

For an open-source project, remember that contributors' agents read this file as well. A clear AGENTS.md raises the quality of the pull requests you receive, and that's a real benefit for maintainers.

What I Would Do First

Write down the last five corrections you gave an agent, and start the file with those plus your exact test and lint commands. That will likely fit in twenty lines, and it is better than most generated files. Then make a habit of it: when you correct an agent twice, add a line.

Decisions and trade-offs

The choices this rests on

Each choice has a reason and a point where it stops being right. The Test questions are built from these.

1
Include only what the agent would get wrong without it
Every line competes with the task for attention. Commands, traps and decisions the code does not show earn their place, and general advice does not.
Stops being right when
Never. If a line changes nothing, cut it.
2
Keep the file under about 200 lines, and move the rest out
It loads on every session. Length buries the important rules, so task-specific procedures belong in skills or docs.
Stops being right when
A very large repo may need more, but split it across packages first.
3
Keep one shared file and import it from tool-specific ones
Copies drift. A team on two tools ends up with two sets of rules, and each one is out of date in a different way.
Stops being right when
A rule really is specific to one tool. Put that one line in its own file.
4
Enforce anything that must hold with a check, not a sentence
An instruction is advice, and agents sometimes ignore it. A linter or CI check holds every time.
Stops being right when
The rule is a judgment call that no tool can check.

In production

Running it once real traffic arrives

What to watch, what it costs at the scenario’s volume, and what to check first when something goes wrong.

What to watch

Repeated corrections
The point of the file. Anything repeated belongs in it.
Falling
File length
Length creeps up one reasonable line at a time.
Under the limit
Stale commands
A wrong command costs a turn on every session.
0
Rules with no check
Anything critical should have a tool behind it.
Reviewed

What it costs

The file150 lines × ~12 tokens × 60 sessions≈ 108,000 tokens/week

At Sonnet 5.5 input108,000 × $2 per 1M, less with caching≈ $0.20/week

Corrections avoided60 sessions × ~5 minutes~5 hours a week

TotalCosts almost nothing, and saves hours a week

The bigger cost of a long file is lost attention, which does not show up on a bill.

When it breaks

The agent ignores a rule

CheckHow far down the file is it, and does the code contradict it?
FixMove it up, point at a good example, and add a check

Two tools behave differently

CheckAre they reading different files?
FixKeep one source and import it from the other

A session starts with a failed command

CheckHas the tooling changed since the file was written?
FixUpdate the file, and let pull requests touch it

In the real world

Twenty lines that replaced a wiki page

A composite of common team rollouts. The numbers are illustrative.

Before

A team had a long generated instructions file nobody read. Agents still used the wrong commands and copied old patterns.

What they built

Deleted everything the agent could work out by itself
Added the last five corrections people had actually made
Moved long procedures into skills
Added a CI check for the rule that mattered most

What changed

Repeated corrections became rare
New team members read the file too

The lessonThe best instructions file reads like a note from a colleague on your first day.

When not to use it

Reach for something else when

If you needUse instead

Procedures only some tasks needAgent Skills

Rules that must never be brokenA linter, a hook or a CI check

A repository you do not trustReading its instructions before running an agent there

Check yourself

Two questions before you move on

Answer in your head first, then open the answer.

Which line belongs in AGENTS.md: “Write clean code” or “Never edit src/generated/, run pnpm codegen”?

The second. It stops a specific mistake the agent would otherwise make. The first changes nothing.

In a monorepo, which AGENTS.md applies to a file being edited?

The closest one in the directory tree, and an explicit chat prompt overrides them all.

Where this leads

Reviewing agent-written code

Good instructions reduce mistakes. Review catches the ones that remain.

Next topic →

Next: See →

Sources

AGENTS.md CLAUDE.md coding-agents monorepo

← PreviousWorking With Coding Agents: The Loop That Holds Up Next →Reviewing Agent-Written Code: Green CI, Wrong Behaviour

Continue reading

5 min

Reviewing Agent-Written Code: Green CI, Wrong Behaviour

Agent mistakes are fluent, and their tests often confirm their bugs. A reading order that puts risk first, invented dependencies, fresh review sessions and review by risk.

6 min

Working With Coding Agents: The Loop That Holds Up

Getting code from an agent is easy. Getting code you can trust takes a way of working: explore, plan, implement, verify and review, with small diffs and a spec first.