Spec Kit as engineering discipline: specify → clarify → plan → tasks

Problem

Naive vibe-coding: one big prompt → the agent immediately writes code → an hour later the structure is unclear, boundaries are blurry, rollback is expensive. In the retrospective you hear "AI can't do architecture" — but there was never a fixed "what we're building" or explicit open questions in the brief. Spec-Driven Development (SDD) via GitHub Spec Kit reverses the order: solution artifacts first, implement last.

Methodology

1. 1. Repository constitution: .specify/

   Before the first feature — templates and project memory, not "start fresh in chat."

   • • templates/ — spec-template.md, plan-template.md, tasks-template.md: the agent doesn't invent a new structure every time.
   • • memory/ — stable decisions (stack, prohibitions, conventions): fewer contradictions between features 001-*, 004-*, 005-*.
   • • scripts/ — Spec Kit CLI wrapper (specify, plan, tasks, etc.).

   Technique: configure templates once for your domain (microservices, events, API keys) — every subsequent feature inherits structure, not the style of a random prompt.

2. 2. One feature — one folder in specs/

   Numbering NNN-short-name (e.g., 001-model-service, 004-order-manager) — parallel workstreams, clear scope in PR and in your head.

   Inside each feature — a chain of files, not one SPEC.md for everything:

   File / directory	Role
   spec.md	What and why; user stories; acceptance scenarios
   plan.md	Architectural decisions with rationale ("why," not just "decided")
   tasks.md	Breakdown with dependencies; what can be parallelized
   contracts/	Service boundaries (messages, API) — before code
   checklists/	Gates before implement
   quickstart.md	How to verify the feature manually

   Technique: don't start implement without plan + tasks — otherwise the agent builds what's easiest to write, not what was agreed.

3. 3. Clarify — a separate phase, not "ask in chat"

   In spec.md there is a Clarifications section (sessions with date): question → answer → recorded decision. Markers [NEEDS CLARIFICATION] in the spec text prohibit silent assumptions.

   Technique: while the spec contains unresolved [NEEDS CLARIFICATION] markers, don't move to plan — otherwise the plan encodes guesses.

4. 4. Plan with rationale, not a list of technologies

   Each non-trivial decision in plan.md: alternative → why rejected → what was accepted. The agent at implement draws not from "internet average temperature" but from your context in spec + plan.

   Technique: any contested point (queue, model storage, auth between services) — only via an entry in plan; otherwise code review has nothing to discuss beyond the diff.

5. 5. Tasks as a graph, not a flat TODO

   tasks.md: dependencies between tasks, explicitly marked "can be parallelized." Implement one task at a time with commit/test — easier rollback and easier to see where the agent went off track.

   Technique: after each task — run the feature checklist; not "all at the end."

6. 6. Multiservice: contracts before code

   When a repo has multiple services (ws-gateway, order-manager, …), contracts/ in each feature fixes messages and API before implementation. Otherwise service B "catches up" to service A's format in production.

7. 7. Anti-pattern table: naive vibe-code vs SDD

   Naive vibe-code	SDD via Spec Kit
   One prompt "build the system"	specify → spec file
   Agent guesses in its head	clarify + Clarifications in spec
   Code with no explanation of choices	plan.md with rationale
   "We'll write tests later"	Acceptance scenarios in spec, checklists
   Monolithic diff	tasks + incremental implement

Artifact

github.com/dobryakov/ytrader-bybit — a public multiservice repository with a complete Spec Kit cycle: .specify/ constitution, numbered specs/00N-*, the full chain spec.md → plan.md → tasks.md, and contracts/ between services.

The breakdown focuses on the shape of the artifacts and their consistency, not the subject domain. To verify: clone the repo and walk one feature-folder top-to-bottom through the file chain — no need to run the full system.

Upstream: github.com/github/spec-kit

For whom and why

Architects and CTOs introducing agents into development: not "which framework to pick," but the artifact discipline under which an agent amplifies — rather than replaces — design. Complements Breakdown 07 (cursor rules in the IDE) and Breakdown 10 (eval at release): Spec Kit operates before code; eval operates after.