Spec Workflow MCP

# 워크플로우 프로세스 가이드 이 가이드는 Spec Workflow MCP 사용을 위한 완전한 스펙 기반 개발 워크플로우와 모범 사례를 설명합니다. ## 개요 스펙 기반 워크플로우는 구조화된 접근 방식을 따릅니다: ``` 스티어링 → 스펙 → 구현 → 검증 ``` 각 단계는 이전 단계를 기반으로 하여 체계적이고 잘 문서화된 개발을 보장합니다. ## 1단계: 스티어링 문서를 사용한 프로젝트 설정 ### 스티어링 문서가 필요한 이유? 스티어링 문서는 프로젝트를 정렬되고 일관성 있게 유지하는 높은 수준의 지침을 제공합니다. 모든 개발 결정에 대한 북극성 역할을 합니다. ### 스티어링 문서 생성 ``` "내 프로젝트를 위한 스티어링 문서 생성" ``` 이는 세 가지 주요 문서를 생성합니다: #### 1. 제품 스티어링 (`steering/product.md`) - 제품 비전 및 미션 - 대상 사용자 및 페르소나 - 핵심 기능 및 우선순위 - 성공 메트릭 및 KPI - 비목표 및 제약 #### 2. 기술 스티어링 (`steering/tech.md`) - 아키텍처 결정 - 기술 스택 선택 - 성능 요구사항 - 보안 고려사항 - 확장성 접근 방식 #### 3. 구조 스티어링 (`steering/structure.md`) - 프로젝트 구성 - 파일 및 폴더 규칙 - 명명 표준 - 모듈 경계 - 문서 구조 ### 스티어링 모범 사례 1. **일찍 생성** - 스펙 전에 스티어링 설정 2. **업데이트 유지** - 프로젝트 발전에 따라 수정 3. **자주 참조** - 의사 결정에 사용 4. **널리 공유** - 팀 정렬 보장 ## 2단계: 스펙 생성 ### 세 가지 문서 시스템 각 스펙은 세 가지 순차적 문서로 구성됩니다: ``` 요구사항 → 설계 → 작업 ``` ### 요구사항 문서 **목적**: 무엇을 빌드할지 정의 **내용**: - 기능 개요 - 사용자 스토리 - 기능적 요구사항 - 비기능적 요구사항 - 수락 기준 - 제약 및 가정 **예제 생성**: ``` "다음을 지원하는 사용자 알림 시스템에 대한 요구사항 생성: - 이메일 알림 - 인앱 알림 - 푸시 알림 - 사용자 기본 설정 - 알림 기록" ``` ### 설계 문서 **목적**: 어떻게 빌드할지 정의 **내용**: - 기술 아키텍처 - 구성 요소 설계 - 데이터 모델 - API 사양 - 통합 지점 - 구현 접근 방식 **자동 생성**: 요구사항 승인 후 생성 ### 작업 문서 **목적**: 빌드 단계 정의 **내용**: - 계층적 작업 분류 - 종속성 - 노력 추정 - 구현 순서 - 테스팅 요구사항 **구조 예제**: ``` 1.0 데이터베이스 설정 1.1 알림 테이블 생성 1.2 인덱스 설정 1.3 마이그레이션 스크립트 생성 2.0 백엔드 구현 2.1 알림 서비스 생성 2.1.1 이메일 핸들러 2.1.2 푸시 핸들러 2.2 API 엔드포인트 생성 2.3 인증 추가 3.0 프론트엔드 구현 3.1 알림 구성 요소 생성 3.2 API와 통합 3.3 기본 설정 UI 추가 ``` ## 3단계: 검토 및 승인 ### 승인 워크플로우 1. **문서 생성** - AI가 문서 생성 2. **검토 요청** - 자동으로 승인 요청 3. **사용자 검토** - 대시보드/확장 프로그램에서 검토 4. **결정** - 승인, 변경 요청 또는 거부 5. **수정** (필요한 경우) - AI가 피드백을 기반으로 업데이트 6. **최종 승인** - 구현을 위해 문서 잠금 ### 승인 결정하기 #### 승인해야 할 때 - 요구사항이 완전하고 명확함 - 설계가 명시된 문제를 해결함 - 작업이 논리적이고 포괄적임 - 주요 우려사항이나 공백이 없음 #### 변경을 요청해야 할 때 - 중요한 세부사항 누락 - 불분명한 사양 - 더 나은 접근 방식 사용 가능 - 표준에 맞춰야 함 #### 거부해야 할 때 - 근본적인 오해 - 완전히 잘못된 접근 방식 - 완전한 재고가 필요함 ### 효과적인 피드백 제공 좋은 피드백: ``` "인증 흐름은 세션 대신 JWT 토큰을 사용해야 합니다. API 엔드포인트에 속도 제한 추가. 네트워크 실패에 대한 오류 처리 포함." ``` 나쁜 피드백: ``` "이것은 옳지 않아 보입니다. 수정하세요." ``` ## 4단계: 구현 ### 작업 실행 전략 #### 순차적 구현 종속 작업에 가장 적합: ``` "user-auth 스펙에서 작업 1.1 구현" "이제 작업 1.2 구현" "작업 1.3으로 계속" ``` #### 병렬 구현 독립적인 작업용: ``` "백엔드를 작업하는 동안 대시보드 스펙의 모든 UI 작업 구현" ``` #### 섹션 기반 구현 논리적 그룹화용: ``` "payment 스펙의 모든 데이터베이스 작업 구현" ``` ### 진행 추적 다음을 통해 구현 모니터링: - 대시보드 작업 뷰 - 진행률 표시줄 - 상태 표시기 - 완료 비율 ### 차단 요소 처리 차단되었을 때: 1. 차단 요소 문서화 2. 해결을 위한 하위 작업 생성 3. 가능한 경우 병렬 작업으로 이동 4. 작업 상태를 "차단됨"으로 업데이트 ## 5단계: 검증 ### 테스팅 전략 구현 후: 1. **단위 테스팅** ``` "알림 서비스를 위한 단위 테스트 생성" ``` 2. **통합 테스팅** ``` "API 엔드포인트를 위한 통합 테스트 생성" ``` 3. **종단간 테스팅** ``` "완전한 알림 흐름을 위한 E2E 테스트 생성" ``` ### 문서 업데이트 문서를 최신 상태로 유지: ``` "새 엔드포인트를 위한 API 문서 업데이트" "README에 사용 예제 추가" ``` ## 파일 구조 및 구성 ### 표준 프로젝트 구조 ``` your-project/ ├── .spec-workflow/ │ ├── steering/ │ │ ├── product.md │ │ ├── tech.md │ │ └── structure.md │ ├── specs/ │ │ ├── user-auth/ │ │ │ ├── requirements.md │ │ │ ├── design.md │ │ │ └── tasks.md │ │ └── payment-gateway/ │ │ ├── requirements.md │ │ ├── design.md │ │ └── tasks.md │ └── approval/ │ └── [승인 추적 파일] ├── src/ │ └── [구현] └── tests/ └── [테스트] ``` ### 명명 규칙 **스펙 이름**: - kebab-case 사용: `user-authentication` - 설명적으로: `payment-processing` (단순히 `payments` 아님) - 버전 회피: `user-profile` (`user-profile-v2` 아님) **문서 이름**: - 항상: `requirements.md`, `design.md`, `tasks.md` - 모든 스펙에서 일관성 유지 ## 고급 워크플로우 ### 기능 반복 발전하는 기능용: 1. 초기 스펙 생성 2. MVP 구현 3. 개선 스펙 생성 4. 원본 스펙 참조 5. 기존 작업 기반 구축 예제: ``` "다음을 추가하는 user-auth에 대한 개선 스펙 생성: - 소셜 로그인 (Google, Facebook) - 생체 인증 - 세션 관리 개선" ``` ### 리팩토링 워크플로우 1. **현재 상태 문서화** ``` "현재 인증 시스템을 문서화하는 스펙 생성" ``` 2. **개선 설계** ``` "인증 성능을 개선하기 위한 리팩토링 설계" ``` 3. **마이그레이션 계획** ``` "리팩토링을 위한 마이그레이션 작업 생성" ``` 4. **점진적으로 구현** ``` "역호환성을 유지하며 리팩토링 작업 구현" ``` ### 버그 해결 워크플로우 1. **버그 보고** ``` "로그인 타임아웃 문제에 대한 버그 보고서 생성" ``` 2. **조사** ``` "버그 #45의 근본 원인 조사" ``` 3. **솔루션 설계** ``` "타임아웃 문제에 대한 수정 설계" ``` 4. **구현** ``` "버그 수정 구현" ``` 5. **검증** ``` "버그 #45를 위한 회귀 테스트 생성" ``` ## 모범 사례 ### 1. 스펙 세분성 유지 **좋음**: 기능당 하나의 스펙 - `user-authentication` - `payment-processing` - `notification-system` **나쁨**: 지나치게 광범위한 스펙 - `backend-system` - `all-features` ### 2. 순차적 문서 생성 항상 순서를 따르세요: 1. 요구사항 (무엇) 2. 설계 (어떻게) 3. 작업 (단계) 절대 건너뛰지 마세요. ### 3. 구현 전 완전한 승인 - ✅ 요구사항 승인 → 설계 생성 - ✅ 설계 승인 → 작업 생성 - ✅ 작업 검토 → 구현 시작 - ❌ 승인 건너뛰기 → 구현 문제 ### 4. 스펙을 최신 상태로 유지 요구사항이 변경되면: ``` "SSO 지원을 포함하도록 user-auth의 요구사항 업데이트" ``` ### 5. 일관된 용어 사용 다음 전반에 걸쳐 일관성 유지: - 스펙 이름 - 구성 요소 이름 - API 용어 - 데이터베이스 명명 ### 6. 완료된 스펙 아카이브 작업 공간을 깔끔하게 유지: ``` "완료된 user-auth 스펙 아카이브" ``` ## 일반적인 패턴 ### MVP에서 전체 기능으로 1. MVP 스펙으로 시작 2. 핵심 기능 구현 3. 개선 스펙 생성 4. 점진적으로 구축 5. 역호환성 유지 ### 마이크로서비스 개발 1. 서비스 스티어링 문서 생성 2. 서비스 경계 정의 3. 서비스당 스펙 생성 4. 통합 지점 정의 5. 서비스 독립적으로 구현 ### API 우선 개발 1. API 스펙 먼저 생성 2. 계약 설계 3. 문서 생성 4. 엔드포인트 구현 5. 클라이언트 SDK 생성 ## 워크플로우 문제 해결 ### 스펙이 너무 큼 **해결책**: 더 작은 스펙으로 분할 ``` "전자상거래 스펙을 다음으로 분할: - product-catalog - shopping-cart - checkout-process - order-management" ``` ### 불분명한 요구사항 **해결책**: 명확화 요청 ``` "요구사항에 다음에 대한 더 많은 세부사항 필요: - 사용자 역할 및 권한 - 오류 처리 시나리오 - 성능 요구사항" ``` ### 설계가 요구사항과 일치하지 않음 **해결책**: 수정 요청 ``` "설계가 다중 테넌시 요구사항을 다루지 않습니다. 테넌트 격리를 포함하도록 수정하세요." ``` ## 개발 프로세스와의 통합 ### Git 워크플로우 1. 스펙당 기능 브랜치 생성 2. 각 작업 완료 후 커밋 3. 커밋 메시지에 스펙 참조 4. 스펙 완료 시 PR ### CI/CD 통합 - 완료된 작업에 대한 테스트 실행 - 요구사항에 대해 검증 - 완료된 기능 배포 - 성공 메트릭에 대해 모니터링 ### 팀 협업 - 대시보드 URL 공유 - 팀 구성원에게 스펙 할당 - 서로의 스펙 검토 - 승인을 통해 조정 ## 관련 문서 - [사용자 가이드](USER-GUIDE.md) - 일반 사용 지침 - [프롬프팅 가이드](PROMPTING-GUIDE.md) - 예제 프롬프트 및 패턴 - [도구 참조](TOOLS-REFERENCE.md) - 완전한 도구 문서 - [인터페이스 가이드](INTERFACES.md) - 대시보드 및 확장 프로그램 세부사항