Describe It Like a Spec

Most bad output starts as a vague request

Your first request was specific because I wrote it for you. Left alone, most people type "make me a dashboard" and get a dashboard, just not the one they meant. Then they spend an hour correcting it. The fix is old and boring: decide what you want before anyone builds it. Claude can help with the deciding too.

Plan Mode Is the F Key

In the real SkiFree, pressing F made you fast enough to outrun the yeti, and hardly anyone ever found out. Claude Code has one of these. In plan mode, Claude reads your files and proposes an approach without changing anything. You read the plan, fix it, and only then does it build. The yeti is rework. In the app, plan mode is in the mode selector under the prompt box (Cmd+Shift+M on a Mac, Ctrl+Shift+M on Windows).

Build it

1. Turn on plan mode

   Open the mode selector under the prompt box and choose Plan. It only lasts for this session, so check it again if you come back later.
   Stuck?

   Claude started changing files anyway.

   Click stop, then check the selector says Plan. Plan mode doesn’t edit your files, so if it’s editing, it’s in another mode.

2. Let Claude interview you

   Nobody writes a good spec cold. Have Claude ask the questions, and answer as the person who’ll use this page on Monday morning.
   Paste this into Claude Copy

   I want to make this dashboard useful for a Monday morning pipeline review. Before changing anything, interview me one question at a time about who reads it and what they need to decide. Then write a one-page spec covering: who reads it, what they need to decide, what it shows, what done means, what's out of scope, and the rules (it stays one file, the data stays inside the page, no outside libraries or services). Show me the spec and your plan for building it.

   Stuck?

   It keeps asking questions.

   Say: “That’s enough questions. Write the spec with what you have, and mark anything you guessed.”

   I don't know the answer to a question.

   Say so, and ask it to suggest two options with the tradeoff of each. Your answer doesn’t have to be permanent.

3. Read the plan and push back

   This is the part where you’re the boss. Read the spec and ask what you’d ask a new hire. Is that what you meant? What did it leave out on purpose? The out-of-scope line matters most. If there isn’t one, ask for it. When it looks right, say: “Save the spec as spec.md, then build it.” That’s the moment you hand over the wheel.
   Stuck?

   The plan is long and I don't follow it.

   Say: “Explain this plan in five plain sentences, and tell me which decisions are mine.”

4. Check the result against the spec

   Open the page. Don’t ask whether it looks nice. Go through what your spec says done means, line by line. If something’s missing, say which line. The total for open deals should still be $331,000, and Maya’s open deals should add up to $190,000.
   Stuck?

   It added things I didn't ask for.

   Say: “Remove anything that isn’t in spec.md, and tell me what you removed.” It tends to be generous. Your spec is how you say no.

Gabe

Tools like Lovable and Bolt still have their place. We use Lovable for quick prototypes, and my favorite workflow uses both. I call it the moonwalk: throw together a prototype to explore the problem, extract a detailed spec from it, then throw the prototype away and rebuild against the spec. The prototype was research. Building it twice is often faster than fixing a messy prototype.

# [Project name]

Who reads it:
What they need to decide:
What it shows:
Done means: (things you could check with your own eyes)
Out of scope: (what we are deliberately not building)
Rules: (data, tools, anything it must never do)