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 · 2103 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.
What is CLAUDE.md and do I have to make it myself?solved
Do you use plan mode for everything or only big stuff?3 ans.
Getting Claude Code to write the failing test first, it always writes the code too3 ans.

Your answer

Sign in to write an answer