devtools.codes

What to put in AGENTS.md

Your tool input is processed locally in your browser and is not intentionally uploaded to our servers. Advertising and analytics providers may still process normal page, device, cookie and network information.

AGENTS.md is a place for facts an agent cannot infer from the code. That single principle decides most of what belongs in it.

Include the purpose of the project in a sentence or two, because an agent reading a repository sees what the code does but not what it is for. Include the commands a contributor actually runs — install, dev, build, test, lint — since these are rarely discoverable from the file tree and guessing wrong wastes a cycle. Include conventions that are not enforced by tooling: commit message style, export rules, the folder pattern you expect new code to follow. A linter already enforces what a linter enforces; write down what it does not.

Include constraints, which are the highest-value section and the most often omitted. These are the things that would be expensive to discover by breaking them: an external service that must not be called from tests, a migration requirement, a directory that is generated and must not be hand-edited.

Leave out what the repository already shows. File structure, dependency lists, a summary of what each module does, and a history of past fixes are all better read from the source, and they go stale quickly. An instruction file that repeats the codebase becomes wrong the moment the codebase changes, and a confidently wrong instruction is worse than no instruction.

Keep it short enough to be read in full. A file that runs to several thousand words competes for the same attention as the actual task, and the parts that matter get diluted. If a section is long, it probably belongs in a linked document rather than in the instruction file itself.

Finally, write it as instructions rather than description. "Use the repository pattern for data access" is actionable; "the project uses a repository pattern" is a fact an agent may or may not treat as a rule.

More on what to put in AGENTS.md

Where should AGENTS.md live?

At the repository root, in version control, alongside the code it describes. Agents look there first and contributors find it without being told. A monorepo can add a second file inside a package for rules that apply only to that package, but the root file should stay the one that holds project-wide facts.

How long should AGENTS.md be?

Short enough to read in full before starting work — for most projects that is one to three pages. Length is not the constraint so much as attention: an instruction file competes with the task for the same context, and the rules that matter get diluted by the ones that do not. Link out rather than inline.

Should I list the project structure in it?

No. The file tree is visible in the repository and a written copy of it goes stale on the first refactor, at which point the instruction file is confidently wrong. Describe only what the structure does not reveal: which directory is generated, which one must not be hand-edited, where new code of a given kind belongs.

Does AGENTS.md replace a README?

No, they address different readers. A README explains the project to a person deciding whether to use or contribute to it. AGENTS.md tells an agent how to work inside it. There is overlap in the commands section, and that overlap is the one place worth accepting a little duplication.

The tool behind this, and related guides