AGENTS.md Best Practices That Actually Help Coding Agents

Most AGENTS.md files are bad in one of two ways.

They are either empty boilerplate that says things like "write clean code" and "run tests," or they are a junk drawer with half the team wiki shoved into the agent's mouth before the first prompt.

Both fail for the same reason. They waste startup context.

If you want AGENTS.md best practices that actually help coding agents, start with this: the file is not documentation. It is a behavior shaper. Its job is to change what the agent does in the next 30 seconds.

That sounds small. It is not.

A good AGENTS.md can stop an agent from pushing to main, skipping a backup before deletion, or looping on the same bad fix three times. A bad one can make the agent slower, more timid, and more likely to wander through markdown files instead of shipping the change.

I care about this because I am not talking about toy runs anymore. I have an agent stack that writes code, audits state, drafts blog posts, and runs scheduled jobs. That means my AGENTS.md is not a nice-to-have. It is a load-bearing file.

AGENTS.md best practices start with a brutal filter

Every line in AGENTS.md should survive three questions:

1. Will this change the agent's next move?
2. Could the agent infer this from the codebase on its own?
3. Is this still true today?

If the answer to the first question is no, cut it.

If the answer to the second question is yes, cut it.

If the answer to the third question is "mostly," cut it.

That last one matters more than people admit. A stale AGENTS.md is worse than no AGENTS.md because it lies with authority.

I got reminded of that again this week. A self-audit in my workspace found that some cron prompts still depended on an older blockers file path that had drifted out of sync with the real state. The work was still happening. The instructions were now partly wrong. That is exactly how agents do the wrong thing while sounding calm and competent.

So my first AGENTS.md best practice is simple: treat the file like a live control surface, not like documentation you wrote once and forgot.

What AGENTS.md is actually for

I think most people still frame AGENTS.md too loosely.

It is not a README. The README is for humans deciding whether they care about the repo.

It is not a full architecture guide. If the agent needs the details, it can go read the actual files.

It is not a diary of every team preference anyone has ever voiced.

It is onboarding notes for a sharp contractor who starts in ten minutes, has full tool access, and can break real things if you are vague.

That framing helps because it makes the scope obvious. You do not need to tell that contractor what TypeScript is. You do need to tell them not to touch production, which command proves a fix is real, and which folder hides the weird legacy code that will bite them.

That narrower job lines up with where the ecosystem is going too. The AGENTS.md standard is now used by tens of thousands of open source projects, and VS Code's custom instructions support is explicitly built around auto-loading repo guidance. That makes the cost of bloat real. If the file gets loaded all the time, every weak line is stealing room from something better.

In my own stack, I keep the root file focused by pushing identity, user context, and environment specifics into sibling files instead of stuffing all of it into AGENTS.md. The root file handles behavior. The supporting files handle personality, operator context, and machine-specific details. Same system, smaller blast radius.

The structure I actually use

After a lot of trial and a lot of cleanup, this is the structure I trust.

1. Hard rules

This is the highest-value section in my file.

Not principles. Rules.

Mine include lines like:

• never spend money without approval
• never push to main or production
• never delete files without creating a backup first
• stop after the same error three times
• never fabricate results

Those rules are not theoretical. They exist because each one closes a failure mode that costs real time or trust.

One of my favorites is the three-strikes rule. It sounds basic, but it changes agent behavior fast. Without it, an agent will often keep trying to redeem a bad plan because persistence feels productive. With it, the loop stops, surfaces the error, and hands back the artifact.

That is a much better failure shape.

2. Prove-it commands

The second section is the smallest set of commands that answer one question: how does the agent prove the work is real?

Build. Test. Lint. Typecheck. Maybe one repo-specific validation command.

Not every script in package.json.

The mistake I see all the time is people dumping a giant command catalog into AGENTS.md and calling it helpful. It is not. That forces the agent to choose from six nearly identical commands when what it really needed was one obvious validation path.

If the repo has one canonical build command and one canonical test command, put those in. If there are two genuinely different paths, explain when each applies in one sentence. Anything past that belongs somewhere else.

3. Repo map

The agent does not need your whole architecture document at startup. It needs a map.

Which directory owns product logic?

Which folder is shared utilities?

Where are migrations?

What part is safe to change and what part is legacy or scheduled for replacement?

That is enough to orient the first move. Once the agent knows where to look, it can read the code.

4. Current focus

This is the section most teams skip and the one I wish more people took seriously.

What is in flight right now?

What should not be refactored because it is about to be replaced?

Which branch of the codebase has active attention?

That context keeps an agent from doing the dumbest possible form of correct work: cleaning up the exact code you already decided to delete.

If you are working with long-running agents or scheduled jobs, this section does more than save time. It prevents contradictory work.

5. Footguns and repeated mistakes

This is where the file earns its keep.

I only add lines here when one of three things is true:

• the agent got it wrong already
• the correct move is not obvious from the repo
• the mistake is expensive enough that one sentence can save an hour later

A concrete example from my workspace: "Crons need deliver: true."

That line exists because silent cron jobs made Ray blind for days. That is not a style preference. That is operational memory compressed into one line.

Another is backup-before-delete. Again, not philosophy. It is a hard-won safety rail.

This is also where you put weird sequencing constraints, required file pairs, and hidden contracts the repo will not teach the model quickly enough.

What I cut from AGENTS.md

Here is the part people hate, because it means deleting writing.

Most of the file should not be there.

I cut:

• generic coding advice the model already knows
• long architecture rationale
• duplicated README content
• aspirational principles that do not cash out into behavior
• giant command lists
• secrets, tokens, or anything sensitive
• old project history that is interesting but not actionable

The easiest test is this: if the agent read this line and then opened the repo, would it make a meaningfully better decision because of the line?

If not, it does not belong.

This is where a lot of AGENTS.md best practices posts stay too polite. I do not think "include what matters" is enough guidance. You need a deletion instinct.

The file gets better when you remove 60 percent of it.

The research is finally catching up to the scar tissue

The reason I feel comfortable being opinionated here is that the outside evidence is finally matching what a bunch of us learned the messy way.

Augment published a good writeup recently on what makes AGENTS.md files help or hurt. The headline was blunt: a good AGENTS.md can act like a model upgrade, and a bad one can be worse than no docs at all. The useful parts of their findings matched what I have seen in real repos:

• progressive disclosure beats stuffing everything into one file
• procedural workflows help when the task is easy to get wrong
• decision tables help when the repo has two reasonable patterns and the agent needs one
• long sequences of "don't" rules without a clear "do this instead" cause over-exploration

That last point is worth underlining. Warning-only docs make agents cautious in all the wrong ways. If you say "don't do X," pair it with what to do instead.

The agents.md site also gets one thing right that people underuse: nested AGENTS.md files. Repo root for broad rules. Subdirectory files for local reality. That is a much healthier pattern than trying to make one monster root file cover every corner of a monorepo.

The biggest mistake I see

The biggest mistake is treating AGENTS.md like a place to dump values instead of a place to encode decisions.

"Write clean code" is a value.

"Run pnpm lint and pnpm test before you claim the task is done" is a decision.

"Be careful with deletions" is a value.

"Create a backup before deleting any file" is a decision.

"Use good judgment with autonomy" is a value.

"If the same error happens three times, stop and report what you tried" is a decision.

Agents work better with decisions.

Humans like values because they sound wise.

Machines do better when the wisdom has already been cashed out into a rule.

My practical template

If you want a starting point, keep it this small:

# AGENTS.md

## Hard rules
- Never push to main.
- Back up files before deletion.
- Stop after the same error three times.

## Validation
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Repo map
- src/app: routes and page shells
- src/features: feature logic
- src/lib: shared utilities
- db: schema and migrations

## Current focus
- Checkout flow refactor in progress
- Do not touch legacy export pipeline this sprint

## Footguns
- Update shared event types before client and server handlers
- New cron jobs must set deliver: true

That is enough to be useful.

You can grow it later, but only when a real mistake earns a new line.

How this fits with the rest of the agent stack

AGENTS.md is startup context.

It is not the whole workflow.

If you want the runtime half, that is where loops, validations, and state checks come in. I wrote about that in The Advanced Ralph Loop for Agentic Engineering. That post is about what happens after the agent starts moving.

This post is about the first move.

And that first move matters more than people think.

A lot of agent failures do not start with a model being dumb. They start with the model being loaded with vague, stale, or bloated instructions. That is the same lesson I ran into when my agent generated an app I had already built. The fix was not "use a smarter model." The fix was giving the system the right local reality before it acted.

AGENTS.md is part of that local reality.

My version of AGENTS.md best practices

If I had to compress my AGENTS.md best practices into one paragraph, it would be this:

Keep the file short enough that you can reread it in two minutes. Fill it with rules that change behavior, commands that prove work, maps that shorten the first search, and footguns the repo will not teach fast enough. Delete anything generic. Delete anything stale. When a line stops paying rent, cut it.

That is the whole game.

Not a manifesto. Not a team wiki. Not a place to sound thoughtful.

A small file that makes the next move better.

If your AGENTS.md has turned into a junk drawer, cut it in half this week. Your agent will probably get better immediately.