---
title: AGENTS.md
type: vocabulary
url: "https://www.envisioning.com/vocab/agents-md"
summary: "A file loaded automatically into a coding agent's context at session start, giving it the project's standing build, test, and convention brief."
year: 2025
generality: 0.45
---

# AGENTS.md

A file loaded automatically into a coding agent's context at session start, giving it the project's standing build, test, and convention brief.
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.

---
Source: Envisioning — Technology Research Institute (https://www.envisioning.com/vocab/agents-md)