sdd-methodology

Category: Development & Coding | Uploader: skdkfk8758 | Downloads: 0 | Version: v1.0（Latest）
Use when referencing SDD principles. spec first, code second 철학, 스펙 구조(Overview→Requirements→Data Model→API→Edge Cases→Success Criteria), 스펙 품질 기준을 제공합니다. vs-plan, spec-writer가 참조합니다.
Changelog: Source: GitHub https://github.com/skdkfk8758/vibespec
Directory Structure

Current level: skills/sdd-methodology/
📄 SKILL.md 6.0 KB
SKILL.md

---
name: sdd-methodology
description: "Use when referencing SDD principles. spec first, code second 철학, 스펙 구조(Overview→Requirements→Data Model→API→Edge Cases→Success Criteria), 스펙 품질 기준을 제공합니다. vs-plan, spec-writer가 참조합니다."
type: domain
---

# Spec-Driven Development (SDD)

코드 작성 전에 스펙을 먼저 확정하는 개발 방법론. 구조화된 스펙이 설계 결정을 명시하고, 구현 방향을 안내하며, 검증 기준을 제공한다.

## Domain Context

**Spec-Driven Development**는 "spec first, code second" 철학에 기반한다. 전통적인 소프트웨어 개발에서 흔히 발생하는 문제 — 요구사항 모호, 구현 중 방향 변경, 완료 기준 부재 — 를 스펙 선행으로 해결한다.

SDD는 다음 관찰에서 출발한다:
- 코드를 작성하기 전에 "무엇을 만들 것인지" 명확히 하면, 구현 시간이 줄어든다
- 스펙이 없으면 구현자(사람 또는 AI)가 암묵적으로 설계 결정을 내리며, 이는 의도와 다를 수 있다
- 검증 가능한 완료 기준이 없으면, "완료"의 정의가 주관적이 된다

이 접근법은 Kent Beck의 "make it work, make it right, make it fast" 원칙과 상보적이다. SDD가 "무엇이 work인지"를 먼저 정의하고, TDD가 "work하는지"를 검증한다.

### Key Principles

1. **스펙이 코드에 선행한다.** 구현은 스펙의 실체화이며, 스펙에 없는 것은 구현하지 않는다. 스펙 범위가 곧 구현 범위다.

2. **구체성이 품질을 결정한다.** "에러를 적절히 처리한다"가 아니라 "404 응답 시 빈 배열을 반환한다"로 쓴다. 구체적 스펙은 구체적 코드를 낳는다.

3. **검증 가능해야 한다.** 모든 요구사항은 테스트 코드로 변환 가능한 형태여야 한다. "사용자 경험이 좋다"는 스펙이 아니라 감상이다.

4. **예시가 추상보다 낫다.** 입출력 예시, 데이터 샘플, 에러 시나리오를 포함해야 구현자가 의도를 오해하지 않는다.

5. **스펙은 살아있는 문서다.** 구현 중 발견된 엣지 케이스나 설계 변경은 스펙에 반영한다. 스펙과 코드의 괴리는 기술 부채다.

## 스펙 구조: 6섹션

SDD 스펙은 다음 6개 섹션으로 구성된다. 각 섹션은 독립적이면서도 순서대로 읽었을 때 전체 그림이 드러나도록 설계되어 있다.

### 1. Overview

한 문단으로 **무엇을**(what), **누구를 위해**(for whom), **왜**(why) 만드는지 요약한다.

- "왜"가 가장 중요하다. 동기가 불명확한 스펙은 방향을 잃기 쉽다
- 핵심 가치 제안(value proposition)을 포함한다
- 기술 용어보다 비즈니스 맥락으로 쓴다

**나쁜 예**: "Task 모델에 metrics 필드를 추가한다"
**좋은 예**: "태스크 완료 시 소요 시간, 테스트 수, 변경 파일 수를 자동 수집하여 팀의 개발 속도를 측정하고 병목을 식별할 수 있게 한다"

### 2. Requirements

MoSCoW 우선순위로 분류한다:

| 레벨 | 의미 | 기준 |
|------|------|------|
| **MUST** | 반드시 구현 | 이것 없이는 기능이 성립하지 않음 |
| **SHOULD** | 구현하면 좋음 | 없어도 핵심 기능은 동작 |
| **COULD** | 시간이 되면 | 향후 개선 후보 |

각 요구사항은 **검증 방법**을 함께 명시한다. "사용자 인증 필요" → 검증: "미인증 요청 시 401 반환 테스트".

비기능 요구사항(성능, 보안, 접근성)은 **정량적 기준**과 **측정 방법**을 테이블로 정리한다.

### 3. Data Model

엔티티, 필드, 타입, 제약조건, 관계를 정의한다.

- 필드 타입은 구현 언어의 실제 타입으로 쓴다 (string, number가 아니라 TEXT, INTEGER)
- 제약조건(PK, FK, UNIQUE, NOT NULL, DEFAULT)을 명시한다
- 관계(1:1, 1:N, N:M)와 FK를 표현한다
- 기존 스키마에 대한 변경이면 ALTER문을 포함한다

### 4. API / Interface

함수 시그니처, 파라미터, 리턴 타입, 에러 케이스를 정의한다.

- 시그니처는 실제 코드에 가까운 형태로 쓴다
- 에러 케이스마다 조건, 처리 방법, 반환값을 명시한다
- **입출력 예시**를 반드시 포함한다 — 실제 데이터로 작성한다

### 5. Edge Cases

알려진 엣지 케이스와 처리 방법을 정리한다.

- 최소 3개 이상 식별한다
- "발생 조건"과 "처리 방법"을 분리하여 명시한다
- 처리 방법이 결정되지 않은 경우 "TBD"로 표시하고, 구현 전에 결정한다

### 6. Success Criteria

기능이 성공했다고 판단할 수 있는 구체적 지표.

- **정량적 기준**: 테스트 커버리지, 응답 시간, 에러율 등 숫자로 측정 가능한 것
- **정성적 기준**: 기존 API와의 일관성, 코드 가독성 등 판단이 필요한 것
- 정량적 기준이 최소 1개 이상 있어야 한다

## 스펙 품질 체크리스트

스펙 작성 완료 후, 다음을 점검한다:

- [ ] Overview가 what / for whom / why를 모두 담고 있는가
- [ ] MUST 요구사항이 모두 테스트로 검증 가능한 형태인가
- [ ] Data Model에 필드 타입과 제약조건이 명시되어 있는가
- [ ] API/Interface에 에러 케이스와 입출력 예시가 포함되어 있는가
- [ ] Edge case가 최소 3개 이상 식별되었는가
- [ ] Success Criteria에 정량적 기준이 최소 1개 이상 있는가
- [ ] 모든 기술 용어가 초등학생도 이해할 수준으로 풀어쓰여 있는가

## 참고자료

- Kent Beck — *Test-Driven Development: By Example*: SDD의 "스펙 선행"과 TDD의 "테스트 선행"이 상보적으로 동작
- Martin Fowler — *Refactoring*: 스펙이 리팩토링의 안전망 역할 (변경 후 스펙 충족 여부로 회귀 검증)
- Dan Olsen — *The Lean Product Playbook*: 가치 제안을 스펙의 Overview에 반영하는 관점
- Teresa Torres — *Continuous Discovery Habits*: 검증 가능한 가정을 스펙의 Acceptance Criteria로 표현
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
sdd-methodology

Directory Structure

SKILL.md

Report

Notice
