What Exactly Is a Spec? — Writing Spec Kit Specs for Beginners

The first time you open the specs/ folder in Spec Kit, most people make the same face. spec.md, plan.md, tasks.md, research.md, data-model.md, contracts/, checklists/ … files keep pouring out, and you're not even sure what a "spec" is in the first place. The reason the series can still feel overwhelming is that you usually see the finished artifacts first. Those artifacts look rule-heavy, but every one of those rules grows from a single, very simple idea.

This post goes back to that starting point. We'll anchor "what are you writing down, and why" with an analogy, dissect why the specs/ directory looks the way it does, and then follow the actual order in which you fill out a single spec page. The focus is on understanding why rather than memorizing commands — so take your time.

What you'll learn

• That a spec is not code, but a document of agreement about "what and why" (a house-building analogy)
• The real reason the specs/ directory looks complicated, and who creates which file
• The six building blocks of a spec page, translated into plain language
• A 5-step writing order so you don't freeze in front of a blank page
• A whole spec page shown through a tiny "contact form" example

This is the beginner companion to the Spec Kit series. Where the series (① Why SDD → ⑦ A retrospective) covers the full flow, this post re-explains the single step people get most stuck on — writing the spec — at a beginner's eye level.

1. What Exactly Is a Spec? — Think of Building a House

First, let's clear up a misconception. A spec is not code. It's not a blueprint either. A spec is a document of agreement that writes down, in human language, "what I want and why."

Compare it to building a house:

The key point is that stage 1 (requirements) contains no "how." The homeowner says "3 rooms, a home office," not "2×4 timber framing with glass-wool insulation." That's the architect's (plan's) job.

spec.md is exactly the same. It writes down only "what the user should be able to do, and why that matters." A sentence like "store it in PostgreSQL and show it with React" is not a spec — it's a design, and that belongs in the next step, plan.

In one line: spec = "What · Why", plan = "How." That boundary is the root of nearly every rule in Spec Kit.

Why split it this far? Two reasons.

• To avoid nailing down a solution too early. The moment you write "process it with Kafka" into the spec, the fact that all you actually needed was a simple poll every 5 seconds never gets considered.
• To create a yardstick for judging "done." A spec is what you later check the code against — "does this satisfy the intent?" If implementation is mixed into the yardstick, the yardstick goes blurry.

2. The Real Reason the specs/ Directory Looks Complicated

Now look at the folder again. There's only one reason it looks complicated — a single feature is split into the four stages above, and each stage produces a file. So it's not that there are many files; it's that the "train of thought" for one feature has been pinned down into files.

A real directory looks roughly like this:

specs/
└── 001-my-feature-name/
    ├── spec.md          ← ① What & Why (start here!)
    ├── plan.md          ← ② How (technical design)
    ├── tasks.md         ← ③ to-do list
    ├── research.md      ← (support) rationale for tech choices
    ├── data-model.md    ← (support) data structures
    ├── contracts/       ← (support) API promises
    └── checklists/      ← (support) quality checklists

No need to be intimidated. The only file a beginner really writes by hand is spec.md. The rest are generated by the later commands.

So 90% of the "specs rules are hard" feeling dissolves once you understand the single spec.md page. Everything else derives from it.

Command names may look different across docs. Older material uses dot notation (/speckit.specify); the latest install uses hyphen notation (/speckit-specify). They're the same command — use whichever your install provides.

3. What Goes Into a Spec Page — Six Things in Plain Words

Open spec.md and you'll meet unfamiliar terms (FR, SC, Acceptance Scenario…). Translated into plain beginner language, here they are.

① User Story — "who / what / why"

Write the feature as one sentence from the user's point of view.

As a visitor, I want to contact the company through a contact form,
because I want to reach out immediately without hunting down an email address.

Stories are listed with priorities (P1, P2…). The trick is to slice them so that even shipping just P1 delivers value.

② Acceptance Scenario — "if this happens, it's a success"

Write the concrete situation in which the story can be called "done," as Given–When–Then (situation–action–result).

Given the visitor filled in name, email, and message correctly,
When  they press send,
Then  a success message appears and an email reaches the staff.

This later becomes the "test." A vague sentence you can't turn into a test is a spec failure.

③ Functional Requirement (FR) — "the system MUST…"

Turn the story into verifiable rules the system must keep, and number them.

FR-001: The system MUST require name, email, and message.
FR-002: The system MUST reject malformed email addresses.
FR-003: The system MUST block bot submissions.

The reason for numbering (FR-001…) is so the plan, tasks, and code can later trace "this exists for FR-002."

④ Success Criteria (SC) — "a measurable definition of done"

Write "it works well" as numbers or observable facts, with no tech terms.

SC-001: A visitor can complete an inquiry in under 3 minutes.
SC-002: All bot spam submissions are blocked.

If FR is "what it must do," SC is "how much is enough."

⑤ Edge Cases — "what about this?"

- What if the same person sends the same message 10 times in a row?
- What if the mail server is down?

⑥ Assumptions — "we'll take this as given"

Write down the reasonable defaults you didn't spell out in the spec. Something like "inquiry data is not stored in a DB; it's only delivered by email."

Six things look like a lot, but getting ①② right already gets you halfway. ③④ flow naturally out of ①②, and ⑤⑥ are notes that fill the gaps.

4. A 5-Step Order So You Don't Freeze at a Blank Page

The real source of that "stuck" feeling is the urge to write it perfectly in one shot. A spec isn't written top-to-bottom in one pass — it's started narrow and widened.

Step 1 — Start with one sentence. "Let visitors contact us through a contact form." That single line is enough.

Step 2 — 1–3 user stories. Start with the most important (P1). Don't be greedy; starting with just one P1 is fine.

Step 3 — 1–3 acceptance scenarios per story. As Given–When–Then. Just picture "what does success look like?"

Step 4 — Turn scenarios into FRs. What must the system do to satisfy the scenario, as rules.

Step 5 — Pin "done" with SCs. As numbers and facts.

And throughout, just keep one golden rule.

When a "how" starts coming out of your fingertips, stop. Frameworks, DBs, API shapes — all of it goes to the plan step. The spec holds only "what & why."

When You Have Claude (or Spec Kit) Do It

Instead of filling the blank page yourself, generating a draft and then refining it is far easier for beginners.

/speckit-specify Visitors must be able to contact the company through a contact form.
Take name, email, and message; block malformed emails and bot submissions.
Deliver inquiries to staff by email (no separate storage).

Dictate just one paragraph of "what & why" like this, and /speckit-specify drafts a spec.md with the six elements above. Your real job is to read that draft, fix wrong assumptions, and add missing scenarios. That's ten times easier than starting from a blank page.

If you see a [NEEDS CLARIFICATION] marker in the draft, it's a signal that "a decision is needed here." If there are too many, decide only the 2–3 most important and move on with reasonable defaults for the rest. Progress beats perfection.

5. Five Mistakes Beginners Often Make

1. Writing "how" into the spec. "Cache it with Redis" → that's plan. The spec gets only the outcome, like "lookups must respond instantly."
2. Sentences you can't turn into a test. "It should be fast and convenient" → fast by what measure? Use "search results appear within 1 second."
3. Overusing [NEEDS CLARIFICATION]. Ask about everything and you never make progress. Ask only the essentials; default the rest.
4. Scope too large. Trying to cram "the whole site" into one spec wears you out. Narrow it to a single feature.
5. Writing code first and retrofitting the spec. Reverse-spec'ing already-built code is possible, but that's a story for when you have a separate goal (organizing existing code). For a new feature, spec → code is the canonical order.

6. Hands-On Mini Example — A Whole "Contact Form" Spec Page

Let's combine everything into a tiny example — a condensed version of a real spec.md.

# Feature Specification: Contact Form
 
## User Scenarios
 
### User Story 1 - Send an inquiry (P1)
As a visitor, I want to contact the company through a contact form.
Why: to reach out immediately without hunting down an email address.
 
**Acceptance Scenarios**
1. Given name, email, and message are filled in correctly,
   When send is pressed, Then a success message shows and staff get an email.
2. Given the email format is wrong,
   When send is pressed, Then a "please check your email" error shows.
 
## Requirements
- FR-001: The system MUST require name, email, and message.
- FR-002: The system MUST reject malformed emails.
- FR-003: The system MUST block bot/spam submissions.
 
## Success Criteria
- SC-001: A visitor can complete an inquiry in under 3 minutes.
- SC-002: All bot spam submissions are blocked.
 
## Edge Cases
- Repeated identical submissions in a row? → silently ignore duplicates.
- Mail server down? → tell the user it failed.
 
## Assumptions
- Inquiry data is not stored in a DB; it is delivered by email only.

Notice there is not a single line about technology. No framework, no DB, no API shape. Only "what, why, and how-much-is-enough." Once this one page stands firm, /speckit-plan takes responsibility for "then how do we build it," and /speckit-tasks breaks down "then what do we do first."

Wrapping Up — A Spec Is "Agreement," Not "Paperwork"

If the specs/ directory felt hard, it wasn't because there are many rules — it's because you saw the artifacts first. The starting point is simple: write down "what you want and why" so anyone can read it and picture the same thing. That's a spec.

Your first page can be rough, and that's fine. Write it in the order one sentence → story → scenario → FR → SC, pushing any "how" off to plan as it surfaces. And once you become the person who has /speckit-specify draft it and then refines it, you'll get the hang of it faster than you'd expect.

Next step: Once the spec stands, it's time to design "how" with /speckit-plan. The full flow of specify → plan → tasks → implement, with a worked example, continues in the Spec Kit series (①–⑦).