CLAUDE.md: the note your coding agent reads first

1. What goes in

Five headings, one screen:

• What this is. Two lines. “A static site about AI for beginners. Live on Cloudflare.”
• How to run and check it. The exact commands. npm run dev, npm run verify.
• Conventions it cannot infer. Where content lives, which style guide is binding, which files are generated and must not be edited by hand.
• Rules. Never commit to main. Never touch the affiliate links. Ask before deleting.
• Lessons. Every time it gets something wrong and you correct it, add one line here. This section is the one that compounds.

2. What stays out

Anything it can read for itself: the folder structure, what each function does, the dependencies. Anything that changes weekly. Long explanations. If you are writing paragraphs, you are writing documentation, and that belongs in a separate file you point at.

3. Let it draft the first version

Open Claude Code in the project and paste this.

Read this project properly, then write a CLAUDE.md for it. One screen, five headings: what
this is, how to run and check it, conventions you could not have inferred from the code,
rules, and an empty Lessons section. Only include things that would change how you work.
If you are not sure something is true, leave it out rather than guess. Show me the file
before you save it.

Read it. Cut anything you would not have said yourself. Save.

4. CLAUDE.md vs AGENTS.md

Same idea, different reader. Claude Code reads CLAUDE.md. Codex and many other coding agents read AGENTS.md. If you use more than one agent on the same project, you do not want two copies of the same rules drifting apart.

What Anthropic’s docs say Claude Code does with them:

• Only AGENTS.md in the project: recent versions of Claude Code read it as the project instructions, so you do not need a CLAUDE.md at all.
• Both files: Claude Code reads CLAUDE.md and ignores AGENTS.md, unless you change the Project instructions setting in /config to read both.
• One shared file: put the real rules in AGENTS.md, and make CLAUDE.md a single line, @AGENTS.md, which pulls the other file in. Add anything only Claude needs below that line.

The third option works on every version, which is why it is the safest default. It is the same idea as the FAQ below: one file with the content, one that points at it.

How you know it worked. The next task starts without you explaining how to run the project. When it repeats a mistake you have already corrected, add one line to Lessons.