What Should Actually Go Into AGENTS.md?

Once a coding agent can inspect an entire repository, the next temptation is to explain everything to it.

That is where AGENTS.md becomes useful — and also where it is easy to overdo it.

At first I thought of it as a place for all the information an agent might possibly need. Architecture, commands, naming rules, deployment notes, project history, product decisions, edge cases. The problem is that if every detail goes into one permanent instruction file, the important rules eventually disappear inside a wall of text.

I now think about AGENTS.md differently. It should contain things that remain true across many tasks.

For example:

• how to run the project and tests;
• important repository structure;
• conventions that should always be followed;
• areas that should not be modified casually;
• unusual commands or environment assumptions;
• rules an agent would otherwise repeatedly get wrong.

Task-specific information does not belong there. If I am asking for one new feature, the details of that feature should stay in the task itself.

The distinction I use is simple: would I want every future agent working in this repository to know this?

If yes, it may belong in AGENTS.md. If it only matters for what I am doing today, it probably does not.

A good instruction file should reduce repetition without becoming a second codebase that also needs maintenance.