Under the Nate Herk channel's interview with Matt Pocock, one commenter (3 likes) described the problem this post solves: getting the same project context to a coding agent, session after session, is "critically important (and extremely hard to get right)." Their custom systems kept failing. "I've spent so much time designing different systems to do this, but they all seem to fail some way or another." Another commenter on the same video described the fix in one line: "write that intent down once, next to the code, so every session starts from it instead of from zero."
The file that does this has a standard name now: AGENTS.md. This post covers what it is, what belongs in it, which file the agent reads when the project has several, and why a vague file still produces generic code.
What an AGENTS.md file is
AGENTS.md is a standard Markdown file that sits at the top of a project and holds the instructions a coding agent loads before it starts work. The agents.md site describes it as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." The format's FAQ says there are no required fields: plain Markdown, any headings you like.
The format came out of work by the teams behind OpenAI Codex, Amp, Jules from Google, Cursor, and Factory, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. The agents.md site counted more than 60,000 open-source projects using the format.
What goes in it
The agents.md guide suggests five sections: a project overview, build and test commands, code style guidelines, testing instructions, and security considerations. The test for anything else: would you tell a new teammate? Specific commands belong verbatim ("pnpm install", "pnpm test"), because an agent that has to guess the package manager may guess wrong. Style rules work best as concrete pairs: "single quotes, no semicolons" gives the agent something to follow and you something to check, where "write clean code" gives it neither.
Decisions fit in the file too. One questioner on the Pocock video asked whether anything still gets written down, "like a short list of decisions for the agent": what was tried and rejected, what the constraints are, what "done" means for this project.
Which file the agent reads
Under the agents.md convention, an agent reads the file closest to the file it's editing. A project with one file at the root works; a monorepo can put another AGENTS.md inside each package, and the nearest one takes precedence for that package. The agents.md site counted 88 of them in OpenAI's main repository. If a chat instruction contradicts the file, the chat wins: the site's FAQ says explicit user chat prompts override everything.
The same filename is the point of the format, but each tool loads it differently. Codex, Cursor, Jules, and Amp read AGENTS.md on their own; Gemini CLI reads it through a settings entry. Claude Code treats it as a fallback: in a project with no CLAUDE.md, version 2.1.277 (September 18, 2026) checks for AGENTS.md instead, a behavior you can toggle in /config that hasn't reached Claude Code's Bedrock, Vertex, or Foundry deployments yet. Check a tool's current documentation before relying on how it resolves these files, since support changes.
This Lab runs on the same pattern at smaller scale: our project repos carry instruction stubs. The one in this blog's repo, abridged:
# AGENTS.md (abridged)
- Brand: GWT Lab, at lab.greatwithtech.com
- Deploy: `bash deploy.sh` from the repo root
- Before touching content: read the brand voice files listed in the context map
- When done: leave a summary in this repo (PROGRESS.md or equivalent)
A coding agent starting in the repo without prior context picks up the deploy command and the content rules in one read instead of being re-told each visit.
Why a vague file still produces vague output
The file carries your instructions into each session; it can't make them specific. One commenter on the Pocock video described filling instruction files with their standards and watching the output stay generic: "I tell it I care about SOLID and DDD, with md patterns what to do, and what no... still building SLOP." SOLID and DDD are programming design principles, and as bare names they're instructions a model can't act on. The same idea rewritten as project-specific rules ("services never import each other's UI code", "one database query per page load") is checkable: the agent can follow it, and you can tell when it didn't.
The file is documentation, and documentation goes stale: when the agent repeats a mistake you already fixed by hand, move the fix into the file. And the file is instruction, not enforcement: chat prompts can override it, and a model can ignore it mid-task, which keeps your review pass on the job. Instructions inside a repo can carry attacks too; How to Tell If a GitHub Repo Is Safe to Run covers reading someone else's rules file before you trust it.
FAQ
Which AI coding tools read AGENTS.md?
Codex, Cursor, Jules, Amp, and Factory read it on their own. Gemini CLI reads it through a settings entry. Claude Code reads AGENTS.md only when the project has no CLAUDE.md, as of version 2.1.277 (September 18, 2026). The agents.md site keeps the current list, since tool support changes.
What's the difference between AGENTS.md and CLAUDE.md?
CLAUDE.md is Claude Code's own instructions file, and AGENTS.md is the cross-tool format. They hold the same kind of content: commands, conventions, project rules. If a project has both, Claude Code uses CLAUDE.md; projects built across several tools tend to keep one AGENTS.md and let Claude Code pick it up when no CLAUDE.md exists.
How long should an AGENTS.md file be?
Short enough that each line helps. The examples on agents.md run a page or two: commands verbatim, style as concrete pairs, the mistakes a new contributor might make. If a line restates what the model would do anyway, cut it.
Can AGENTS.md enforce a rule?
No. The file loads as instructions, chat prompts can override them, and a model can ignore the file mid-task. Tests, permissions, and your review are what enforce behavior: run the tests the file names, and read the changes against the style rules it lists.
Is AGENTS.md only for code projects?
The format targets coding agents, and that's where it's standardized. For chat tools outside a codebase, the same idea shows up as saved memory and custom instructions; How to Use ChatGPT Memory Effectively covers what ChatGPT keeps and what you control.
Want to go further?
Why Does AI Rebuild From Scratch? How to Get It to Improve What You Have covers getting edits instead of new builds, and What Is Context in AI? Why It Makes or Breaks Your Results covers what the model can see in a single session. To start, create an AGENTS.md at your project root with the three commands you run most and one style rule you're tired of repeating, then hand the agent a small change and check what it does with them.