Sdd spec

/claude-sdd:sdd-spec — 기술 명세서 생성

요구사항을 상세한 기술 명세서와 스펙 준수 체크리스트로 변환합니다.

사용법

/claude-sdd:sdd-spec                           # 단일: 기존 동작 / 멀티: 도메인 선택 요청
/claude-sdd:sdd-spec refresh                   # 스펙 재생성 (기존 편집 내용은 주석으로 유지)

# 멀티 도메인 옵션
/claude-sdd:sdd-spec --shared                  # 프로젝트 수준 공유 아키텍처만 생성/갱신
/claude-sdd:sdd-spec --domain=<id>             # 특정 도메인 스펙 생성
/claude-sdd:sdd-spec --domain=<id> refresh     # 특정 도메인 스펙 재생성
/claude-sdd:sdd-spec --all                     # 모든 도메인 스펙 일괄 생성

사전 조건

1. docs/specs/sdd-config.yaml을 읽어 프로젝트 유형(new/legacy)과 도메인 설정을 확인합니다.
2. 도메인 모드 감지: domains 키 존재 여부로 단일/멀티 도메인 모드를 결정합니다.
3. 요구사항 존재 확인:
   • 단일 도메인: docs/specs/01-requirements.md
   • 멀티 도메인: docs/specs/domains/<domain-id>/01-requirements.md
4. 요구사항이 존재하지 않으면 안내합니다: 먼저 /claude-sdd:sdd-intake를 실행하여 요구사항을 수집하세요.

집요한 상세 설계 모드 (spec_depth: thorough)

docs/specs/00-project-context.md가 존재하고 spec_depth: thorough가 설정되어 있으면 (/claude-sdd:sdd-godmode에서 생성), 모든 스펙을 집요하게 상세한 수준으로 생성합니다:

• API 스펙: 모든 엔드포인트의 완전한 JSON 스키마, 필드별 유효성 검사 규칙(정규식, 길이, 범위), 모든 HTTP 상태 코드별 에러 코드, 페이지네이션/필터링/정렬 상세, Rate limiting, 캐시 전략, 요청/응답 예시
• 데이터 모델: DDL 수준 스키마(CREATE TABLE 문), 인덱스 전략과 근거, 마이그레이션 윤곽, 시드 데이터, 소프트 삭제/감사 컬럼
• 아키텍처: 핵심 유스케이스별 시퀀스 다이어그램, 통합 포인트별 에러 처리 전략, 서킷 브레이커/리트라이 패턴, 헬스체크 설계
• 컴포넌트: 모든 공개 메서드의 완전한 시그니처, DI 전략, 에러 타입 계층 구조

이 모드가 아니면 기존 수준의 스펙을 생성합니다.

---

동작 (단일 도메인 모드)

신규 프로젝트의 경우 (type: new)

sdd-spec-writer 에이전트를 사용하여 다음을 생성합니다:

1. 02-architecture.md — 시스템 아키텍처

   • 기술 스택과 선정 근거
   • 모듈 구조 및 책임
   • 모듈 의존성 다이어그램
   • 공통 관심사 (에러 처리, 로깅, 설정)

2. 03-api-spec.md — API 명세서

   • HTTP 메서드가 포함된 모든 엔드포인트
   • 요청/응답 스키마 (JSON)
   • 필드별 유효성 검사 규칙
   • 모든 에러 코드 및 응답
   • 페이지네이션 및 속도 제한

3. 04-data-model.md — 데이터 모델

   • 모든 필드가 포함된 엔티티 정의
   • 필드 타입, 제약 조건, 기본값
   • 관계 및 외래 키
   • 목적이 명시된 인덱스
   • Enum 정의

4. 05-component-breakdown.md — 컴포넌트 분해

   • 모듈 책임
   • 공개 인터페이스 (타입 포함)
   • 의존성 (내부/외부)
   • 컴포넌트별 에러 처리

5. 06-spec-checklist.md — 스펙 준수 체크리스트

   • 위 스펙에서 검증 가능한 모든 항목
   • 카테고리 분류: ARCH, API, DM, COMP, TEST, SEC, PERF, UI
   • 각 항목은 해당 스펙 섹션을 참조
   • 하단에 진행률 추적기

레거시 프로젝트의 경우 (type: legacy)

sdd-spec-writer 에이전트를 사용하여 신규 프로젝트와 동일한 파일명으로 다음을 생성합니다. 현행 시스템을 기준으로 전체 문서화하되, 각 문서에 변경 태그와 영향 분석 섹션을 추가합니다:

1. 02-architecture.md — 현행 아키텍처

   • 기존 기술 스택, 모듈 구조, 의존성 다이어그램 (신규와 동일)
   • [레거시 추가] 변경 영향 분석 섹션: 영향 모듈, 위험 평가, 하위 호환성, 마이그레이션 계획

2. 03-api-spec.md — 현행 API 전체 문서화

   • 모든 엔드포인트의 완전한 스펙 (신규와 동일)
   • [레거시 추가] 변경 태그: 각 엔드포인트에 UNCHANGED/MODIFY/NEW/DEPRECATE 태그
   • [레거시 추가] 하위 호환성 전략

3. 04-data-model.md — 현행 데이터 모델

   • 모든 엔티티, 관계, 인덱스 (신규와 동일)
   • [레거시 추가] 마이그레이션 대상 태그: 각 엔티티에 UNCHANGED/MODIFY/NEW/DEPRECATE 태그
   • [레거시 추가] 마이그레이션 스크립트 윤곽, 롤백 계획

4. 05-component-breakdown.md — 현행 컴포넌트

   • 모든 모듈, 인터페이스, 의존성 (신규와 동일)
   • [레거시 추가] 변경 대상 태그: 각 컴포넌트에 UNCHANGED/MODIFY/NEW/DELETE 태그
   • [레거시 추가] 의존성 영향 분석

5. 06-spec-checklist.md — 신규 프로젝트와 동일

---

동작 (멀티 도메인 모드)

--shared (프로젝트 수준 아키텍처)

프로젝트 수준 공유 아키텍처를 생성합니다. 멀티 도메인에서 항상 먼저 실행해야 합니다.

sdd-spec-writer 에이전트를 사용하여 docs/specs/02-architecture.md를 생성합니다:

• templates/specs/project-architecture-multi.md.tmpl 템플릿 사용
• 프로젝트 개요 및 도메인 경계 다이어그램
• 도메인 목록 테이블 (ID, 이름, 설명, 의존성)
• 기술 스택 (계층별 기술과 선정 근거)
• 공유 인프라 (인증/인가, 공통 미들웨어, DB 전략)
• 도메인 간 통신 방식 (동기 API / 비동기 이벤트)
• 횡단 관심사 (에러 처리, 로깅, 설정)
• 배포 아키텍처

--domain=<id> (도메인별 스펙)

사전 조건: docs/specs/domains/<domain-id>/01-requirements.md가 존재해야 합니다.

sdd-spec-writer 에이전트를 사용하여 도메인 디렉토리에 스펙을 생성합니다:

1. domains/<id>/02-architecture.md — 도메인 아키텍처

   • templates/specs/domain-architecture.md.tmpl 템플릿 사용
   • 프로젝트 수준 아키텍처 (docs/specs/02-architecture.md) 참조
   • 도메인 내부 모듈 구조
   • 다른 도메인과의 연동 인터페이스

2. domains/<id>/03-api-spec.md — 도메인 API 스펙

   • 해당 도메인이 소유한 엔드포인트만 포함
   • 다른 도메인의 API를 호출하는 경우: (ref: <other-domain>/03-api-spec.md#<endpoint>) 형태로 참조만 기록

3. domains/<id>/04-data-model.md — 도메인 데이터 모델

   • 해당 도메인이 소유한 엔티티만 포함
   • 다른 도메인의 엔티티를 참조하는 경우: (ref: <other-domain>/04-data-model.md#<entity>) 형태로 참조만 기록

4. domains/<id>/05-component-breakdown.md — 도메인 컴포넌트

   • 해당 도메인 내부 모듈만 포함

5. domains/<id>/06-spec-checklist.md — 도메인 체크리스트

   • templates/checklists/domain-checklist.md.tmpl 템플릿 사용
   • 항목 ID에 도메인 접두사: <PREFIX>-<CATEGORY>-<NNN>
   • 도메인 접두사 규칙: 도메인 ID를 대문자 축약형으로 변환
     • device-mgmt → DEV
     • subscription → SUB
     • rate-plan → RATE
     • rate-benefit → BENEFIT
     • 그 외: 도메인 ID의 첫 번째 단어를 대문자로 (예: user-management → USER)
   • 예: DEV-API-001, SUB-DM-003, RATE-TEST-001
   • 각 항목은 도메인 스펙 섹션을 참조: (domains/<id>/03-api-spec.md#section)

--all (전체 도메인 일괄 생성)

1. 프로젝트 수준 아키텍처를 먼저 생성합니다 (--shared 동작과 동일).

2. 도메인 의존성 순서에 따라 각 도메인의 스펙을 생성합니다:

   • 의존성이 없는 도메인 먼저 (예: device-mgmt, rate-plan)
   • 의존하는 도메인 나중에 (예: subscription, rate-benefit)
   • 이유: 후속 도메인이 선행 도메인의 인터페이스를 참조할 수 있음

3. 크로스 도메인 통합 문서를 생성합니다:

   a. docs/specs/cross-domain/dependency-map.md:

   • templates/cross-domain/dependency-map.md.tmpl 템플릿 사용
   • 도메인 의존성 그래프
   • 공유 엔티티 목록

   b. docs/specs/cross-domain/integration-points.md:

   • templates/cross-domain/integration-points.md.tmpl 템플릿 사용
   • 도메인 간 통합 포인트 (FK 참조, API 호출, 이벤트, 공유 엔티티)

   c. docs/specs/cross-domain/integration-checklist.md:

   • templates/cross-domain/integration-checklist.md.tmpl 템플릿 사용
   • 크로스 도메인 통합 검증 항목 (INT-NNN 형식)

4. 프로젝트 통합 체크리스트를 자동 집계합니다:

   • docs/specs/06-spec-checklist.md를 생성합니다
   • templates/checklists/project-checklist-multi.md.tmpl 템플릿 사용
   • 모든 도메인의 06-spec-checklist.md 항목을 합칩니다
   • cross-domain/integration-checklist.md 항목을 추가합니다
   • 도메인별 섹션으로 구분합니다
   • 이 파일은 자동 생성됨 — 직접 편집 금지 표시

도메인 미지정 시 (멀티 도메인 모드)

사용자에게 도메인 선택 목록을 표시합니다:

도메인을 선택하세요:
  1. device-mgmt (단말관리) [상태: 요구사항 수집 완료]
  2. subscription (구독 서비스) [상태: 요구사항 수집 완료]
  3. (shared) 프로젝트 수준 아키텍처만 생성
  4. (all) 모든 도메인 일괄 생성

---

다이어그램 자동 생성

스펙 생성 완료 후, 스펙 검토 요약을 출력하기 전에 다이어그램 PNG를 자동 생성합니다.

sdd-spec-writer 에이전트가 스펙 작성 시 Mermaid 코드 블록을 직접 포함하며, 여기서 해당 블록을 추출하여 mmdc로 PNG를 렌더링합니다.

렌더링 파이프라인

1. 스펙 파일에서 ```mermaid ``` 코드 블록을 찾습니다.
2. 블록 직후의 ![](diagrams/XX-name.png) 참조에서 출력 파일명을 결정합니다.
3. Mermaid 코드를 임시 .mmd 파일에 저장합니다.
4. mmdc로 렌더링합니다:

   npx mmdc -i /tmp/diagram.mmd -o <출력경로>/XX-name.png \
     -b white -s 2 -c {플러그인}/scripts/mermaid-config.json
   

5. 렌더링 실패 시 경고(⚠)를 표시하고 계속 진행합니다 (graceful degradation).

claude-mermaid MCP 활용 (선택): 다이어그램을 미세조정하고 싶으면 claude-mermaid MCP로 브라우저 프리뷰를 확인한 후, 스펙의 Mermaid 코드 블록을 수정하고 다시 렌더링합니다.

단일 도메인

1. docs/specs/diagrams/ 디렉토리를 생성합니다 (없으면).
2. 각 스펙 파일에서 Mermaid 블록을 추출하여 렌더링합니다:

입력 파일	Mermaid 유형	출력 PNG
docs/specs/02-architecture.md	graph TB	docs/specs/diagrams/02-module-dependency.png
docs/specs/04-data-model.md	erDiagram	docs/specs/diagrams/04-er-diagram.png
docs/specs/05-component-breakdown.md	sequenceDiagram	docs/specs/diagrams/05-component-interaction.png

3. 실패 시 경고만 표시하고 계속 진행합니다:

   ⚠ 다이어그램 생성 실패: 02-module-dependency.png (mmdc 미설치)
   

멀티 도메인

1. 프로젝트 수준: docs/specs/diagrams/ 디렉토리에 생성

입력 파일	Mermaid 유형	출력 PNG
docs/specs/02-architecture.md	graph TB	docs/specs/diagrams/02-domain-boundary.png

2. 도메인별: docs/specs/domains/<id>/diagrams/ 디렉토리에 생성

입력 파일	Mermaid 유형	출력 PNG
domains/<id>/02-architecture.md	graph TB	domains/<id>/diagrams/02-domain-dependency.png
domains/<id>/04-data-model.md	erDiagram	domains/<id>/diagrams/04-er-diagram.png
domains/<id>/05-component-breakdown.md	sequenceDiagram	domains/<id>/diagrams/05-component-interaction.png

3. 크로스 도메인: docs/specs/cross-domain/diagrams/ 디렉토리에 생성

입력 파일	Mermaid 유형	출력 PNG
cross-domain/dependency-map.md	graph LR	cross-domain/diagrams/cross-domain-dependency.png

요약 출력

다이어그램 생성 결과를 스펙 검토 요약에 포함합니다:

다이어그램:
  02-module-dependency.png     ✓ 생성 (mmdc)
  04-er-diagram.png            ✓ 생성 (mmdc)
  05-component-interaction.png ⚠ 실패 (mmdc 미설치)

---

프로젝트 규칙 정합성 검증

docs/specs/sdd-config.yaml의 rules.enabled가 true이고 rules.validation.on_spec이 true이면, 스펙 생성 완료 후 프로젝트 규칙과의 정합성을 자동 검증합니다.

검증 대상

규칙 카테고리	검증 대상 스펙	검증 내용
rules/api-design.md	03-api-spec.md	URL 패턴, 응답 형식, 에러 코드 체계가 규칙과 일치하는지
rules/data-model.md	04-data-model.md	엔티티 ID 전략, 공통 필드, FK 정책이 규칙과 일치하는지
rules/architecture.md	02-architecture.md	모듈 구조, 의존성 방향이 규칙과 일치하는지
rules/security.md	03-api-spec.md, 04-data-model.md	인증/인가, 감사 필드 요구사항이 스펙에 반영되었는지
rules/error-handling.md	03-api-spec.md, 05-component-breakdown.md	에러 처리 전략이 스펙에 반영되었는지

검증 결과

프로젝트 규칙 정합성 검증:
  api-design ↔ 03-api-spec.md:       ✓ 일치
  data-model ↔ 04-data-model.md:     ✓ 일치
  architecture ↔ 02-architecture.md: ✓ 일치
  security ↔ 03/04-spec.md:          ⚠ RULE-SEC-010 감사 필드 누락 (advisory)
  error-handling ↔ 03/05-spec.md:    ✓ 일치

불일치 처리

• strict 모드: 불일치 항목을 수정한 후 다음 단계로 진행
• advisory 모드: 불일치를 경고로 보고하고 진행

---

스펙 검토

생성 후 요약을 표시합니다:

단일 도메인:

기술 명세서가 생성되었습니다:
  - 02-architecture.md
  - 03-api-spec.md
  - 04-data-model.md
  - 05-component-breakdown.md
  - 06-spec-checklist.md (M개 카테고리에 N개 항목)

진행하기 전에 스펙을 검토하고 필요한 편집을 수행하세요.
다음 단계: /claude-sdd:sdd-plan — 태스크 분해 및 팀 멤버 배정

멀티 도메인:

기술 명세서가 생성되었습니다:

프로젝트 수준:
  - 02-architecture.md (멀티 도메인 아키텍처)
  - 06-spec-checklist.md (통합 체크리스트: N개 항목)

도메인별:
  - domains/device-mgmt/: 02~06 (19개 항목)
  - domains/subscription/: 02~06 (24개 항목)
  - domains/rate-plan/: 02~06 (15개 항목)
  - domains/rate-benefit/: 02~06 (18개 항목)

크로스 도메인:
  - cross-domain/dependency-map.md
  - cross-domain/integration-points.md
  - cross-domain/integration-checklist.md (8개 항목)

전체 체크리스트: 84개 항목 (4개 도메인 + 크로스 도메인)

진행하기 전에 스펙을 검토하고 필요한 편집을 수행하세요.
다음 단계: /claude-sdd:sdd-plan [--domain=<id> | --all] — 태스크 분해

출력

• 단일 도메인: docs/specs/02-*.md부터 docs/specs/06-*.md
• 멀티 도메인: docs/specs/02-architecture.md + docs/specs/domains/<id>/02-*.md부터 06-*.md + docs/specs/cross-domain/*.md + docs/specs/06-spec-checklist.md (통합)

의존성

• docs/specs/01-requirements.md 또는 docs/specs/domains/<id>/01-requirements.md (/claude-sdd:sdd-intake에서 생성)
• docs/specs/sdd-config.yaml (/claude-sdd:sdd-init에서 생성)
• docs/specs/00-project-context.md (선택 — /claude-sdd:sdd-godmode에서 생성, 집요한 설계 모드용)