Build With AI

Spec-Driven Development With Claude Code: The Spec I Write Before Every Feature

The spec is the difference between AI code that ships and AI code you keep re-explaining. Here's the one I write before every feature.

By Saygin Celen · 6 min read

Cover: Spec-driven development. The spec I write before every feature.

How do you do spec-driven development with Claude Code? Before Claude writes any code, you write a short spec in plain English.

It says what the feature does and why, who it's for, the rules it must follow, what it must never do, and how you'll know it's done.

Claude builds to the spec, you test against it, and every mistake becomes a new rule in the spec so it never happens twice.

The spec and the code change together, in the same step.

When people ask how a non-developer built a live AI platform, they expect a clever prompt.

There isn't one.

There's a document.

The spec is the most important thing I write.

Not code.

Not prompts.

The spec.

I'm the founder of SiteNeuro, and I'm not a developer.

We merged 1,156 changes in 175 working days, and every one of them traces back to a spec.

I explained the overall workflow in Claude Code for non-developers.

This post zooms in on the document at its center.

What a spec is (and isn't)

A spec is a plain-English description of what to build.

It is not code. It is not a long technical document. And it is not a chat with Claude that disappears when the session ends.

It's the source of truth. If the spec and the code disagree, one of them is wrong, and you fix it on purpose.

A chat is a conversation. A spec is a contract.

The foundation: your project's constitution

Before any feature spec, there's one document above all of them.

GitHub's Spec Kit calls it the constitution: the principles your whole project follows. Mine holds things like:

What the product is for, and who it serves
The non-negotiable rules every feature must respect
How changes are made (for example: the spec and the code are always updated together)

Every feature spec inherits from it. When Claude starts work, it reads the constitution first.

The sections every feature spec needs

An annotated one-page spec with five sections: what and why, who it's for, rules, never, and done when, each with an example line and what it's for. — The five sections of a one-page spec for building with Claude: what and why, who it's for, the rules, what it must never do, and done when.

My feature specs follow the same shape. In general terms:

1. What and why

One paragraph: what the feature does and the problem it solves. If I can't write this clearly, I'm not ready to build.

2. Who it's for

The customer and the moment they use it. This keeps decisions anchored to a real person.

3. The rules

Numbered, specific statements of how it must behave. This is the heart of the spec.

"A business only counts as reachable by contact form if the form accepts a message." is a rule. "Make contact detection better" is not.

4. What it must never do

The negative rules. Often the most valuable part, because they're usually written after something went wrong.

5. The data it touches

What information the feature reads and changes, in plain words. No database jargon needed.

6. The tasks

The build broken into small steps, each one testable on its own.

7. What "done" looks like

How I'll test it like a customer: the screens to check, on desktop and phone, and what should happen.

A real example, told as a pattern

Here's one from SiteNeuro, without the internals.

The book

Write the spec. Let Claude build.

Build Your AI Platform walks non-developers through Spec-Driven Development, from the first spec to a live product. Chapter 1 is free.

29 chapters, five levels, step by step
Three complete builds, start to finish
Templates, checklists and a prompt kit
Chapter 1 is free to read, in full

Read Chapter 1 free →

We wanted to know which local businesses could be contacted through a form on their website. The first version simply checked whether a page had a form.

It worked. Technically.

But when we looked at the results, many of those "forms" were search boxes. A search box is a form. You can't send a business a message through it.

So the spec gained a rule, in plain English: a contact form only counts if it accepts a message.

Claude updated the code to match the rule, the tests were updated to prove it, and the rule stayed in the spec forever. Every future change to that feature now has to respect it.

That's the pattern: the spec isn't written once. It learns.

What happened when I skipped the spec

My first month was the slowest.

The rules weren't written down yet. Lessons lived in my head and in old chat sessions. So the same mistakes kept coming back: a fix in one place, a new problem somewhere else, and a "done" that wasn't done.

Everything sped up once every fixed mistake became a written rule.

Every bug you fix without updating the spec is a bug you'll fix again.

How the spec, the code and Claude's memory stay in sync

Three things have to agree:

The spec: what should happen
The code: what does happen
Claude's memory: the project notes Claude reads at the start of every session

My rule is simple: when a mistake is fixed, all three change together. Claude adds the lesson to its memory notes, updates the spec, and fixes the code, in the same step.

That's how a project gets smarter over time instead of more fragile.

How long does a spec take?

It depends on the feature.

A small change can be specced in a few lines inside the conversation. A big feature, the kind that touches many parts of the product, deserves real planning: describing it to Claude, asking about risks and side effects, getting a second opinion from ChatGPT and other models, and merging their ideas into one plan before any code is written.

That planning time isn't a delay. It's where most of the speed comes from.

Your first spec, step by step

Write your constitution first: what the product is, who it's for, the rules nothing may break.
Pick one small feature.
Fill in the seven sections above, in plain English.
Ask Claude to challenge it: what's missing, what could break, what's unclear.
Let Claude build to it, then test against "what done looks like."
When something goes wrong, add a rule.

There's more on why this beats building by chat in vibe coding vs. spec-driven development.

Straight answers

What is spec-driven development with Claude Code?

It's a way of building software where you first write a plain-English spec describing what a feature must do, its rules and what "done" means. Claude Code builds to that spec, and you test the result against it.

What should a spec include?

What the feature does and why, who it's for, numbered rules, what it must never do, the data it touches, the build tasks and how you'll test that it's done.

What is a Spec Kit constitution?

In GitHub's Spec Kit, the constitution is the foundation document that sets your project's principles and non-negotiable rules. Every feature spec follows it.

Do I need to be technical to write specs?

No. Specs are written in plain English. What matters is being specific about behavior, rules and what success looks like.

How do specs prevent repeated bugs?

When a mistake is fixed, it becomes a written rule in the spec and in Claude's project notes. Future work has to respect that rule, so the same mistake doesn't return.

Building an AI platform?

I built SiteNeuro as a non-developer, with Claude and written specs: 1,000+ websites built so far.

If you're turning an idea into an AI product, I can help you shape the business case, set up Claude and your specs, and plan a first build that doesn't loop.

Tell me what you're building →Or connect on LinkedIn