sdd-tool 0.7.1 → 1.0.1

package/README.md

@@ -3,13 +3,16 @@
 **Spec-Driven Development CLI** - AI와 함께하는 명세 기반 개발 도구
 
 [![npm version](https://img.shields.io/npm/v/sdd-tool)](https://www.npmjs.com/package/sdd-tool)
+[![CI](https://github.com/JakeB-5/sdd-tool/actions/workflows/ci.yml/badge.svg)](https://github.com/JakeB-5/sdd-tool/actions/workflows/ci.yml)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/typescript-5.x-blue)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
+📚 **[문서 사이트](https://jakeb-5.github.io/sdd-tool/)** | 🚀 **[시작하기](https://jakeb-5.github.io/sdd-tool/guide/getting-started)** | 📋 **[CLI 레퍼런스](https://jakeb-5.github.io/sdd-tool/cli/)**
+
 ## 개요
 
-SDD Tool은 **Claude Code**와 함께 사용하도록 설계된 명세 기반 개발(Spec-Driven Development) CLI입니다. 슬래시 커맨드를 통해 AI와 대화하며 명세를 작성하고, 코드를 구현합니다.
+SDD Tool은 **Claude Code**와 함께 사용하도록 설계된 명세 기반 개발(Spec-Driven Development) CLI입니다. **슬래시 커맨드**를 통해 AI와 대화하며 명세를 작성하고, 코드를 구현합니다.
 
 ### 핵심 개념
 
@@ -29,50 +32,132 @@ npm install -g sdd-tool
 
 ---
 
-## Claude Code와 함께 시작하기
-
-SDD Tool은 Claude Code의 슬래시 커맨드와 통합되어, AI와 대화하며 명세 기반 개발을 진행합니다.
-
-### Step 1: 프로젝트 초기화
+## 빠른 시작
 
 ```bash
+# 1. 프로젝트 초기화 (슬래시 커맨드 29개 자동 생성)
 sdd init
-```
 
-이 명령은 다음을 생성합니다:
-- `.sdd/` - 명세 디렉토리 (constitution.md, specs/, changes/)
-- `.claude/commands/` - **26개의 슬래시 커맨드** 자동 생성
+# 2. Claude Code 실행
+claude
 
-### Step 2: Claude Code 실행
+# 3. 슬래시 커맨드로 워크플로우 시작
+/sdd.start
+```
 
-프로젝트 디렉토리에서 Claude Code를 실행합니다:
+---
+
+## 전체 워크플로우
 
-```bash
-claude
 ```
+┌─────────────────────────────────────────────────────────────┐
+│                    SDD 슬래시 커맨드 워크플로우                  │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. /sdd.start        → 워크플로우 시작                      │
+│     │                                                       │
+│     ▼                                                       │
+│  2. /sdd.constitution → 프로젝트 원칙 정의                   │
+│     │                                                       │
+│     ▼                                                       │
+│  3. /sdd.new          → 기능 명세 작성 (spec.md)             │
+│     │                                                       │
+│     ▼                                                       │
+│  4. /sdd.plan         → 구현 계획 수립 (plan.md)             │
+│     │                                                       │
+│     ▼                                                       │
+│  5. /sdd.tasks        → 작업 분해 (tasks.md)                 │
+│     │                                                       │
+│     ▼                                                       │
+│  6. /sdd.prepare      → 서브에이전트/스킬 점검                │
+│     │                                                       │
+│     ▼                                                       │
+│  7. /sdd.implement    → 순차적 구현                          │
+│     │                                                       │
+│     ▼                                                       │
+│  8. /sdd.validate     → 명세 검증                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 슬래시 커맨드 (29개)
+
+`sdd init` 실행 시 `.claude/commands/`에 자동 생성됩니다.
+
+### 핵심 워크플로우
+
+| 커맨드 | 설명 | 사용 예시 |
+|--------|------|----------|
+| `/sdd.start` | 통합 진입점 | `/sdd.start` |
+| `/sdd.constitution` | 프로젝트 원칙 관리 | `/sdd.constitution React 기반 할일 앱` |
+| `/sdd.new` | 새 기능 명세 작성 | `/sdd.new 사용자 인증 기능` |
+| `/sdd.plan` | 구현 계획 작성 | `/sdd.plan` |
+| `/sdd.tasks` | 작업 분해 | `/sdd.tasks` |
+| `/sdd.prepare` | 서브에이전트/스킬 점검 | `/sdd.prepare` |
+| `/sdd.implement` | 순차적 구현 | `/sdd.implement` |
+| `/sdd.validate` | 스펙 검증 | `/sdd.validate` |
+
+### 변경 관리
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/sdd.change` | 기존 스펙 변경 제안 |
+| `/sdd.impact` | 변경 영향도 분석 |
+| `/sdd.transition` | new ↔ change 워크플로우 전환 |
+
+### 분석 및 품질
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/sdd.analyze` | 요청 분석 및 규모 판단 |
+| `/sdd.quality` | 스펙 품질 점수 산출 |
+| `/sdd.report` | 프로젝트 리포트 생성 |
+| `/sdd.search` | 스펙 검색 |
+| `/sdd.status` | 프로젝트 상태 확인 |
+| `/sdd.list` | 항목 목록 조회 |
+| `/sdd.sync` | 스펙-코드 동기화 검증 |
+| `/sdd.diff` | 스펙 변경사항 시각화 |
+| `/sdd.export` | 스펙 내보내기 (HTML, JSON) |
+
+### 문서 생성
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/sdd.research` | 기술 리서치 문서 |
+| `/sdd.data-model` | 데이터 모델 문서 |
+| `/sdd.guide` | 워크플로우 가이드 |
+
+### 운영
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/sdd.chat` | 대화형 SDD 어시스턴트 |
+| `/sdd.watch` | 파일 감시 모드 |
+| `/sdd.migrate` | 외부 도구에서 마이그레이션 |
+| `/sdd.cicd` | CI/CD 설정 |
+| `/sdd.prompt` | 프롬프트 출력 |
+
+---
 
-### Step 3: 워크플로우 시작
+## 워크플로우 상세
 
-Claude Code에서 슬래시 커맨드를 입력합니다:
+### Step 1: /sdd.start
+
+프로젝트 상태를 분석하고 다음 작업을 안내합니다:
 
 ```
 /sdd.start
 ```
 
-AI가 프로젝트 상태를 분석하고, 다음 작업을 안내합니다:
 - 신규 프로젝트: Constitution 작성 권장
 - 기존 프로젝트: 워크플로우 선택 메뉴 제공
 
-### Step 4: Constitution(헌법) 작성
+### Step 2: /sdd.constitution
 
 프로젝트의 핵심 원칙을 정의합니다:
 
-```
-/sdd.constitution
-```
-
-신규 프로젝트의 경우, 프로젝트 설명을 함께 입력할 수 있습니다:
-
 ```
 /sdd.constitution React 기반 할일 관리 앱
 ```
@@ -82,167 +167,99 @@ AI가 `.sdd/constitution.md`를 분석하고, 프로젝트 원칙 작성을 도
 - 기술 원칙 (Technical Principles)
 - 금지 사항 (Forbidden)
 
-### Step 5: 새 기능 명세 작성
+### Step 3: /sdd.new
 
 기능 명세를 AI와 함께 작성합니다:
 
-```
-/sdd.new
-```
-
-필요한 기능을 함께 입력하면 AI가 바로 명세 작성을 시작합니다:
-
 ```
 /sdd.new 사용자 인증 기능
 ```
 
 AI가 대화를 통해 다음을 생성합니다:
 - `spec.md` - 기능 명세 (RFC 2119 + GIVEN-WHEN-THEN)
-- `plan.md` - 구현 계획
-- `tasks.md` - 작업 분해
 
-### Step 6: 구현 진행
+### Step 4: /sdd.plan
 
-작업 목록을 기반으로 순차적 구현:
+구현 계획을 수립합니다:
 
 ```
-/sdd.implement
+/sdd.plan
 ```
 
-AI가 tasks.md를 읽고, TDD 방식으로 구현을 안내합니다.
+- 기술 결정사항과 근거
+- 구현 단계(Phase) 정의
+- 리스크 분석 및 완화 전략
 
----
+### Step 5: /sdd.tasks
 
-## 전체 워크플로우 예시
+작업을 실행 가능한 단위로 분해합니다:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  1. sdd init          → 프로젝트 초기화                      │
-│  2. claude            → Claude Code 실행                    │
-│  3. /sdd.start        → 워크플로우 시작                      │
-│  4. /sdd.constitution → 프로젝트 원칙 정의                   │
-│  5. /sdd.new          → 기능 명세 작성                       │
-│  6. /sdd.plan         → 구현 계획 수립                       │
-│  7. /sdd.tasks        → 작업 분해                           │
-│  8. /sdd.implement    → 순차적 구현                          │
-│  9. /sdd.validate     → 명세 검증                           │
-└─────────────────────────────────────────────────────────────┘
+/sdd.tasks
 ```
 
----
-
-## 구현 준비: sdd prepare
+- 각 작업은 2-4시간 내 완료 가능한 크기
+- 작업 간 의존성 표시
+- 우선순위: HIGH(🔴), MEDIUM(🟡), LOW(🟢)
 
-구현 전 필요한 Claude Code 서브에이전트와 스킬을 점검합니다.
+### Step 6: /sdd.prepare
 
-### 워크플로우
+구현에 필요한 Claude Code 도구를 점검합니다:
 
 ```
-/sdd.new → /sdd.plan → /sdd.tasks → sdd prepare → /sdd.implement
-                                         ↑
-                               서브에이전트/스킬 점검
+/sdd.prepare
 ```
 
-### 사용법
+**기능:**
+- tasks.md 분석하여 필요한 도구 자동 감지
+- 서브에이전트 (`.claude/agents/`) 존재 여부 확인
+- 스킬 (`.claude/skills/`) 존재 여부 확인
+- 누락된 도구 자동 생성
 
-```bash
-sdd prepare user-auth
-```
+**감지 대상:**
 
-tasks.md를 분석하여 필요한 도구를 자동으로 감지합니다:
-
-```
-ℹ 기능 'user-auth' 준비 점검 중...
+| 키워드 | 서브에이전트 | 스킬 |
+|--------|-------------|------|
+| 테스트, test | test-runner | test |
+| api, rest | api-scaffold | gen-api |
+| component | component-gen | gen-component |
+| database | - | db-migrate |
+| 문서, doc | - | gen-doc |
+| review | code-reviewer | review |
 
-✓ 분석 완료
+**CLI에서도 사용 가능:**
 
-총 작업 수: 5개
-서브에이전트: 2개 필요 (존재: 0, 누락: 2)
-스킬: 3개 필요 (존재: 1, 누락: 2)
-
-⚠ 누락된 서브에이전트:
-  - test-runner: 테스트 실행 및 결과 분석 에이전트
-  - api-scaffold: REST API 보일러플레이트 생성 에이전트
-
-⚠ 누락된 스킬:
-  - gen-api: API 엔드포인트 생성 스킬
-  - review: 코드 리뷰 스킬
-
-ℹ 보고서: .sdd/specs/user-auth/prepare.md
-ℹ 누락된 도구를 자동 생성하려면: sdd prepare user-auth --auto-approve
+```bash
+sdd prepare user-auth                 # 대화형
+sdd prepare user-auth --dry-run       # 미리보기
+sdd prepare user-auth --auto-approve  # 자동 생성
 ```
 
-### Claude Code 도구 위치
-
-| 도구 유형 | 위치 |
-|-----------|------|
-| 서브에이전트 | `.claude/agents/<name>.md` |
-| 스킬 | `.claude/skills/<name>/SKILL.md` |
-| 슬래시 커맨드 | `.claude/commands/<name>.md` |
-
-### 옵션
+### Step 7: /sdd.implement
 
-| 옵션 | 설명 |
-|------|------|
-| `--dry-run` | 파일 생성 없이 분석 결과만 출력 |
-| `--auto-approve` | 누락된 도구를 자동으로 생성 |
-| `--json` | JSON 형식으로 출력 |
-
----
-
-## 슬래시 커맨드 (26개)
-
-`sdd init` 실행 시 `.claude/commands/`에 자동 생성됩니다.
-
-### 핵심 워크플로우
-
-| 커맨드 | 설명 | 사용 시점 |
-|--------|------|----------|
-| `/sdd.start` | 통합 진입점 | 작업 시작 시 |
-| `/sdd.constitution` | 프로젝트 원칙 관리 | 프로젝트 초기 설정 |
-| `/sdd.new` | 새 기능 명세 작성 | 새 기능 개발 시 |
-| `/sdd.plan` | 구현 계획 작성 | 명세 작성 후 |
-| `/sdd.tasks` | 작업 분해 | 계획 수립 후 |
-| `/sdd.implement` | 순차적 구현 | 작업 분해 후 |
-| `/sdd.validate` | 스펙 검증 | 작성/수정 후 |
-
-### 변경 관리
-
-| 커맨드 | 설명 |
-|--------|------|
-| `/sdd.change` | 기존 스펙 변경 제안 |
-| `/sdd.impact` | 변경 영향도 분석 |
-| `/sdd.transition` | new ↔ change 워크플로우 전환 |
+작업 목록을 기반으로 순차적 구현:
 
-### 분석 및 품질
+```
+/sdd.implement
+```
 
-| 커맨드 | 설명 |
-|--------|------|
-| `/sdd.analyze` | 요청 분석 및 규모 판단 |
-| `/sdd.quality` | 스펙 품질 점수 산출 |
-| `/sdd.report` | 프로젝트 리포트 생성 |
-| `/sdd.search` | 스펙 검색 |
-| `/sdd.status` | 프로젝트 상태 확인 |
+AI가 tasks.md를 읽고, TDD 방식으로 구현을 안내합니다:
+1. 작업 상태를 "진행 중"으로 변경
+2. 테스트 작성
+3. 코드 구현
+4. 작업 상태를 "완료"로 변경
 
-### 문서 생성
+### Step 8: /sdd.validate
 
-| 커맨드 | 설명 |
-|--------|------|
-| `/sdd.research` | 기술 리서치 문서 |
-| `/sdd.data-model` | 데이터 모델 문서 |
-| `/sdd.guide` | 워크플로우 가이드 |
-| `/sdd.prepare` | 서브에이전트/스킬 점검 |
+명세 검증:
 
-### 운영
+```
+/sdd.validate
+```
 
-| 커맨드 | 설명 |
-|--------|------|
-| `/sdd.chat` | 대화형 SDD 어시스턴트 |
-| `/sdd.list` | 항목 목록 조회 |
-| `/sdd.watch` | 파일 감시 모드 |
-| `/sdd.migrate` | 외부 도구에서 마이그레이션 |
-| `/sdd.cicd` | CI/CD 설정 |
-| `/sdd.prompt` | 프롬프트 출력 |
+- RFC 2119 키워드 사용 여부
+- GIVEN-WHEN-THEN 형식 준수
+- 메타데이터 필수 필드 확인
 
 ---
 
@@ -328,6 +345,7 @@ sdd list                    # 목록 조회
 ```bash
 sdd new <name>              # 새 기능 생성
 sdd new <name> --all        # spec + plan + tasks 모두 생성
+sdd prepare <name>          # 서브에이전트/스킬 점검
 ```
 
 ### 변경 관리
@@ -342,50 +360,41 @@ sdd impact <feature>        # 영향도 분석
 
 ```bash
 sdd quality                 # 품질 분석
-sdd quality --min-score 70  # 최소 점수 기준
 sdd report                  # 리포트 생성
 sdd search <query>          # 스펙 검색
 ```
 
-### 구현 준비
-
-```bash
-sdd prepare <feature>              # 서브에이전트/스킬 점검
-sdd prepare <feature> --dry-run    # 변경 없이 분석만
-sdd prepare <feature> --auto-approve  # 누락 도구 자동 생성
-```
-
-### 운영
+### 동기화 및 변경 추적 (v0.8.0)
 
 ```bash
-sdd watch                   # 파일 감시
-sdd migrate detect          # 외부 도구 감지
-sdd cicd setup              # CI/CD 설정
-```
-
----
-
-## CI/CD 통합
+sdd sync                    # 스펙-코드 동기화 검증
+sdd sync user-auth          # 특정 스펙만 검증
+sdd sync --ci --threshold 80 # CI 모드 (동기화율 임계값)
+sdd sync --json             # JSON 출력
+sdd sync --markdown         # 마크다운 리포트
 
-### GitHub Actions
-
-```bash
-sdd cicd setup github
+sdd diff                    # 스펙 변경사항 (작업 디렉토리)
+sdd diff --staged           # 스테이징된 변경
+sdd diff abc123 def456      # 커밋 간 비교
+sdd diff --stat             # 통계 요약
+sdd diff --json             # JSON 출력
 ```
 
-### Git Hooks
+### 스펙 내보내기 (v0.9.0)
 
 ```bash
-sdd cicd hooks
+sdd export user-auth        # 단일 스펙 HTML 내보내기
+sdd export --all            # 전체 스펙 내보내기
+sdd export --format json    # JSON 형식
+sdd export --format markdown # 마크다운 병합
+sdd export -o ./docs/specs.html # 출력 경로 지정
+sdd export --theme dark     # 다크 테마
+sdd export --no-toc         # 목차 제외
 ```
 
-커밋 전 자동으로 스펙 검증이 실행됩니다.
-
 ---
 
-## 디렉토리 구조
-
-`sdd init` 실행 후 생성되는 구조:
+## Claude Code 도구 구조
 
 ```
 your-project/
@@ -396,16 +405,25 @@ your-project/
 │   │   └── feature-name/
 │   │       ├── spec.md
 │   │       ├── plan.md
-│   │       └── tasks.md
+│   │       ├── tasks.md
+│   │       └── prepare.md  # 도구 점검 결과
 │   ├── changes/            # 변경 제안
-│   ├── archive/            # 완료된 변경
-│   └── templates/          # 템플릿
+│   └── archive/            # 완료된 변경
+│
 └── .claude/
-    └── commands/           # 슬래시 커맨드 (26개)
-        ├── sdd.start.md
-        ├── sdd.new.md
-        ├── sdd.constitution.md
-        └── ...
+    ├── commands/           # 슬래시 커맨드 (29개)
+    │   ├── sdd.start.md
+    │   ├── sdd.new.md
+    │   ├── sdd.prepare.md
+    │   └── ...
+    ├── agents/             # 서브에이전트
+    │   ├── test-runner.md
+    │   └── api-scaffold.md
+    └── skills/             # 스킬
+        ├── test/
+        │   └── SKILL.md
+        └── gen-api/
+            └── SKILL.md
 ```
 
 ---
@@ -420,8 +438,34 @@ pnpm run build
 pnpm test
 ```
 
+### 문서 개발
+
+```bash
+pnpm run docs:dev      # 개발 서버
+pnpm run docs:build    # 빌드
+pnpm run docs:preview  # 미리보기
+```
+
+### 테스트 커버리지
+
+```bash
+pnpm run test:coverage  # 커버리지 리포트
+```
+
+---
+
+## 기여
+
+기여를 환영합니다! [CONTRIBUTING.md](CONTRIBUTING.md)를 참고해주세요.
+
+---
+
+## 변경 이력
+
+자세한 변경 이력은 [CHANGELOG.md](CHANGELOG.md)를 참고해주세요.
+
 ---
 
 ## 라이선스
 
-MIT License
+MIT License - 자세한 내용은 [LICENSE](LICENSE) 파일을 참고해주세요.