sdd-tool 0.2.0 → 0.4.0

package/README.md

@@ -2,6 +2,7 @@
 
 **Spec-Driven Development CLI** - 명세 기반 개발을 위한 통합 CLI 도구
 
+[![npm version](https://img.shields.io/npm/v/sdd-tool)](https://www.npmjs.com/package/sdd-tool)
 [![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)
@@ -28,7 +29,7 @@ npm install -g sdd-tool
 pnpm add -g sdd-tool
 
 # 또는 로컬에서 실행
-git clone <repository>
+git clone https://github.com/JakeB-5/sdd-tool.git
 cd sdd-tool
 pnpm install
 pnpm run build
@@ -40,13 +41,16 @@ pnpm run build
 # 1. 프로젝트 초기화
 sdd init
 
-# 2. 새 기능 생성
+# 2. 워크플로우 시작 (통합 진입점)
+sdd start
+
+# 3. 새 기능 생성
 sdd new user-auth --title "사용자 인증" --all
 
-# 3. 스펙 검증
+# 4. 스펙 검증
 sdd validate
 
-# 4. 프로젝트 상태 확인
+# 5. 프로젝트 상태 확인
 sdd status
 ```
 
@@ -70,6 +74,19 @@ sdd init --force      # 기존 파일 덮어쓰기
 ├── changes/          # 변경 제안
 ├── archive/          # 완료된 변경
 └── templates/        # 템플릿 파일
+.claude/
+└── commands/         # Claude 슬래시 커맨드
+```
+
+### `sdd start`
+
+통합 워크플로우 진입점입니다.
+
+```bash
+sdd start                          # 상태 확인 및 워크플로우 메뉴
+sdd start --status                 # 상태만 표시
+sdd start --workflow new-feature   # 특정 워크플로우 시작
+sdd start --workflow change-spec   # 변경 워크플로우
 ```
 
 ### `sdd new`
@@ -83,12 +100,17 @@ sdd new <feature-name>
 # 옵션
 sdd new auth --title "인증 기능" --description "사용자 인증"
 sdd new auth --all              # spec, plan, tasks, checklist 모두 생성
+sdd new auth --numbered         # 자동 번호 부여 (feature/001-auth)
 sdd new auth --no-branch        # Git 브랜치 생성 안 함
 
 # 서브커맨드
 sdd new plan <feature>          # 구현 계획 생성
 sdd new tasks <feature>         # 작업 분해 생성
 sdd new checklist               # 워크플로우 체크리스트 생성
+sdd new counter                 # 기능 번호 카운터 관리
+sdd new counter --peek          # 다음 번호 확인
+sdd new counter --history       # 생성 이력
+sdd new counter --set <n>       # 번호 설정
 ```
 
 ### `sdd validate`
@@ -99,6 +121,9 @@ sdd new checklist               # 워크플로우 체크리스트 생성
 sdd validate                    # 전체 검증
 sdd validate path/to/spec.md    # 특정 파일 검증
 sdd validate --strict           # 엄격 모드 (경고도 에러)
+sdd validate --check-links      # 참조 링크 유효성 검사
+sdd validate --constitution     # Constitution 위반 검사 (기본값)
+sdd validate --no-constitution  # Constitution 검사 스킵
 sdd validate --quiet            # 조용한 모드
 ```
 
@@ -106,6 +131,24 @@ sdd validate --quiet            # 조용한 모드
 - YAML frontmatter 존재 및 형식
 - RFC 2119 키워드 사용
 - GIVEN-WHEN-THEN 시나리오 포함
+- 참조 링크 유효성 (--check-links)
+- Constitution 원칙 위반 (--constitution)
+
+### `sdd constitution`
+
+프로젝트 Constitution(헌법)을 관리합니다.
+
+```bash
+sdd constitution                # Constitution 표시
+sdd constitution show           # Constitution 내용 표시
+sdd constitution version        # 버전만 표시
+sdd constitution validate       # 형식 검증
+sdd constitution history        # 변경 이력 조회
+sdd constitution bump           # 버전 업데이트
+sdd constitution bump --major   # 주요 변경 (원칙 삭제 등)
+sdd constitution bump --minor   # 기능 추가
+sdd constitution bump --patch   # 문구 수정
+```
 
 ### `sdd change`
 
@@ -113,10 +156,13 @@ sdd validate --quiet            # 조용한 모드
 
 ```bash
 sdd change                      # 새 변경 제안 생성
-sdd change CHG-001              # 특정 변경 조회
-sdd change --list               # 변경 목록
-sdd change apply CHG-001        # 변경 적용
-sdd change archive CHG-001      # 변경 아카이브
+sdd change -t "제목"            # 제목과 함께 생성
+sdd change -l                   # 진행 중인 변경 목록
+sdd change <id>                 # 특정 변경 조회
+sdd change diff <id>            # 변경 내용 diff
+sdd change validate <id>        # 변경 제안 검증
+sdd change apply <id>           # 변경 적용
+sdd change archive <id>         # 변경 아카이브
 ```
 
 ### `sdd impact`
@@ -124,9 +170,60 @@ sdd change archive CHG-001      # 변경 아카이브
 스펙 변경의 영향도를 분석합니다.
 
 ```bash
+# 기본 영향도 분석
 sdd impact <feature>            # 특정 기능 영향도 분석
-sdd impact --graph              # 의존성 그래프 출력 (Mermaid)
+sdd impact <feature> --graph    # 의존성 그래프 출력 (Mermaid)
 sdd impact <feature> --json     # JSON 형식 출력
+
+# 코드 영향도 분석
+sdd impact <feature> --code     # 스펙 변경이 코드에 미치는 영향 분석
+sdd impact <feature> --code --json  # JSON 형식
+
+# 리포트 및 변경 분석
+sdd impact report               # 전체 프로젝트 리포트
+sdd impact report --json        # JSON 형식 리포트
+sdd impact change <id>          # 변경 제안 영향도 분석
+
+# What-if 시뮬레이션
+sdd impact simulate <feature> <proposal>  # 변경 전 영향도 예측
+sdd impact simulate auth change-001       # 예시
+```
+
+코드 영향도 분석은 다음 방법으로 스펙-코드 연결을 탐지합니다:
+- 주석 참조: `// spec: feature-id`, `/* spec: feature-id */`, `@spec feature-id`
+- 파일명/디렉토리명 매칭: `auth.ts` ↔ `auth` 스펙
+- 매핑 설정: `.sdd/code-mapping.json` 파일 사용
+
+### `sdd transition`
+
+워크플로우 간 전환을 수행합니다.
+
+```bash
+sdd transition new-to-change <spec-id>    # new → change 전환
+sdd transition change-to-new <change-id>  # change → new 전환
+sdd transition guide                       # 전환 가이드
+```
+
+### `sdd migrate`
+
+기존 문서를 SDD 형식으로 마이그레이션합니다.
+
+```bash
+sdd migrate docs <source>       # 문서 마이그레이션
+sdd migrate analyze <file>      # 문서 분석
+sdd migrate scan [dir]          # 디렉토리 스캔
+```
+
+### `sdd cicd`
+
+CI/CD 파이프라인을 설정합니다.
+
+```bash
+sdd cicd setup                  # GitHub Actions 설정
+sdd cicd setup gitlab           # GitLab CI 설정
+sdd cicd setup all              # 모든 플랫폼 설정
+sdd cicd hooks                  # Git hooks 설정
+sdd cicd check                  # CI 검증 실행
 ```
 
 ### `sdd status`
@@ -158,14 +255,8 @@ AI 도구용 슬래시 커맨드 프롬프트를 출력합니다.
 ```bash
 sdd prompt                      # 사용 가능한 명령어 목록
 sdd prompt --list               # 명령어 목록
-sdd prompt change               # /sdd:change 프롬프트
-sdd prompt new                  # /sdd:new 프롬프트
-sdd prompt plan                 # /sdd:plan 프롬프트
-sdd prompt tasks                # /sdd:tasks 프롬프트
-sdd prompt apply                # /sdd:apply 프롬프트
-sdd prompt archive              # /sdd:archive 프롬프트
-sdd prompt impact               # /sdd:impact 프롬프트
-sdd prompt validate             # /sdd:validate 프롬프트
+sdd prompt new                  # /sdd.new 프롬프트
+sdd prompt change               # /sdd.change 프롬프트
 ```
 
 ## 워크플로우
@@ -173,25 +264,101 @@ sdd prompt validate             # /sdd:validate 프롬프트
 ### 신규 기능 개발
 
 ```
-1. sdd new <feature> --all      # 기능 생성 (spec, plan, tasks)
-2. spec.md 작성                 # 요구사항 정의
-3. sdd validate                 # 명세 검증
-4. plan.md 작성                 # 구현 계획
-5. tasks.md 기반 구현           # 작업별 구현
-6. sdd change archive           # 완료 후 아카이브
+1. sdd start                    # 워크플로우 시작
+2. sdd new <feature> --all      # 기능 생성 (spec, plan, tasks)
+3. spec.md 작성                 # 요구사항 정의
+4. sdd validate                 # 명세 검증
+5. plan.md 작성                 # 구현 계획
+6. tasks.md 기반 구현           # 작업별 구현
+7. sdd change archive           # 완료 후 아카이브
 ```
 
 ### 기존 기능 변경
 
 ```
-1. sdd change                   # 변경 제안 생성
+1. sdd change -t "변경 제목"    # 변경 제안 생성
 2. proposal.md 작성             # 변경 내용 정의
 3. sdd impact <feature>         # 영향도 분석
-4. 검토 및 승인
-5. sdd change apply             # 변경 적용
-6. sdd change archive           # 아카이브
+4. sdd change validate <id>     # 검증
+5. sdd change apply <id>        # 변경 적용
+6. sdd change archive <id>      # 아카이브
 ```
 
+### 워크플로우 전환
+
+작업 중 워크플로우를 변경해야 할 때:
+
+```
+# 새 기능 → 변경 제안 (기존 스펙과 중복 발견 시)
+sdd transition new-to-change <spec-id>
+
+# 변경 → 새 기능 (범위가 커서 분리 필요 시)
+sdd transition change-to-new <change-id>
+```
+
+## Claude 슬래시 커맨드
+
+`sdd init` 실행 시 `.claude/commands/` 디렉토리에 Claude Code용 슬래시 커맨드가 자동 생성됩니다.
+
+### 기본 워크플로우 커맨드
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/sdd.start` | 통합 진입점 - 워크플로우 시작 |
+| `/sdd.new` | 새 기능 명세 작성 |
+| `/sdd.plan` | 구현 계획 작성 |
+| `/sdd.tasks` | 작업 분해 |
+| `/sdd.implement` | 순차적 구현 진행 |
+| `/sdd.validate` | 스펙 형식 검증 |
+| `/sdd.status` | 프로젝트 상태 확인 |
+| `/sdd.change` | 변경 제안 작성 |
+| `/sdd.constitution` | Constitution 관리 |
+
+### 고급 커맨드
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/sdd.chat` | 대화형 SDD 어시스턴트 |
+| `/sdd.guide` | 전체 워크플로우 가이드 |
+| `/sdd.transition` | 워크플로우 전환 |
+| `/sdd.analyze` | 요청 분석 및 규모 판단 |
+| `/sdd.research` | 기술 리서치 문서 작성 |
+| `/sdd.data-model` | 데이터 모델 문서 작성 |
+| `/sdd.prepare` | 환경 준비 가이드 |
+
+### 사용법
+
+Claude Code에서 슬래시 커맨드를 입력하면 해당 워크플로우가 자동으로 실행됩니다:
+
+```
+/sdd.start      # 워크플로우 시작
+/sdd.new        # 새 기능 명세 작성 시작
+/sdd.chat       # 대화형 모드로 SDD 작업
+```
+
+### 워크플로우 예시
+
+1. **대화형 모드로 시작**
+   ```
+   /sdd.chat
+   → 자연어로 SDD 작업 수행
+   → 질문/작성/검토/실행 모드 지원
+   ```
+
+2. **새 기능 개발**
+   ```
+   /sdd.new
+   → 기능명과 설명 입력
+   → spec.md 자동 생성 및 작성 안내
+   ```
+
+3. **워크플로우 전환**
+   ```
+   /sdd.transition
+   → new ↔ change 워크플로우 전환
+   → 전환 가이드 제공
+   ```
+
 ## 스펙 파일 형식
 
 ### spec.md
@@ -202,6 +369,7 @@ id: feature-id
 title: "기능 제목"
 status: draft
 created: 2025-12-21
+constitution_version: 1.0.0
 depends: null
 ---
 
@@ -238,6 +406,93 @@ depends: null
 | **MAY** | 선택적 | "다크 모드를 지원할 수 있다(MAY)" |
 | **SHALL NOT** | 절대 금지 | "평문 비밀번호를 저장해서는 안 된다(SHALL NOT)" |
 
+## CI/CD 통합
+
+### GitHub Actions
+
+```bash
+sdd cicd setup github
+# .github/workflows/sdd-validate.yml 생성
+```
+
+### GitLab CI
+
+```bash
+sdd cicd setup gitlab
+# .gitlab-ci-sdd.yml 생성
+```
+
+### Git Hooks
+
+```bash
+sdd cicd hooks
+# .husky/pre-commit, pre-push 생성
+```
+
+## 고급 기능
+
+### 코드 매핑 설정
+
+`.sdd/code-mapping.json` 파일을 사용하여 스펙과 코드 파일 간의 명시적 매핑을 정의할 수 있습니다:
+
+```json
+{
+  "version": "1.0.0",
+  "mappings": [
+    {
+      "specId": "user-auth",
+      "files": [
+        "src/core/auth.ts",
+        "src/services/auth-service.ts"
+      ],
+      "directories": [
+        "src/auth/"
+      ]
+    },
+    {
+      "specId": "payment",
+      "files": [
+        "src/payment/handler.ts"
+      ]
+    }
+  ],
+  "patterns": {
+    "include": ["src/**/*.ts"],
+    "exclude": ["**/*.test.ts", "**/*.spec.ts"]
+  }
+}
+```
+
+### Constitution 위반 검증
+
+스펙이 Constitution에 정의된 원칙을 위반하는지 자동으로 검사합니다:
+
+```bash
+# Constitution 위반 검사 포함 (기본값)
+sdd validate
+
+# Constitution 검사 스킵
+sdd validate --no-constitution
+```
+
+위반 감지 예시:
+- Constitution: "평문 비밀번호를 저장해서는 안 된다(SHALL NOT)"
+- 스펙: "비밀번호를 평문으로 저장한다" → 위반 경고 출력
+
+### What-if 시뮬레이션
+
+변경을 적용하기 전에 영향도를 예측합니다:
+
+```bash
+sdd impact simulate <feature> <proposal>
+```
+
+시뮬레이션 결과:
+- 현재 상태 vs 변경 후 상태 비교
+- 리스크 점수 변화
+- 새로 영향받는 스펙 목록
+- 권장사항 및 경고
+
 ## 개발
 
 ```bash
@@ -278,7 +533,12 @@ sdd-tool/
 │   │   │   ├── impact.ts
 │   │   │   ├── status.ts
 │   │   │   ├── list.ts
-│   │   │   └── prompt.ts
+│   │   │   ├── prompt.ts
+│   │   │   ├── constitution.ts
+│   │   │   ├── start.ts
+│   │   │   ├── transition.ts
+│   │   │   ├── migrate.ts
+│   │   │   └── cicd.ts
 │   │   └── index.ts
 │   ├── core/                   # 핵심 로직
 │   │   ├── spec/               # 스펙 파서/검증