What Should Go in an AGENTS.md File?

A practical guide to giving coding agents clear repo rules so they stop guessing and making messy changes.

I tend to like the AI post where somebody shares a CLAUDE.md or repo rule file, says “these 21 rules changed everything,” and then the quote tweet count starts to explode.

I like those posts more than most AI productivity advice because they point to something real. A coding agent gets much better once it stops guessing how your project works. The model name, the filename, and the exact rule count are the forgettable parts.

That sounds obvious until you watch one work without any local guidance.

By default, a coding model knows a lot about syntax and just enough about software engineering to be dangerous in the same cheerful way a junior engineer with root access would be dangerous. It can produce code. It can explain code. It can also decide that your tiny bug fix is a great time to “clean up” three unrelated files, assume a requirement you never stated, and speak about its own uncertainty with the confidence of a generated release note.

This breaks for a simpler reason: missing local context. Your agent does not know what “done” means in this repo, which changes are out of bounds, which conventions are non-negotiable, or when it should stop and ask instead of making its own decisions.

That is what the instruction file is for.

Call it AGENTS.md, CLAUDE.md, repo rules, or a small pile of working notes. The name matters a lot less than the job. You are giving the agent an operating manual for this codebase so it can stop guessing its way through every task.

The four rules that pull the most weight

I do not think the magic number is 21. Four rules do most of the real work.

1. Ask instead of assume.
   If requirements are unclear, the agent should surface the ambiguity instead of silently choosing a path. Wrong confidence is more expensive than one extra question.

2. Start with the smallest working change.
   Agents love broad cleanup because it gives them more surface area to look helpful on. That rarely means the task is going well, so I would strongly prefer small, reversible diffs.

3. Do not touch unrelated code.
   Most teams do not mind extra polish in theory. They mind it very much when a review gets slow because the assistant “also improved” files nobody asked about.

4. Flag uncertainty before acting.
   A decent agent should know the difference between “I found the bug” and “I have a plausible theory.” The second state is fine. Hiding it is not.

Those four rules are bigger than any one model. They are the difference between an assistant and an intern who keeps rearranging your desk while answering the wrong question.

What the file is really doing

I think of a good agent instruction file as a boundary-setting document. Its job is to reduce four common failure modes.

Scope drift
The agent starts on a bug fix, notices a naming inconsistency, then notices an outdated helper, then notices a nearby refactor opportunity, and suddenly your one-line change reaches much farther than it should. A rules file tells it what “stay in scope” actually means here.

Bad defaults
Every model comes with habits. Some over-explain. Some rush to code. Some make confident assumptions to keep the turn moving. Some will happily take a destructive action if you did not explicitly say “ask first.” If you do not set the defaults, the model will.

Decision loss
Longer sessions get weird because the model forgets which trade-offs were already settled. You said no refactor. Later it proposes one. You said keep the old API. Later it “improves” it. This is where a tiny memory stack helps more than another clever prompt.

Polite nonsense
This is my least favorite failure mode. The model has partial evidence, but it keeps writing as if it has a proof. A good working agreement makes uncertainty a first-class output, not an embarrassment to hide.

That is why the screenshot-style rule sets often split into three buckets: defaults, behavior, and memory. I think that split is sane, and I would keep it.

What to put in a generalized AGENTS.md

If I were writing one file meant to survive changing models, I would keep these sections.

Defaults

This is where you define the repo’s normal operating mode.

• Keep changes narrow and task-focused

• Prefer the simplest fix that works

• Match existing style unless the task is explicitly a redesign

• Ask before destructive actions

• Explain what changed in plain language

• Do not invent requirements, APIs, or test results

Defaults matter because they catch the moments when the prompt is too short to say all of that again.

Behavior

This section tells the agent how to work, not just what to produce.

• Restate the task in concrete terms before making major changes

• Confirm assumptions when they change behavior or risk

• Show diffs or summarize edits clearly

• Stop if the new plan expands beyond the original ask

• Keep the user in the loop before irreversible steps

This is about visibility, not ceremony. Most people can tolerate an agent being wrong for a turn. They get annoyed when it is wrong and quiet about it.

Memory

This is the part many teams skip, and for me it is where a lot of the quality gain comes from.

Your agent does not just need rules. It needs a place to pin decisions that should survive the next twenty turns.

• DECISIONS.md for active trade-offs and chosen direction

• KNOWN_ISSUES.md or ERRORS.md for failures already observed

• SESSION.md for where work stopped and what should happen next

• Permanent facts for “never rename this endpoint” or “this file mirrors an external contract”

You do not need all of these in every repo. You just need enough memory to stop paying for the same rediscovery loop over and over.

Escalation

This is where the agent learns when to slow down.

• Ask when two paths have different product consequences

• Ask when requirements conflict with existing constraints

• Ask before deleting, renaming, or migrating broad surfaces

• Say when confidence is low

• Prefer a question over a fake conclusion

If you only add one behavioral rule, make it this kind of rule. A coding agent that escalates well is dramatically easier to trust.

A template I would actually use

Here is a generalized version I would be comfortable dropping into a project root today:

# AGENTS.md

## Goal

Help with this repository by making the smallest correct change that solves the
requested task.

## Defaults

- Stay within the requested scope
- Prefer the simplest working fix over broad rewrites
- Match existing code style and project structure
- Do not edit unrelated files just because they could be improved
- Ask before destructive or irreversible actions
- Do not claim tests passed unless you actually ran them
- Do not invent requirements, endpoints, configs, or results

## Working style

- Restate the task briefly before major edits
- Surface assumptions when they affect behavior
- Show what changed and why
- Keep diffs easy to review
- Stop and ask if the task expands into a refactor or redesign

## Uncertainty

- Flag low-confidence conclusions explicitly
- Prefer "I need to verify X" over guessing
- When there are multiple reasonable paths, present the trade-off

## Memory

- Read `DECISIONS.md` before making architectural changes
- Read `KNOWN_ISSUES.md` before debugging recurring failures
- Update `SESSION.md` with current status when work stops mid-task
- Treat pinned project facts as constraints, not suggestions

## Guardrails

- Never hide uncertainty behind polished wording
- Never change public contracts without calling it out
- Never mix requested work with opportunistic cleanup unless asked

That file is boring, which is exactly what you want here. The best rule file in a repo is usually the one that prevents avoidable messes, not the one that sounds smartest on social media.

This is really about interface design

What I like about these rule-file experiments is that they quietly move the conversation away from model hype and back toward engineering.

Better outcomes do not come only from upgrading the model. You also get them by improving the interface between the model and the project. A local instruction file, a short decision log, and a few explicit escalation rules can do more for day-to-day quality than another round of “which coding assistant is winning this week.”

That is also why I would generalize the idea well beyond Claude.

AGENTS.md is a better mental model than CLAUDE.md if you want something durable. Models change. Product names change. The failure modes stay stubbornly the same. Every coding agent needs help with scope, defaults, uncertainty, and memory. If your team solves those once in versioned text, you do not have to solve them again from scratch every time a new assistant shows up with a shinier demo.

The real win

For me, the win is simpler than “21 rules made the model smarter.” The model stopped having to guess what kind of teammate it was supposed to be, which is a much more useful improvement anyway.

If you use coding agents seriously, give them a local operating manual. Keep it short, keep it opinionated, and keep it honest about boundaries. Then add just enough memory that the same wrong turn does not have to be rediscovered every Tuesday.

For me, that is just good interface design for a very fast, very eager collaborator.