Your AGENTS.md Should Be a Field Guide, Not a Constitution

There is a recognizable moment in the life of an AGENTS.md file. It begins as a useful page of setup commands and project quirks. Then an agent makes a mistake, so somebody adds a warning. Another mistake adds another warning. Six weeks later the file reads like the rulebook for a sport nobody enjoys playing.

That is understandable. It is also a sign that the file is being asked to do too much.

The useful job of AGENTS.md is orientation. It should tell an agent where it is, what matters here, how to verify its work, and which boundaries must not be crossed. It is not a replacement for tests, permissions, linters, or a well-shaped repository.

What is confirmed

Codex reads AGENTS.md before it starts work. The official documentation describes a layered system: global guidance is loaded first, project guidance is added from the repository root toward the current directory, and the closest file takes precedence. The default combined size limit is 32 KiB. That means placement and concision matter.

A June 2026 research paper gives the same idea a more rigorous shape. The authors tested repository guidance that was probed and refined against SWE-bench Verified tasks. Their refined guidance improved average resolution over both static guidance and no extra context. The improvement came mostly from better coverage and localization, not from making each individual instruction more forceful. The paper also favored compact artifacts and warned that its result came from one model and one benchmark setting.

A better shape for repository guidance

Start with the facts that are expensive for an agent to rediscover:

1. The command that installs dependencies.
2. The command that runs the relevant tests.
3. The location of the main application and important packages.
4. The files or directories that must not be edited.
5. The definition of done for visible behavior.
6. Any unusual local convention that is not obvious from the code.

Then stop. If a paragraph only says “be careful,” it probably belongs somewhere else. Good guidance gives the agent a concrete action or check.

For example:

## Verification

- Run `npm test` after changing shared utilities.
- Run `npm run test:e2e` after changing routing or forms.
- For visual changes, check 375 px, 768 px, and 1440 px widths.

## Boundaries

- Do not edit generated files under `dist/`.
- Never place credentials in committed config files.

That is short, local, and testable. It helps without pretending to be a complete policy engine.

My take

The best repository rules feel like notes from the person who knows where the floorboards creak. They are specific enough to prevent wasted work, but small enough that somebody will maintain them.

When the same warning appears for the third time, do not add a fourth sentence. Ask whether the repository can make the wrong action impossible or the right action obvious. A test is stronger than prose. A formatter is stronger than a preference. A permission boundary is stronger than “please do not.”

The goal is not to make an agent obedient to a long document. The goal is to make the project legible.

A rule worth copying

Keep AGENTS.md focused on navigation, commands, boundaries, and proof. Move enforceable rules into code, tests, hooks, or permissions.

Sources and further reading

• How Codex discovers AGENTS.md files
• The open AGENTS.md format
• Probe-and-refine research on repository guidance
• The AGENTS.md file used in the Codex repository

Related reading

• The Last Ten Percent Is the Product
• The Shift From Chat to Agentic Work