CLAUDE.md and AGENTS.md

What it isCopy Anchor Link

AGENTS.md is a community convention read by Claude Code, Codex, Cursor, Aider and others. Claude Code also reads CLAUDE.md. The file holds what an agent cannot infer from the code: how to run tests and the build, the project layout, naming and style rules that differ from defaults, and things to never do.

What belongs in itCopy Anchor Link

Commands (install, test, lint, run), architecture in a few lines, conventions that are not obvious, and sharp edges such as "do not edit generated files". Keep it short, since it is loaded into every session and each line competes for attention. When the agent makes the same mistake twice, add one line. Move long reference material into separate files and link to them so they load only on demand. Prune lines that stop mattering.

A worked example: a good fileCopy Anchor Link

Run: pnpm install, pnpm test, pnpm dev. Layout: app code in src/, tests in spec/. Conventions: functional components, no default exports. Never: edit src/generated, commit .env. Gotcha: tests need Docker running. Eight lines. Every line prevents a repeated correction.

How the file is usedCopy Anchor Link

When a session starts, the harness reads the file and puts its text at the top of the model's context. The model does not remember earlier sessions by itself. Each one begins empty, so this file is the main thing that carries project knowledge from one session to the next. The agent can still read the code itself. Because the text sits in the context window, every line uses space and competes with your actual task.

A second example: a file that makes things worseCopy Anchor Link

Imagine a file of 300 lines with the full history of the project, old decisions, and a tutorial for the framework. The agent now has to weigh all of it on every task. Important rules, like "never edit generated files", are buried. A shorter version keeps only what the agent cannot discover by reading the code: commands, traps and rules. The history can live in a docs folder that the file links to. Instructions in the file are also advice, not a lock. For a rule that must never break, use a permission setting or a hook.

What goes wrongCopy Anchor Link

Files go stale. A command in the file changes, nobody updates it, and the agent keeps running the old one. You will see errors about a missing script or a wrong folder. Contradictions cause trouble too: one line says use tabs, another says spaces, and the agent may follow either. Over-long files lead to ignored rules.

How to tell it is workingCopy Anchor Link

Run a simple test. Start a fresh session and ask: "What commands would you run to test this project, and what must you never do?" The answer should match your file. If it guesses, the file is not being loaded or the wording is unclear. Then give the agent a real task and count how many corrections you make. Add a line for each repeated correction and remove one that never matters.

Try it yourselfCopy Anchor Link

Write a file of ten lines or fewer for a project you own.

1. List the install, test and run commands.
2. Add one convention and one thing to avoid.
3. Start a new session and ask the test question above.

Expect the first answer to be mostly right and to reveal one missing line.

Common mistakeCopy Anchor Link

Pasting the whole architecture document. The file loads every session, so only keep what changes behavior.