Iman Suherman — Building solutions. Delivering impact.
ENID
← All articles

Articles

Get started with SDD: from idea to spec to implementation

Watched the 12 Sep live build (or the recording) and felt more confused afterward? SDD means Spec-Driven Development. This is the short path: idea → spec → implement → prove — and the API contract is language-neutral (Python reference; Java welcome).

Updated 5 Oct 20269 min read
Spec-Driven DevelopmentGetting startedSurveyDeskAI agents
Get started with SDD — Idea, Spec, Implement, Prove: from product story to acceptance tests on SurveyDesk

After Build an App with AI, Live on 12 September 2026, a few people said the same thing: the session was cool — then trying SurveyDesk made them more confused. That is a normal reaction. A live stream compresses hours of contract work into a demo. This article is the slow path you can follow at your own pace.

Language is not the point (Node is just one interface)

If you prefer Java and do not want to live in Node.js — that is fine. SurveyDesk’s durable contract is OpenAPI + SQLite + lifecycle rules, not a Node runtime. The reference API is Python (FastAPI) so the demo stays language-neutral. Implement the same specs in Java, Kotlin-JVM, Go, or anything else that honours the contract. Next.js on the public web is only the respondent UI interface from the live session — not a requirement for SDD itself.

The map (so the demo stops feeling random)

Loading diagram…

Idea → Spec → Implement → Prove. Skip a box and the next agent (or you, next Saturday) loses the plot.

If you open the repo in the middle — apps/, Cursor chat, green terminals — you are looking at step 3 and 4 without the map from step 1 and 2. That is why it feels like magic (or nonsense).

1. Idea — write the product story first

Do not start with “build me an app.” Start with a short story a teammate could read without the livestream. For SurveyDesk the story answers: who operates it, who responds, what is local vs public, what is explicitly out of scope.

text
Product: SurveyDesk — local-first survey desk.

Operators: native iOS / Android apps only.
Respondents: anonymous Next.js web — no login.
API: local HTTP + SQLite via OpenAPI (Python reference;
     Java or any language welcome — no cloud tenant).

Must: create survey → open → collect → live results → close.
Must not: multi-tenant SaaS, SSO, email invites, payments.

Demo proof: create “Session feedback”, open it,
submit anonymously, see results update, close,
further submit rejected.

2. Spec — freeze the contract

A spec is not a novel. It is a checklist of truth: what SHALL happen, what SHALL NOT happen, and how we will know. In SurveyDesk that lives under specs/ — requirements (SHALL), acceptance (Gherkin), ADRs (architecture decisions).

  • SHALL: the durable product rule (“submit SHALL be rejected when the survey is closed”).
  • Acceptance: a scenario a test can execute (Given / When / Then).
  • ADR: why we chose SQLite / local-first / native operators — so the next agent does not “improve” you into the cloud.
gherkin
Feature: Survey lifecycle
  Scenario: Reject submit when closed
    Given a survey that is closed
    When a respondent submits answers
    Then the API SHALL reject the submit

Tools can help write the first pack from natural language (Agent On Rails gather). You still confirm the outline. Nothing important should land only in chat.

3. Implementation — agent builds against the IDs

Now open Cursor (or any coding agent). Point it at a requirement ID or feature file — not at a vague feeling. Good prompts sound like: “Implement SD-003 lifecycle against specs/acceptance/lifecycle.feature. Do not invent multi-tenant behaviour.”

  1. 01Read the relevant SHALL + acceptance scenario.
  2. 02Ask the agent to implement that ID only.
  3. 03Review the apps/ diff against the contract — not against the vibe.
  4. 04If the product decision changed, update the spec first, then re-implement.

That last step is the whole point of the live “iPad refresh” moment: the ask was update the spec, not only the UI. Details: https://suherman.net/articles/vibe-coding-vs-spec

4. Prove — run acceptance before you trust the demo

A green UI is not proof. In SurveyDesk, npm run test:acceptance (or pytest against the OpenAPI API) is the proof surface. If a behaviour cannot be pointed to a scenario, it is still a prototype accident.

bash
# After clone / install — names may vary by repo
npm run test:acceptance
# or: pytest against the Python API / any OpenAPI-compliant server
# Expect: features/scenarios pass for the IDs you claimed to ship

A weekend starter plan (when the recording left you dizzy)

  1. Watch the recording once for the story, not for every keystroke: https://youtu.be/h3FPQEw2QNI
  2. Skim the 12 Sep session notes: https://suherman.net/articles/surveydesk-12-sep-session-notes
  3. Read Beyond Gherkin for ADR / SHALL / OpenAPI: https://suherman.net/articles/beyond-gherkin-adr-shall-openapi
  4. Open https://github.com/iman-suherman/survey-desk and read specs/ before apps/.
  5. Pick one feature file (lifecycle is a good first). Read Given/When/Then aloud.
  6. Run the acceptance suite. Map one failing or passing scenario back to a SHALL.
  7. Only then ask an agent to change something — and tell it to update the spec if the product rule changes.

Where to go next

Bottom line: if trying the repo made you more confused, start from the idea and the contract — not from the shiny apps/ tree. Same energy as the live vibe. Different landing zone.

← All articles

Get started with SDD: from idea to spec to implementation · suherman.net