AGENTS.md

AGENTS.md is a plain Markdown file at the root of a repository that a coding agent loads whenever a session begins. It is the standing brief for the codebase: how to run the tests, which package manager to use, the conventions that matter, and the traps that have bitten before. Codex and a growing list of tools read AGENTS.md; Claude Code reads CLAUDE.md; Cursor keeps rules in a .cursor/rules directory. Same idea, different filename.

Because it is loaded every session, it is the cheapest way to fix a repeated mistake and the easiest file to bloat. Every line costs context on every request, and a file that grows into a full architecture guide starts crowding out the task. The other failure is silence: no file at all, so each session guesses the build command, guesses the style, and re-learns the same lesson you taught it last week.

Keep it short and operational. Commands first, then conventions, then gotchas, each as a line or two. For anything longer, point to a document instead of pasting it, and let progressive disclosure do the rest: the agent reads the deep doc only when the task needs it. Update it when the agent gets something wrong twice. It works alongside the system prompt, which the harness controls, and the memory system, which holds facts the agent writes for itself.