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.

Related