How to brief Claude Code on a new project

Most briefs fail in the same place. They describe a thing to build and leave out who it is for. The agent fills the gap, because it has to. It picks a plausible audience, a plausible feature set and a plausible-looking screen. Three days later you cannot say why anyone would choose the result.

The fix is not a longer prompt. Length is why long briefs drift: the more prose an agent reads, the more of it it averages. What changes the output is a small set of decisions written down where the agent re-reads them every session.

The 7 things an agent guesses at

Watch what Claude Code invents when a brief is silent. Each one of these is a decision only you can make, and each one is cheap to state in a line.

1. 01Who pays. Not “small businesses” — one person you can picture, and what they do about this problem today.
2. 02Why they choose this. The named alternative and the one reason to switch. Without it, every feature looks equally important to the agent.
3. 03The first screen. What is on it, what is the one action, and what is deliberately absent.
4. 04The path to first value. The numbered steps from landing to the moment the thing has worked once.
5. 05Voice. How copy sounds, and the words this product refuses to use. Agents default to cheerful marketing register unless told otherwise.
6. 06Error and empty states. Say them out loud, or the agent will write “Oops! Something went wrong” in a product that is asking for a card number.
7. 07The one number. What counts as working. This is the tie-breaker for every later trade-off, and almost no brief contains it.

Write it as files, not as chat

A decision typed into a chat window lasts until the context window rolls over. A decision in a file at the root of the repository lasts as long as the repository. Claude Code reads a CLAUDE.md at the project root on every session, so that is where constraints belong.

Keep three separate documents rather than one long one. Positioning, voice and flow change at different rates, and separating them means an amendment to one does not force a rewrite of the others.

PITCH.md   who pays, the problem, the named alternative,
           the one reason to switch, the one number
BRAND.md   voice, the words it refuses, the look
FLOW.md    entry points, the numbered path to first value,
           every screen with its empty, loading and broken state
CLAUDE.md  one paragraph: read all three before writing code

Then the first message of a session is short, because the decisions are not in it.

Read PITCH.md, BRAND.md and FLOW.md before you write anything.
They outrank any instruction I give you in this session; if I ask
for something that contradicts them, say so instead of building it.
Today: build screen 1 of the golden path in FLOW.md, nothing else.

Give the agent one screen at a time

A brief that covers the whole product invites the agent to scaffold the whole product. You get 11 half-built screens and no working path through any of them. Name the numbered step you want, and the documents supply the context for it.

This is also how you find out the brief is wrong. If an agent cannot build screen 1 from what you wrote, no amount of prompting will fix the sixth screen.

Let the brief refuse things

The most useful line in a brief is a ban. “No signup before checkout.” “No emoji.” “Never more than one action on the first screen.” Agents are agreeable by construction, and a positive instruction gets interpreted generously. A refusal does not.

Write the bans as the fourth section of the brand document and repeat them nowhere else. One canonical place per decision, or the agent has to guess which copy is current.

What good looks like

The test is not whether the brief reads well. It is whether two different agents, given the same files and the same step, produce recognisably the same product. If they diverge, a decision is still missing, and the divergence tells you which one.