GalRogozinski/스펙 기반 개발(SDD)

스펙 기반 개발(SDD) 스킬

GitHub의 Spec-Kit을 사용한 스펙 기반 개발 방법론을 안내합니다. 이 방법론은 전통적인 소프트웨어 개발을 뒤집어 스펙을 실행 가능하게 만들고 직접 작동하는 구현을 생성합니다.

핵심 철학

스펙 기반 개발은 다음을 강조합니다:

• 의도 중심 개발: '어떻게'보다 '무엇을' 먼저 정의
• 풍부한 스펙 생성: 가드레일과 조직 원칙 사용
• 다단계 정제: 단일 코드 생성이 아닌 반복적 개선
• AI 네이티브: 고급 AI 기능에 대한 중대한 의존성

기억하세요: 이것은 AI 네이티브 개발입니다. 스펙은 단순한 문서가 아니라 실행 가능한 아티팩트로, 직접 구현을 주도합니다. AI 에이전트는 이를 사용하여 스펙에 정의된 의도와 일치하는 작동 코드를 생성합니다.

승인 기준: Gherkin 형식 (필수)

모든 spec.md(또는 specify.md)의 모든 사용자 스토리에는 prose 설명 외에도 Gherkin 스타일의 승인 기준이 포함되어야 합니다. 이는 그린필드와 브라운필드 모두, 모든 사용자 스토리에 적용되며, /speckit.specify로 생성되었든 CLI 생성 템플릿을 사용하지 않는 저장소의 수동 작성이든 관계없습니다. Prose는 스토리가 무엇에 관한 것인지 설명합니다; Gherkin 시나리오는 정확히 어떻게 검증할 것인지 알려줍니다 — 이것이 스펙을 서술적이 아닌 실행 가능하게 만듭니다.

형식 — 각 사용자 스토리 바로 아래에 펜스 처리된 gherkin 블록, 1~4개의 시나리오: 먼저 해피 패스, 그다음 해당 스토리에 중요한 엣지/네거티브 케이스 (스펙의 모든 엣지 케이스가 아니라 — 그런 것들은 스펙 자체의 '엣지 케이스' 섹션에 속합니다; 이 스토리 특정적인 것만).

Scenario: <짧고 구체적인 이름 — "해피 패스" 아님>
  Given <전제 조건 / 시작 상태>
  When <행위자가 취하는 단일 동작>
  Then <관찰 가능하고 테스트 가능한 결과>
  And <필요한 경우 추가 결과>

Scenario: <이 스토리의 엣지/네거티브 케이스>
  Given <전제 조건>
  When <동작>
  Then <결과 — 발생해서는 안 되는 일도 유효한 Then>

작성 규칙:

• 시나리오 당 When 하나. 여러 동작은 여러 시나리오를 의미합니다. 이렇게 하면 각 시나리오가 하나의 테스트에 매핑됩니다.
• Then은 관찰 가능해야 하며 내부적이지 않습니다: "사용자에게 확인 토스트가 표시됩니다"는 좋지만 "상태가 올바르게 업데이트됩니다"는 좋지 않습니다. 누군가 확인할 수 있는 방법을 말할 수 없다면, 준비되지 않은 것입니다.
• 스펙의 자체 용어를 재사용하세요. Given/When/Then 단계는 사용자 스토리 및 기능 요구사항과 동일한 명사(자산 이름, 거래 유형, 필드 이름)를 사용해야 합니다 — 의역하지 마세요.
• 기능 요구사항을 Gherkin으로 다시 말하지 마세요. 승인 기준은 스토리를 검증합니다; FR은 별도로 추적됩니다. 중복은 괜찮지만, 모든 FR을 시나리오로 복제하는 것은 아닙니다.
• 스토리에 시나리오가 여러 개인 경우 추적성을 위해 번호를 매깁니다: Scenario: AC-1 — ..., Scenario: AC-2 — ... (단일 시나리오 스토리는 선택 사항).

요약할 때 (10포인트 템플릿, "생성된 내용"), 사용자 스토리/성공 기준 개수와 함께 시나리오 개수를 보고합니다. 예: "5개의 사용자 스토리(11개의 Gherkin 시나리오), 8개의 성공 기준." 사용자 스토리에 승인 기준이 없는 경우 /speckit.plan으로 이동하기 전에 "🔍 검토해야 할 중요 항목" 아래에 표시합니다 — 승인 기준이 없는 스토리로 작성된 계획은 테스트를 과소 지정하는 경향이 있습니다.

행동 AC: LLM-인-더-루프 스토리 전용

Gherkin은 한 번의 실행으로 합격/불합격을 결정한다고 가정합니다. 이는 모델의 출력이 결과를 결정할 때 깨집니다: 비결정적 스토리의 한 번의 성공적인 실행은 거의 아무것도 증명하지 않습니다. 이러한 스토리의 경우 Gherkin 블록 아래에 행동 AC 블록을 추가합니다.

스토리의 관찰 가능한 결과가 모델의 출력에 의존하는 경우에만 생성하세요. 예: 프롬프트, 시스템 프롬프트, 미션, 스킬 파일 또는 도구 설명 변경; 모델이 동작을 선택하거나, 판단하거나 해결하거나, 사용자 대면 텍스트를 작성하는 경우; 모델 또는 해당 매개변수가 변경되는 경우. 결정적 코드, 저장된 데이터의 UI 렌더링, 배관, 또는 모델 호출이 있지만 그 출력이 단언되지 않는 스토리의 경우 생성하지 마세요. 확실하지 않은 경우 하나의 질문을 하세요; 추측으로 블록을 추가하지 마세요. LLM-인-더-루프 스토리가 없는 스펙에는 행동 AC가 전혀 없으며 빈 자리 표시자도 없습니다.

형식: 자격이 되는 각 스토리에 대해 하나의 블록, 해당 Gherkin 바로 뒤에.

**행동 AC** (LLM-인-더-루프: <모델이 결정하는 것>)
- **케이스:** <N>개의 케이스, `<케이스 세트 경로>`에 위치, 실제 실패 / 추적 / 대본에서 가져옴; 합성 입력은 간격을 메우는 경우에만, 합성 예상 출력은 절대 안 됨
- **실행:** 케이스 당 k = <k> (≈ 3 / 예상 실패율; 알 수 없는 경우 20–30)
- **합격 기준:** <메트릭> ≥ <임계값> over k, 기준선을 노이즈보다 더 많이 초과 (현재 버전과의 쌍별 비교)
- **채점기:** 코드 검사 | LLM 판사 (이진, 실패 모드 당 하나) | 사람; 판사는 또한 해당 검증을 명명합니다: 보류된 인간 레이블에 대해 TPR/TNR ≥ 0.9 (0.8 최소), 또는 "검증되지 않음"을 명시적으로 말함
- **명령어:** `<합격률, 비용 및 지연 시간을 출력하는 하나의 명령어>`

규칙:

• 진짜 모델 실행만 인정됩니다. 모의 실험, 키워드 시뮬레이션 또는 예측 점수는 결과가 아닙니다. 실행할 수 없는 경우(비용, 키), 스토리가 UNEVALUATED라고 말하세요. 숫자를 조작하지 마세요.
• 코드 채점기를 선호하세요. 코드가 확인할 수 없는 경우에만 판사를 사용하세요.
• Gherkin은 여전히 적용됩니다. Gherkin 시나리오는 결정적 쉘(작성된 아티팩트, 유지된 가드)을 다룹니다. 행동 AC는 모델의 행동을 다룹니다.
• plan.md는 평가를 전달합니다: 케이스 세트 위치, 실행 명령어, 실행당 비용, 실행 시기(PR당, 또는 비용이 많이 드는 경우 병합 전에만).

요약할 때 별도로 계산합니다. 예: "5개의 사용자 스토리(11개의 Gherkin 시나리오, 2개는 행동 AC 있음)". "검토해야 할 중요 항목" 아래에 해당 블록이 없는 LLM-인-더-루프 스토리와 검증되지 않음으로 표시된 판사를 플래그합니다.

빠른 결정 트리

신규 프로젝트(그린필드)인가요?

→ 전체 6단계 프로세스는 그린필드 워크플로우 를 참조하세요

기존 코드베이스(브라운필드)인가요?

→ 역공학 및 통합 지침은 브라운필드 워크플로우 를 참조하세요

설치 도움이 필요하신가요?

→ 설정 및 문제 해결은 설치 가이드 를 참조하세요

설치 빠른 시작

권장(영구 설치):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

일회성 사용:

uvx --from git+https://github.com/github/spec-kit.git specify init <프로젝트_이름>

확인:

specify check

자세한 설치 옵션, 문제 해결 및 환경 변수는 설치 가이드를 참조하세요.

지원되는 AI 에이전트

다음과 함께 작동:

• ✅ Claude Code
• ✅ GitHub Copilot
• ✅ Gemini CLI
• ✅ Cursor
• ✅ Qwen Code
• ✅ opencode
• ✅ Windsurf
• ✅ Kilo Code
• ✅ Auggie CLI
• ✅ CodeBuddy CLI
• ✅ Roo Code
• ✅ Codex CLI
• ✅ Amp
• ⚠️ Amazon Q Developer CLI (슬래시 명령에 대한 사용자 지정 인수를 지원하지 않음)

아티팩트 요약 및 피드백 루프

중요 워크플로우: SDD 명령이 아티팩트를 생성하거나 수정한 후, 자동으로 이 피드백 루프를 따라 사용자의 참여를 유지하세요:

각 명령 완료 후

1. 아티팩트 변경 감지

   • 생성되거나 수정된 아티팩트 식별:
     • constitution.md (프로젝트 원칙)
     • spec.md (요구사항 명세)
     • plan.md (기술 구현 계획)
     • tasks.md (실행 가능한 작업 분류)
     • 브라운필드 워크플로우의 분석 보고서

2. 읽고 요약

   • 관련 아티팩트 읽기
   • 핵심 정보 추출:
     • constitution.md의 경우: 핵심 원칙, 코딩 표준, 제약 조건
     • spec.md의 경우: 주요 요구사항, 사용자 스토리 (해당 Gherkin 승인 기준 포함), 성공 기준
     • plan.md의 경우: 기술 스택 선택, 아키텍처 결정, 마일스톤
     • tasks.md의 경우: 작업 수, 주요 작업 범주, 종속성
     • 분석 보고서의 경우: 현재 패턴, 기술 부채, 통합 지점

3. 구조화된 요약 제시 (아래 10포인트 템플릿 사용)

   • 생성된 내용과 이유 표시
   • 근거와 함께 가장 중요한 결정 강조
   • 품질 지표 및 주의 사항 포함
   • 요약을 집중적이고 실행 가능하게 유지
   • 각 섹션에 명확한 제목 사용

4. 기능 상태 포함 (하이브리드 접근 방식)

   • 모든 요약에 간략한 상태 줄 포함
   • /speckit.status로 요청 시 상세 상태 제공
   • 아래 "기능 상태 추적" 섹션 참조

5. 피드백 옵션 제공

   • 옵션 A: "좋습니다, 다음 단계로 진행하세요"
   • 옵션 B: "[특정 섹션]을 수정하고 싶습니다"
   • 옵션 C: "다음 변경 사항으로 재생성: [사용자 입력]"
   • 옵션 D: "[특정 결정]이 내려진 이유를 설명하세요"

10포인트 요약 템플릿

SDD 명령 완료 후 이 구조화된 형식을 사용하세요:

## ✅ [명령 이름] 완료 - 방금 발생한 일

### 🎯 주요 결정 (상위 3개)
1. [결정] - **근거:** [이것이 선택된 이유]
2. [결정] - **근거:** [이것이 선택된 이유]
3. [결정] - **근거:** [이것이 선택된 이유]

### 📋 생성된 내용
- [아티팩트 1]: [콘텐츠에 대한 간략한 설명]
- [아티팩트 2]: [콘텐츠에 대한 간략한 설명]

### 🔍 검토해야 할 중요 항목 (상위 3개)
1. [확인해야 할 중요 항목 및 이유]
2. [확인해야 할 중요한 세부 사항 및 잠재적 영향]
3. [고려해야 할 엣지 케이스 및 설계에 미치는 영향]

### ⚠️ 주의 사항 (상위 2개)
- [잠재적 문제 또는 함정] - **방지 방법:** [지침]
- [일반적인 실수] - **방지 방법:** [지침]

### 🔄 다음에 가능한 것 (2가지 옵션)
- **옵션 1:** [다음 단계] - 다음 경우에 가장 적합: [조건]
- **옵션 2:** [대체 단계] - 다음 경우에 가장 적합: [조건]

📊 **기능 상태:** [현재 기능 이름] ([단계]) → 다음: [다음 기능]
   진행률: [●●●○○] [X]% | 완료: [완료된 기능 수] / [총 기능 수] | 종속성: [상태]

**옵션:** [A] 진행 [B] 수정 [C] 더 설명 [D] 전체 상태 보기

예시: /speckit.specify 후 강화된 요약

## ✅ Specify 완료 - 방금 발생한 일

### 🎯 주요 결정
1. **인증: JWT 토큰** - 근거: 상태 비저장 아키텍처, 수평적 확장 가능, 업계 표준
2. **비밀번호 요구사항: 복잡성 포함 12자 이상** - 근거: 보안(NIST 지침)과 사용성을 균형
3. **세션 시간 초과: 24시간** - 근거: 웹 앱 표준, 보안과 사용자 편의성의 균형

### 📋 생성된 내용
- `.speckit/features/user-auth/specify.md`: 5개의 사용자 스토리(12개의 Gherkin 승인 기준 시나리오), 8개의 성공 기준, 3개의 엣지 케이스를 포함한 완전한 요구사항

### 🔍 검토해야 할 중요 항목
1. **비밀번호 재설정 흐름** - 이메일 요구사항이 인프라(SMTP 서버, 템플릿)와 일치하는지 확인
2. **다중 요소 인증** - 현재 "향후 개선 사항"으로 표시됨; MVP에 필요할 수 있음
3. **속도 제한** - 15분당 5회 로그인 시도로 설정; 보안 정책에 맞는지 고려

### ⚠️ 주의 사항
- **이메일 서비스 종속성이 지정되지 않음** - 방지 방법: plan.md 종속성에 이메일 서비스 추가
- **사용자 데이터에 대한 GDPR 준수** - 방지 방법: 데이터 보존 및 사용자 삭제 요구사항 검토

### 🔄 다음에 가능한 것
- **옵션 1:** `/speckit.plan` 실행하여 기술 구현 설계 - 다음 경우에 가장 적합: 요구사항이 괜찮아 보임
- **옵션 2:** specify.md 수정 - 다음 경우에 가장 적합: 요구사항을 조정하거나 기능을 추가해야 함

📊 **기능 상태:** user-authentication (지정됨) → 다음: profile-management
   진행률: [●●○○○] 40% | 완료: 1 / 5 기능 | 종속성: database-setup ✅

**옵션:** [A] 계획 수립 진행 [B] 요구사항 수정 [C] JWT 선택 설명 [D] 전체 상태 보기

요약 생략 시기

다음 경우에만 요약 단계를 건너뜁니다:

• 사용자가 명시적으로 "요약 건너뛰기" 또는 "모든 단계 자동 실행" 요청
• 아티팩트 변경 없이 명령 재실행
• 명령 실패 또는 오류 발생 (대신 문제 해결)

이 워크플로우의 이점

• "블랙 박스" 느낌 제거: 생성된 내용과 이유에 대한 명확한 설명
• 조기 피드백 가능: 구현 전에 오해 포착
• 민첩성 유지: 긴 승인 프로세스가 아닌 구조화된 형식의 빠른 검토
• 신뢰 구축: 사용자는 AI의 추론과 결정 및 그 근거를 봄
• 컨텍스트 제공: 기능 상태는 사용자를 전체 프로젝트에서 방향을 잡아줌

기능 상태 추적

하이브리드 접근 방식

모든 SDD 명령 후에 요약에 간략한 기능 상태 줄을 포함합니다. /speckit.status로 요청 시 상세 상태를 제공합니다.

간략한 상태 줄 형식

모든 요약 끝에 다음을 포함합니다:

📊 **기능 상태:** [현재 기능 이름] ([단계]) → 다음: [다음 기능 이름]
   진행률: [●●●○○] [X]% | 완료: [완료된 기능 수] / [총 기능 수] | 종속성: [종속성] ✅/⏸️

단계 값:

• 지정 중 (20% 완료)
• 계획 중 (40% 완료)
• 작업 중 (60% 완료)
• 진행 중 (80% 완료)
• 완료 (100% 완료)

진행률 표시기:

• 완료된 단계에는 채워진 원(●) 사용
• 보류 중인 단계에는 빈 원(○) 사용
• 단계를 기준으로 백분율 계산

상세 상태 대시보드

사용자가 전체 상태를 요청하거나(옵션 D) /speckit.status를 실행하면 다음을 표시합니다:

📊 프로젝트 기능 상태 대시보드

🎯 현재 기능
├─ [기능 이름] ([단계] - [X]% 완료)
│  ├─ ✅ 요구사항 지정됨
│  ├─ 🔄 구현 계획 진행 중
│  ├─ ⏸️ 작업 시작 안 됨
│  └─ ⏸️ 구현 시작 안 됨
│  차단 항목: [없음 | 설명]
│  종속성: [기능 이름] ✅

✅ 완료된 기능 ([N])
├─ [기능 1] (100% 완료)
└─ [기능 2] (100% 완료)

📋 예정된 기능 ([N])
├─ [기능 3] (종속: [현재 기능])
└─ [기능 4] (종속: [기능 3])

⚠️ 차단된 기능

...

[번역을 위해 잘림]

(참고: 원본의 [truncated for translation] 마커를 존중하여 나머지 내용은 번역하지 않았습니다.)