# Spec Driven Development

> 기능 구현을 위한 테크스펙과 구현 계획 문서를 작성합니다. 스펙 주도 개발 워크플로우를 지원합니다.

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

---


# 스펙 주도 개발 (Spec Driven Development)

## 개요

이 skill은 기능 구현 전에 테크스펙과 구현 계획 문서를 체계적으로 작성하도록 도와줍니다.

---

## 핵심 원칙: 테크스펙이 가장 중요하다

> **"코드는 테크스펙의 구현일 뿐이다. 테크스펙 없이 코드를 작성하지 마라."**

### 왜 테크스펙이 중요한가?

1. **명확한 방향 설정**: 구현 전에 무엇을, 왜, 어떻게 만들지 명확히 정의
2. **설계 오류 조기 발견**: 코드 작성 전에 설계 문제를 발견하고 수정
3. **커뮤니케이션 도구**: 팀원, 미래의 자신과의 명확한 의사소통
4. **의사결정 기록**: 기술적 결정의 이유와 트레이드오프 문서화
5. **구현 품질 향상**: 충분한 사전 검토로 더 나은 코드 품질 확보

### 테크스펙 작성 원칙

- **최대한 자세하게**: 모호함 없이 구체적으로 작성
- **모든 엣지 케이스 고려**: 예외 상황과 경계 조건 명시
- **코드 수준의 상세함**: 주요 타입, 함수 시그니처, 데이터 구조 포함
- **Why를 명확히**: 단순히 What이 아닌, 왜 그렇게 결정했는지 기록
- **검증 가능한 요구사항**: 테스트로 검증할 수 있는 형태로 작성

### 테크스펙 완성 기준

테크스펙은 다음 질문에 모두 답할 수 있어야 완성된 것이다:

- [ ] 이 기능이 해결하는 문제가 명확한가?
- [ ] 모든 기능적/비기능적 요구사항이 정의되었는가?
- [ ] 도메인 모델과 타입이 구체적으로 설계되었는가?
- [ ] API 인터페이스가 명확하게 정의되었는가?
- [ ] 데이터 모델과 스키마가 설계되었는가?
- [ ] 기술 선택의 이유가 문서화되었는가?
- [ ] 위험 요소와 완화 방안이 식별되었는가?
- [ ] 테스트 전략이 수립되었는가?

---

## 워크플로우

1. **테크스펙 작성** (가장 중요): 기능의 요구사항, 설계, 기술적 결정사항을 **최대한 자세하게** 문서화
2. **구현 계획 작성**: 테크스펙 기반으로 단계별 구현 계획과 체크리스트 생성

## 파일 구조

```
docs/spec/
├── 001-기능명/
│   ├── TECH-SPEC.md           # 테크스펙
│   └── PLAN.md                # 구현 계획
├── 002-기능명/
│   ├── TECH-SPEC.md
│   └── PLAN.md
└── ...
```

## 사용법

### 1. 새 기능 테크스펙 작성

사용자가 기능에 대해 설명하면:

1. `docs/spec/` 디렉토리에서 기존 폴더 번호 확인
2. 다음 번호로 `docs/spec/NNN-기능명/` 디렉토리 생성
3. [TECH-SPEC.template.md](./TECH-SPEC.template.md) 템플릿을 기반으로 `TECH-SPEC.md` 작성

### 2. 구현 계획 작성

테크스펙이 완성되면:

1. **사용자에게 PLAN 문서 작성 여부 확인** (필수)
   - "테크스펙 작성이 완료되었습니다. 구현 계획(PLAN) 문서를 작성할까요?"
   - 사용자가 명시적으로 허락할 때까지 PLAN 작성을 진행하지 않음
2. 사용자 승인 후, 동일 디렉토리에 `PLAN.md` 파일 생성
3. [PLAN.template.md](./PLAN.template.md) 템플릿을 기반으로 문서 작성
4. 각 단계별 체크리스트 포함

---

## 템플릿 파일

- **테크스펙 템플릿**: [TECH-SPEC.template.md](./TECH-SPEC.template.md)
- **구현 계획 템플릿**: [PLAN.template.md](./PLAN.template.md)

---

## 진행 방법

### 테크스펙 작성 시

1. 사용자로부터 기능 요구사항 청취
2. `docs/spec/` 디렉토리의 기존 파일 확인하여 다음 번호 결정
3. 테크스펙 템플릿을 기반으로 문서 작성
4. 사용자와 함께 요구사항 및 설계 검토

### 구현 계획 작성 시

> **중요**: 테크스펙 완성 후 반드시 사용자에게 PLAN 작성 허락을 받아야 합니다.
> 사용자가 명시적으로 승인하기 전까지 PLAN 문서 작성을 시작하지 마세요.

1. 테크스펙 완성 후 사용자에게 PLAN 작성 여부 질문
2. **사용자 승인 후에만** 해당 테크스펙 문서 읽기
3. 테크스펙 기반으로 구현 단계 도출
4. 각 단계별 체크리스트 작성
5. 의존성 및 선행 조건 명시

### 구현 진행 시

1. 구현 계획 문서의 체크리스트 확인
2. 각 작업 완료 시 체크 표시 (`- [x]`)
3. 단계 완료 시 상태 테이블 업데이트
4. 예상치 못한 변경사항은 계획 문서에 반영

---

## 디렉토리 번호 규칙

```bash
# 기존 디렉토리 확인
ls -d docs/spec/[0-9]*/ 2>/dev/null | sort -r | head -1

# 다음 번호 결정
# 기존 디렉토리가 없으면: 001
# 기존 최신이 005면: 006
```

## 디렉토리명 규칙

- 번호: 3자리 (001, 002, ...)
- 기능명: 영문 소문자 + 하이픈 (kebab-case)
- 예시:
  - `docs/spec/001-user-authentication/TECH-SPEC.md`
  - `docs/spec/001-user-authentication/PLAN.md`
  - `docs/spec/002-order-execution/TECH-SPEC.md`
  - `docs/spec/002-order-execution/PLAN.md`

---

## 주의사항

1. **테크스펙 먼저**: 구현 계획은 반드시 테크스펙 완성 후 작성
2. **사용자 승인 필수**: PLAN 문서는 사용자가 명시적으로 허락할 때만 작성 (자동으로 진행하지 않음)
3. **점진적 상세화**: 처음부터 완벽할 필요 없음, 점진적으로 보완
4. **변경 추적**: 중요한 변경사항은 문서에 기록
5. **체크리스트 활용**: 구현 진행 상황을 체크리스트로 추적
6. **프로젝트 원칙 준수**: CLAUDE.md의 함수형 DDD 원칙 따르기