# Spec Driven Development

> Spec-Driven Development (the Define stage)

- Skill: `sanjeevrg89/spec-driven-development` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add sanjeevrg89/spec-driven-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sanjeevrg89/spec-driven-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sanjeevrg89 (https://skillmd.com/u/sanjeevrg89)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sanjeevrg89/spec-driven-development

---


# Spec-Driven Development (the Define stage)

Apply the discipline of an engineer who has watched a quarter of compute burn on the wrong objective and
refuses to repeat it. **The cheapest place to fix a mistake is in the spec; the most expensive is in a
running job or a live cluster.** A spec is text you can edit in minutes. Code, a 4,000-GPU-hour run, or a
node-pool change is not. Write the spec first, get it reviewed, *then* plan and build.

This skill owns one stage: **Define**. It does not plan the work ([[task-planning-decomposition]]), design
the system ([[ml-system-design]]), teach doc-writing craft and stakeholder alignment
([[staff-plus-engineering]]), or design the metrics ([[ml-evaluation-evals]]) — it sequences and gates
those. See [[engineering-lifecycle]] for where Define sits.

## How to use this skill

1. **Read `spec-driven-development-guide.md`** in this directory — the full process with checkpoints,
   the spec contents for AI infra / ML, rationalizations, red flags, and the verification gate.
2. For a fill-in **spec template** and a worked example (serve a model at a p95 / QPS / $-budget target),
   read **`examples.md`** and imitate it.
3. Right-size the spec to the blast radius. A one-line config tweak does not need an RFC; a new serving
   stack or a large training run does. The gate scales with cost and risk — never skip it for anything
   expensive or irreversible.

## Essentials (full detail in `spec-driven-development-guide.md`)

- **Interview before you spec.** A vague ask is not a requirement. Extract *what* (the change), *why*
  (the underlying goal), *for whom* (the consumer), *constraints* (budget, deadline, quota, latency),
  and the *success metric* — before writing a line of spec or code.
- **The metric is the spec.** State the ML/business metric and turn it into **acceptance criteria as
  testable conditions** ("p95 < 200 ms at 500 QPS on the eval set; quality ≥ baseline − 0.5%"). If you
  can't measure done, you're not ready to start.
- **Cost is a first-class section.** Estimate GPU/TPU-hours and dollars *before* the run. An expensive
  job with no cost estimate is a red flag, not a plan.
- **Write scope AND non-goals.** Non-goals prevent scope creep and tell reviewers what you deliberately
  excluded.
- **SLOs/SLAs explicitly:** latency (p50/p95/p99), throughput (QPS/tokens-per-sec), availability. Vague
  "fast" and "reliable" are not commitments.
- **Failure modes & blast radius:** what breaks, who it takes down, the rollback/exit plan. Multi-tenant
  clusters and shared quota mean your failure is someone else's outage.
- **Data & dependencies, security & quota:** where the data comes from and its licensing/PII status;
  what services/teams you depend on; quota and multi-tenancy isolation.
- **Open questions are part of the spec.** Listing unknowns is honest and routes the right reviewers;
  hiding them defers the cost to build time at 100x the price.
- **Checkpoint: the spec is reviewed and agreed before Plan/Build.** A spec written and never read by a
  stakeholder bought you nothing.

## Related skills

- `[[engineering-lifecycle]]` — the umbrella; Define → Plan → Build → Verify → Ship. Start here.
- `[[task-planning-decomposition]]` — the next stage: turn the agreed spec into an ordered plan.
- `[[ml-system-design]]` — designing the architecture the spec commits to (serving stack, training topo).
- `[[ml-evaluation-evals]]` — designing the metric and eval harness your acceptance criteria reference.
- `[[staff-plus-engineering]]` — RFC/design-doc writing craft, driving alignment, and review at scale.