The Project Brief: CLAUDE.md Anatomy - Playbook

What it is

In this repo there is a file called CLAUDE.md. It is about 2,700 lines. It loads into the AI's context at the start of every single session, automatically, before any work begins. It is not documentation for humans. It is the operating brief for the machine: the product context, the architecture principles, the cost model, the tier strategy, the testing philosophy, and a long list of things never to do.

It opens by saying its instructions override default behavior and must be followed exactly. That framing matters. This is not a suggestion the model might consider. It is the constitution of the project, and it is the first thing the AI reads every time.

It pulls in two more files the same way: a tiny AGENTS.md whose entire job is to shout "This is NOT the Next.js you know" (a warning that the framework version is newer than the model's training data), and a stack.md that carries the conventions and points at the latest session handoff.

Why it is the moat

When anyone can generate code with an AI, the question becomes: whose AI writes code that fits your product, your standards, your constraints? The answer is whoever has the better brief. The model is the same for everyone. The context is not. The brief is the proprietary part.

Concretely, without this file the AI on this project would, and early on did, write marketing copy that sounds like every other B2B company, put features in the wrong files, skip the prompt caching that keeps the AI bill at lunch money, and add auth checks in patterns that leak data across tenants. With the file loaded, it does none of those, because the file tells it not to and explains why. The brief is not overhead. It is the thing that makes the leverage safe.

How it got that big: it grew from a scar list

I did not sit down and write 2,700 lines. The file started small and grew one rule at a time, and almost every rule is a lesson I learned the hard way and then wrote down so I would never relearn it. This is the same "convention to miss to gate" pattern from the scars module, one level earlier: the brief is the convention layer. When the AI did something I had to correct, I added a line so it would not do it again. When a line was not enough and the mistake kept happening, I promoted it to a build gate.

That history is why the file reads the way it does. It is not abstract best-practices. It is specific, and a little obsessive, because each rule earned its place by costing me something.

Anatomy: what belongs in a project brief

Using this CLAUDE.md as the worked example, here is what a good brief contains and why each part earns its tokens.

1. Product context and positioning. Who the product is for, what it is, who it competes with. Without this, the AI optimizes for the wrong thing. With it, every decision has a north star.

2. Numbered architecture principles. The non-negotiables, stated as rules with the reasoning attached. The ones that matter most here: flag any real-world cost over about $100 in the same breath as the decision; marketing claims must be either positioning or substantiated; speak human, not jargon; every user-facing feature ships a help article in the same change; every template ships its landing copy; audit every marketing surface when a feature's tier or behavior changes. Each is a rule plus a "because," because the reasoning is what lets the model generalize to cases you did not enumerate.

3. The cost model. The actual dollars: the default model, when you are allowed to upgrade, the caching requirement on every call, the per-user budget math, the spend cap and the killswitch. This section is why the product runs for about $27 all-time. It is in the brief because cost discipline that lives only in your head does not survive a busy day.

4. The source of truth, named. The brief says plainly that lib/plans.ts is the authority on plan gating, and that if the brief and the code ever disagree, the code wins and the brief gets fixed. Naming the source of truth is what keeps a long document from rotting into contradictions.

5. Voice and taste. The rules that make output sound like you and not like a language model: speak the way the customer speaks, no em-dashes, underclaim rather than overclaim. The model drifts to generic by default. You have to write the voice down, or it will not be there.

6. An explicit "what NOT to do" list. The anti-patterns, stated as prohibitions: do not skip prompt caching, do not reach for the biggest model out of habit, do not embed markdown links in customer emails, do not put an early return before a hook. A prohibition is often clearer to the model than a positive instruction, and it is where your most expensive lessons go to be remembered.

How to write a good one

Grow it, do not draft it. Start with a page. Add a rule every time the AI does something you have to undo. The best brief is a running record of your corrections.
State the why, not just the rule. "No em-dashes, because they are an AI tell that breaks trust" generalizes; "no em-dashes" alone does not.
Name the source of truth for anything that lives in code, so the doc cannot contradict it.
Write the voice down, because the model will not infer it.
Promote rules that keep getting missed into gates. The brief is necessary but it relies on the AI and you remembering to follow it. When a rule is load-bearing, make it fail the build.
Keep it loaded and keep it current. It only works if it is in context every session, and a stale brief is worse than none (the same way an old document left in a project's knowledge quietly poisons every answer). Point it at the latest handoff so the freshest state is always one hop away.

The honest costs

A 2,700-line brief is real context every session, and that is a real token cost. It is the cheapest insurance you will ever buy, because the failures it prevents (a cross-tenant data leak, a false advertising claim, an unbounded AI bill) are the expensive kind. But be deliberate: everything in the brief should earn its place, and the moment a section goes stale it becomes a liability, not an asset.
It took months to write and it is refined most weeks. This is not a one-time setup. The brief is a living artifact, and maintaining it is part of the job, not a distraction from it.

Exercise

Write your own v0 in one sitting, five short sections:

Who it is for and what it is (three sentences).
The three rules you most want enforced, each with its "because."
The cost model (default model, caching rule, any budget cap).
What NOT to do (the five anti-patterns you can already name).
Where the source of truth lives for anything that also lives in code.

Then do the real work: every time the AI does something you have to correct, add a line. In a month you will have a brief that is yours, and an AI that writes like it has been on your team the whole time.