Files that instruct coding agents
A CLAUDE.md is a markdown file, and so is an AGENTS.md, a Cursor rule and an llms.txt. They are read by a model rather than a person, which changes what good looks like: shorter, more specific, and ruthless about what earns its place.
Start here
- CLAUDE.mdThe file Claude Code reads at the start of every session, and what belongs in it.
- Claude Code best practicesThe practices that follow from one constraint: context fills, and quality drops as it fills.
- AGENTS.mdThe vendor-neutral instruction file, read by Codex, Cursor, Copilot, Zed and dozens more.
- Cursor rulesHow .mdc rules work, which frontmatter gives you which behaviour, and where AGENTS.md goes.
- llms.txtA markdown map of your site for language models. The exact format, and its limits.
- CLAUDE.md generatorWrite one from a short form, or paste yours and see what it is costing you.
Which tool reads which file
Checked against the vendors’ own documentation in August 2026. This part of the landscape moves faster than anything else on this site, so treat the date as part of the answer.
| Tool | Reads | Worth knowing |
|---|---|---|
| Claude Code | CLAUDE.md | Also CLAUDE.local.md, and any CLAUDE.md in a subdirectory you touch. Reads AGENTS.md only if you import it. |
| Codex | AGENTS.md | One of the tools the format emerged from. OpenAI donated it to the Agentic AI Foundation. |
| Cursor | AGENTS.md and .cursor/rules/*.mdc | AGENTS.md goes in the project root, as an alternative to the rules folder rather than inside it. The .mdc rules add path-scoped and on-demand loading. |
| GitHub Copilot | AGENTS.md | Plus its own .github/copilot-instructions.md. Not yet honoured by every Copilot feature. |
| Gemini CLI | GEMINI.md | AGENTS.md only if you ask for it, by setting context.fileName in settings.json. |
| Zed, Aider, Jules and others | AGENTS.md | Over 60,000 public repositories now ship one. |
The one rule underneath all of them
Everything in one of these files loads at the start of every session and stays there, competing with your actual conversation for the model’s attention. That single fact explains almost all of the advice you will read about them.
It is why the documented target is under 200 lines, why a directory tree is a bad idea when the agent can read the filesystem, why marking ten lines IMPORTANT makes none of them important, and why imports tidy a long file without making it cheaper. A rule that is not being followed is usually not a rule that was written badly. It is a rule that was written on line 340.
The practical test: for every line, ask whether the agent could work it out by reading the code. If it could, cut it. What is left is the commands, the conventions that differ from the defaults, and the decisions that live in someone’s head.
Why this is on a markdown site
Because these are markdown files, and the mistakes are markdown mistakes: a fence that never closes and swallows the rest of the file, a list that renders as one paragraph, a heading level that skips. The checker catches those, the generator catches the rest, and the viewer shows you what you actually wrote.