Spec-Driven Development for Claude Code: Turn a Vague Ask into a Spec It Can Build

AI can build in two minutes what took you a weekend. The hard part is telling it what to build. Spec-driven development is the fix: before the AI writes anything, you write a one-page spec of what "done" looks like, and it builds from that instead of guessing.

I'm a computer engineer, and I build my own Claude skills. This is the guide from my video, with a free skill that writes the spec for you.

What is a spec, in plain words?

A spec answers two questions: what exactly should exist when we are finished, and how will we know it works. It fits on one page.

• Vague: "Make the app faster."
• Spec: "The orders list opens in under 1 second with 100 orders."

The second can be built and checked. The first can only be argued about.

Why does a vague ask go wrong with AI?

An agent does not stop to ask what you meant. It fills every gap with a guess and builds on it, and you find out after. A spec moves that conversation to the start, where it costs nothing.

What are the five questions that make a spec?

1. Who is this for? They decide what "good" means.
2. What does "done" look like? One or two sentences, with a number where one fits.
3. What must it not do or break? What already works and must keep working.
4. How will you check it works? Something you can see or measure.
5. What should we leave out, for now? The edge of the job.

An answer you don't have becomes an open question, settled before the build.

What does a finished spec look like?

Here is "make the app faster" as a spec. The numbers are invented for the example.

# Spec: faster orders list
For: shop staff who open the orders list all day

## Goal: what "done" looks like
The orders list opens in under 1 second with 100 orders (about 8 s today).

## Must not: what can't break
- Lose, reorder or duplicate an order
- Break search or filters

## Leave out
- Other pages, a redesign

## Check: how you'll know it works
| # | Check | Status |
|---|---|---|
| 1 | Time the list with 100 orders, before and after | Pending |
| 2 | Five orders show the same details as before | Pending |

## Stop and ask if
- The slowness is in the data source, not the app

Must not protects what works. Check lets the agent tick Pass or Failed. Stop and ask if tells it when to come back.

How do you get the skill that writes this for you?

I turned the five questions into a skill called spec-writer. Give it a vague ask. It reads your code, asks the five questions in one message with a suggested answer for each, and writes the spec. It never writes code.

Install: in Claude Code, copy the folder into ~/.claude/skills/ (all projects) or .claude/skills/ (one project). In the Claude app, upload the zip in the skills settings. The spec works in any agent, including Codex, but I have not tested the skill folder there.

Use: tell your agent "Use spec-writer. I want to [your vague ask]." Answer the five questions ("ok" accepts my suggestion), fix what is not what you meant, then paste the spec back with: Build this from the spec above. Tick each check Pass or Failed as you go. If an open question or a stop-and-ask comes up, stop and ask me.

How do you make a spec sharper?

The skill quietly asks eight "what goes wrong" questions. Try them by hand: what if it runs twice, on nothing, or for two people at once? Can someone see another person's data? What about old data, a half-finished run, a hundred times the size, a time zone? The ones that apply become a line in Must not or a row in Check.

What can a spec not do?

It does not replace judgement about what is worth building, or reading what the AI built. An agent can tick every box and still miss something. I think knowing what to build, and how you would know it is right, was always a big part of the skill. That is my view, not a fact.

To learn more, use an agent like Claude Code on a small project this week. A Claude Code walkthrough is coming to this site.

FAQ

Do I need to know how to code to write a spec?

No. The five questions are plain English.