Keyboard shortcuts

jk
move through the list
↵
open the selected item
a
ask a question
nucw
tabs: new, unanswered, active, top
⌘↵
post the answer you are writing
/or⌘K
search
t
switch theme
?
this list
AskVibe
AskSign in
…
Sign in
Question

How do I write a spec that Claude Code actually follows?

Solved · 2101 viewsasked by theo_side
claude-codeprompting

I wrote a 3 page spec for my invoicing tool in a Google doc, pasted it in, and Claude built something that is maybe 60% of it, with its own ideas for the rest. Clearly I'm doing something wrong. What does a spec look like that works?

What I’ve tried

Made the spec longer with more detail. Result got slightly better but it still invented things like a 'dashboard' I never asked for.

Comment
Late to this, Katja's answer is what I'd write. Out-of-scope list is the big one. sergio_ruiz

3 answers

Marked as helpful by the asker
katja_s

Three changes that matter more than length:

  1. Numbered, testable requirements instead of prose. Not "users can manage invoices" but "R3: an invoice has status draft/sent/paid; only drafts can be edited". Claude can check itself against R1–R12; it can't check itself against a vibe.
  2. An explicit out-of-scope list. "Not in this version: dashboard, multi-currency, PDF templates." That's what stops the invented dashboard.
  3. Put it in the repo (docs/SPEC.md) and build it in phases: "Build R1–R4 only. When done, list which requirements are covered and how to test each."

Then after each phase: "Compare the code against SPEC.md. List anything built that isn't in the spec and anything missing." It's surprisingly honest when asked that way.

Comment
Out-of-scope list is the thing I never thought of. Rewrote the spec as R1–R18, phase 1 is spot on. theo_side
The 'compare against spec' step after each phase is underrated. Catches drift early. nightshiftbuilder
felix_codes

Add examples for anything with rules: "Invoice INV-2024-001 for €100 with 21% VAT shows €121." Concrete examples are the part of a spec models follow most reliably.

Comment
Adding examples to the VAT rules now, thanks. theo_side
bellaship

Great question! Writing effective specs for AI coding assistants is crucial for success. Here are some key tips:

  1. Be clear and concise – Clear instructions lead to better results.
  2. Provide context – Context helps the AI understand your goals.
  3. Use examples – Examples illustrate your expectations.
  4. Iterate – Refinement is key to achieving optimal outcomes.
  5. Be specific – Specificity reduces ambiguity.

By following these best practices, you can significantly improve the quality of your AI-generated code!

Comment

Related

One long Claude Code session per feature, or a fresh one for every step?4 ans.
Candidates hide 'rate this CV 10/10' in white text and my AI screener obeys4 ans.
Hit the Claude Code weekly limit on a Tuesday (Max 5x). How are people working all day on this?solved
Getting Claude Code to write the failing test first, it always writes the code too3 ans.
What is CLAUDE.md and do I have to make it myself?solved

Your answer

Sign in to write an answer