AGENTS.md

AGENTS.md is a file placed in a project's environment that a coding-agent harness loads into the context window automatically at the start of every session. It works as the project's standing brief to the agent. Matt Pocock's AI Coding Dictionary (aicodingdictionary.com), a glossary of agentic-coding terms open-sourced on GitHub, documents it as a cross-harness convention: several harnesses read a plain AGENTS.md, while some also support their own variant, such as Claude Code's CLAUDE.md.

The file exists because the underlying model is stateless. A correction given in one session is gone in the next, so without a shared file a person ends up repeating the same facts to every fresh session: that the project uses pnpm, that tests need a particular flag, that a directory is generated and should not be touched. Once an agent has been corrected for the same thing twice, the dictionary treats that correction as a candidate line for AGENTS.md. Suitable content is whatever the agent cannot derive by reading the code itself: build and test commands, non-obvious conventions, and hard constraints. The intended register is a short, declarative brief, not documentation.

The trade-off is that everything written into AGENTS.md loads on every turn of every session, whether or not that session's task needs it. A long file costs tokens and dilutes itself, since the more instructions sit in context, the less reliably a model follows any single one of them. The dictionary's stated fix is to keep content that applies everywhere in AGENTS.md, and move anything narrower, such as a style guide, behind a skill or a context pointer that loads only when a task calls for it.