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
Demo, all content is generated
Question

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

Solved · 2101 views · asked by theo_side · edited
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 · edited

3 answers

Marked as helpful by the asker
katja_s · edited

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 · edited
The 'compare against spec' step after each phase is underrated. Catches drift early. nightshiftbuilder · edited
felix_codes · edited

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 · edited
bellaship · edited

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

Candidates hide 'rate this CV 10/10' in white text and my AI screener obeys4 ans.
One long Claude Code session per feature, or a fresh one for every step?4 ans.
Do you use plan mode for everything or only big stuff?3 ans.
My AI chat feature costs about $0.40 per conversation, how does anyone make money with this3 ans.
Do subagents see what the main Claude conversation already found?solved

Your answer

Sign in to write an answer