Write It Down or Watch It Guess
After this, you can write the one file a coding agent reads before it touches your project, and know what that file cannot do.
A coding agent starts every session from nothing. It does not remember yesterday, your rules, or the folder you told it never to touch. Many coding agents read one plain file at the start: AGENTS.md, or CLAUDE.md for Claude Code. Write it once and you stop repeating yourself. Write it badly and it follows the bad version, carefully.
- Step 01
Say what the project is in three lines: what it does, who it is for, what it is built with.
Check: Paste only those lines into a fresh chat and ask for the project back in one sentence. It should match yours.
If it fails: It describes a different, more exciting project. Confidently.
- Step 02
List what it must never do, each one specific: a command, a folder, a file.
Check: Every line names something you could point at. "Be careful" names nothing.
If it fails: A rule nobody can check. It gets read, agreed with, and stepped over.
- Step 03
Write how it proves it is done: the exact commands that have to pass.
Check: Run them yourself, now. They pass.
If it fails: "Done!" with nothing run. You find out from a user.
- Step 04
Say where things live: one line for each folder that matters.
Check: Ask where it would put a new page. It names the right folder.
If it fails: A second copy of a file you already had, in a folder you did not.
- Step 05
Date it, and change it the day a decision changes.
Check: The date is recent, and the last thing you decided is in it.
If it fails: It follows a rule you dropped a month ago. Exactly as written.
The tools, from their own docs
- AGENTS.md
For: An open format: one plain file at the root of a repository, described as a README for agents. Its site lists more than twenty tools that read it.
Does not: Enforcing anything. It is a file the agent reads, nothing more.
As of 2026-10-01
- Claude Code (CLAUDE.md)
For: Read at the start of every session; it can read AGENTS.md instead when there is no CLAUDE.md.
Does not: Blocking an action. Its docs call these files context, not enforced configuration, and point to hooks for that.
As of 2026-10-01
- Cursor
For: Reads an AGENTS.md in the project root, or project rules in .cursor/rules as .mdc files.
Does not: Reading a plain .md file inside .cursor/rules. Its docs say that file is ignored.
As of 2026-10-01
Where this stops
A file is read, not obeyed. Claude Code's own documentation calls these files context, not enforced configuration. Anything that must never happen needs a check that runs outside the agent: a permission it does not have, a branch it cannot push to, a test that fails.