How to Write a CLAUDE.md (or AGENTS.md) That Actually Works
Every time you open a fresh AI coding session, it's like a substitute teacher walking into your classroom on day one with zero context. A CLAUDE.md (or AGENTS.md) is the note you leave on the desk before you're gone — and whether the day goes well depends entirely on what you wrote down.
The substitute teacher's note
Think about what you'd actually leave for a substitute covering your class. Not a philosophy of education — a practical note: here's where we are in the textbook, here's the one student who needs extra patience, here's the rule about phones, and please don't let them watch a movie instead of teaching the lesson. A vague, lofty note gets ignored the moment things get busy. A specific, almost boring note gets followed exactly.
An AI agent opening your repo is that substitute. It has never seen your project before this exact session — it doesn't know your file conventions, your don't-touch list, or what "finished" actually means for you. Whatever isn't written down, it will guess at, and the guess is often wrong in a way that costs you real time to undo.
What actually belongs in it
Four things matter, roughly in this order:
Who it's serving and what the project is. One or two sentences, no more. "This is the Infinite Offer Engine — a $1 product that sells AI-ready Context Files telling a buyer's AI tools how to build their offer, funnel, pages, and launch." That single sentence stops the agent from making generic assumptions about what "the product" means.
Where things actually live. The real folder layout, the naming pattern for new files, and one worked example of "when you add X, it goes in Y, following the pattern in Z." Point at an actual existing file as the example — agents copy patterns far more reliably than they follow abstract descriptions.
The guardrails. Your don't-touch list, stated plainly: don't touch pricing, don't touch the database schema, don't touch the payment or checkout flow unless explicitly asked. Say what to do instead — "prefer a copy change over a logic change" — rather than just "be careful."
How to verify the work is actually done. The exact commands: the lint command, the typecheck command, the build command. Without this, "I finished the task" and "I ran the checks that prove it" are two different, unrelated claims, and you find out the difference in production.
What breaks it
The most common failure is writing a marketing document instead of an operating manual — paragraphs about the company's mission with nothing an agent can actually act on. The second most common failure is letting the file rot: it describes a folder structure or a rule that changed months ago, and now every session either follows outdated instructions or has to rediscover the truth from scratch, which defeats the entire purpose of having the file. The third is duplicating rules across five different files that quietly drift out of sync — pick one source of truth and have everything else point to it instead of repeating it.
A structure that works
A reliable shape, roughly:
- One line on what this project is and who it's for.
- A pointer to the other "source of truth" docs if you have more than one (engineering rules, brand rules, and so on), each with a one-line note on what it covers.
- The folder layout and naming conventions, with real paths.
- The explicit don't-touch list.
- The exact commands to run before calling something done.
Keep it a map, not an encyclopedia. If a rule needs three paragraphs to explain properly, that's a sign it belongs in its own linked doc, with just a pointer and a one-line summary living in the CLAUDE.md itself.
How this connects to the Engine
A CLAUDE.md or AGENTS.md is, in every way that matters, a Context File — the same kind of document that tells any AI tool who it's serving, what to build, and where the edges are, just written for a codebase instead of a business. The skill is identical either way: say the essential things plainly, point at real examples instead of describing them, and keep the guardrails explicit. If you want a working example of that skill before you write your own, the $1 Starter Kit generates your first set of Context Files for you, so you're editing a real draft instead of staring at a blank file.
READY TO STOP READING AND START BUILDING?
The Starter Kit generates your first 6 Context Files — personalized to your niche — for $1. The files your AI needs to build with you.