메뉴
Use when starting any non-trivial feature or project, or when docs and code have drifted — write the design chain before or alongside code and reconcile specs onto reality.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | spec-driven-development |
| description | Use when starting any non-trivial feature or project, or when docs and code have drifted — write the design chain before or alongside code and reconcile specs onto reality. |
Author an ordered design chain — BRIEF → RESEARCH → SPECS → DESIGN → TASKS — before or alongside writing implementation code, then keep those specs reconciled onto the code that actually shipped. The chain is not ceremony: each phase feeds the next, and the specs stay alive as versioned artifacts after launch.
Reach for this when:
Red-flag thoughts that mean STOP and apply this skill:
Code written without a spec encodes decisions you never examined; the design doc you back-fill afterward just rationalizes whatever you happened to type. Separating what from how lets reviewers catch a wrong requirement before you've spent days building the right mechanism for it. Recording verdicts in the doc means a settled debate stays settled — re-opening it in the next phase burns time and erodes trust in the chain. And a spec that freezes at its original optimistic claims becomes a lie the moment code diverges: the next person reads it, believes it, and builds on a fiction. Reconciling the spec onto reality keeps the document worth reading, which is the only thing that keeps it being read.
On the project this was distilled from — a hexagonal, human-in-the-loop AI agent shipped to a cloud platform — the docs/BRIEF.md header literally carried its place in the chain: "Status: Approved — feeds SPECS → DESIGN → TASKS → TDD build." RESEARCH closed with a peer-review addendum (§12) whose verdict, "ACCEPT-WITH-NOTES," was then "carried into SPECS/DESIGN (they refine the design; they are not re-research)" — the notes moved forward as refinements rather than being re-argued. After launch, when the build diverged from the plan, the team didn't abandon the docs: SPECS went to v0.4 and DESIGN to v1.4, "reconciled to delivered code — HTTP API + observability un-deferred, decision thresholds now YAML-tunable." The specs described what actually ran. You can apply all of this on any stack: name your phases, review each, version the specs, reconcile after divergence.
What a machine can check: the chain's structure, not its wisdom. A spec-structure lint — every phase doc carries a status line and a recorded review verdict, every phase names the doc it consumes, cross-links resolve — plus a version bump asserted when a spec's content changes. The judgment inside a phase is gated by the independent review the rule already requires (adversarial-lens-review is its binding form), with the verdict recorded where the lint can find it.
Use when wiring a project's dev workflow (local stack, test tiers, gates, docs), or when naming make targets in a repo that has siblings — build a thin self-documenting Makefile facade over real scripts, name targets from the shared cross-repo vocabulary, and split env files by owner so targets consume them but never write them.
Use when you need to prove a feature actually delivers its intended outcome to a user or caller, not just that its code paths run — write executable acceptance tests against real, observable outcomes, derived from the spec before or independent of the implementation.
Use when adding any new capability to a working system — ship it behind a flag or optional collaborator that defaults to prior behavior.
Use when a spec, plan, or implementation must be independently reviewed before it is trusted, committed, or advanced to the next phase — dispatch a fresh reviewer per named lens whose job is to refute the artifact, not confirm it.
Use when building automation that edits, tests, or deploys itself — an agent that regenerates its own code, a self-updating pipeline, any loop that modifies the thing running it.
Use when about to call any integration, deployment, or hard guarantee "done" — prove it live end-to-end and capture the run as evidence.
