Spec Workflow MCP

# 사용자 가이드 AI 지원 소프트웨어 개발을 위한 Spec Workflow MCP 사용에 대한 포괄적인 가이드입니다. ## 시작하기 ### Spec Workflow MCP란? Spec Workflow MCP는 AI 어시스턴트에 구조화된 스펙 기반 개발 도구를 제공하는 Model Context Protocol 서버입니다. 다음을 도와줍니다: - 코딩 전에 상세한 사양 생성 - 구현 진행 상황 추적 - 승인 및 수정 관리 - 프로젝트 문서 유지 ### 기본 워크플로우 1. **스펙 생성** - 빌드할 항목 정의 2. **검토 및 승인** - 사양이 요구사항을 충족하는지 확인 3. **작업 구현** - 구현 계획 실행 4. **진행 상황 추적** - 완료 상태 모니터링 ## 스펙 생성 ### 간단한 스펙 생성 AI 어시스턴트에게 스펙 생성 요청: ``` "사용자 인증을 위한 스펙 생성" ``` AI가 자동으로: 1. 요구사항 문서 생성 2. 기술적 접근 방식 설계 3. 구현을 작업으로 분류 ### 상세한 스펙 생성 더 나은 사양을 위해 더 많은 컨텍스트 제공: ``` "다음 기능이 포함된 payment-gateway라는 스펙 생성: - 신용 카드 처리 - PayPal 통합 - 구독 관리 - 결제 이벤트를 위한 웹훅 처리" ``` ### 기존 문서에서 기존 PRD 또는 설계 문서 사용: ``` "@product-requirements.md에서 스펙 생성" ``` ## 스펙 관리 ### 모든 스펙 나열 ``` "내 모든 스펙 나열" ``` 반환: - 스펙 이름 - 현재 상태 - 진행 비율 - 문서 상태 ### 스펙 상태 확인 ``` "user-auth 스펙의 상태 표시" ``` 제공: - 요구사항 승인 상태 - 설계 승인 상태 - 작업 완료 진행 상황 - 상세한 작업 분류 ### 스펙 문서 보기 대시보드 또는 VSCode 확장 프로그램을 사용하여: - 요구사항 문서 읽기 - 설계 문서 검토 - 작업 목록 탐색 - 구현 진행 상황 추적 ## 작업 작업 ### 작업 구조 작업은 계층적으로 구성됩니다: - **1.0** - 주요 섹션 - **1.1** - 하위 작업 - **1.2** - 하위 작업 - **1.2.1** - 상세 단계 ### 작업 구현 #### 방법 1: 직접 구현 ``` "user-auth 스펙에서 작업 1.2 구현" ``` #### 방법 2: 대시보드에서 복사 1. 대시보드 열기 2. 스펙으로 이동 3. "작업" 탭 클릭 4. 작업 옆의 "프롬프트 복사" 버튼 클릭 5. AI 대화에 붙여넣기 #### 방법 3: 일괄 구현 ``` "user-auth 스펙의 모든 데이터베이스 설정 작업 구현" ``` ### 작업 상태 작업에는 세 가지 상태가 있습니다: - ⏳ **대기 중** - 시작되지 않음 - 🔄 **진행 중** - 현재 작업 중 - ✅ **완료됨** - 완료됨 ## 승인 워크플로우 ### 승인 요청 문서가 검토 준비가 되면: 1. AI가 자동으로 승인 요청 2. 대시보드에 알림 표시 3. 문서 검토 4. 피드백 제공 또는 승인 ### 승인 작업 - **승인** - 문서를 있는 그대로 수락 - **변경 요청** - 수정을 위한 피드백 제공 - **거부** - 새 요구사항으로 처음부터 시작 ### 수정 프로세스 1. 구체적인 피드백 제공 2. AI가 문서 수정 3. 업데이트된 버전 검토 4. 승인 또는 추가 변경 요청 ## 버그 워크플로우 ### 버그 보고 ``` "SSO 사용 시 로그인 실패에 대한 버그 보고서 생성" ``` 생성: - 버그 설명 - 재현 단계 - 예상 대 실제 동작 - 우선순위 및 심각도 ### 버그 해결 ``` "user-auth 스펙의 버그 #123에 대한 수정 생성" ``` 생성: - 근본 원인 분석 - 수정 구현 계획 - 테스팅 요구사항 - 배포 단계 ## 템플릿 시스템 ### 템플릿 사용 Spec Workflow에는 다음 템플릿이 포함됩니다: - 요구사항 문서 - 설계 문서 - 작업 목록 - 버그 보고서 - 스티어링 문서 ### 사용자 지정 템플릿 `.spec-workflow/templates/`에 자체 템플릿 생성: ```markdown # 사용자 지정 기능 템플릿 ## 개요 [기능 설명] ## 사용자 스토리 [사용자 스토리] ## 기술 요구사항 [기술 세부사항] ``` ## 고급 기능 ### 스티어링 문서 높은 수준의 프로젝트 가이드 생성: ``` "내 전자상거래 프로젝트를 위한 스티어링 문서 생성" ``` 생성: - **제품 스티어링** - 비전 및 목표 - **기술 스티어링** - 아키텍처 결정 - **구조 스티어링** - 프로젝트 구성 ### 아카이브 시스템 완료된 스펙 관리: - 완료된 스펙을 아카이브로 이동 - 활성 작업 공간을 깔끔하게 유지 - 언제든지 아카이브된 스펙 액세스 - 필요할 때 스펙 복원 ### 다국어 지원 인터페이스 언어 변경: 1. **대시보드**: 설정 → 언어 2. **VSCode 확장 프로그램**: 확장 프로그램 설정 → 언어 3. **구성 파일**: `lang = "ja"` (또는 다른 언어 코드) ## 모범 사례 ### 1. 스티어링 문서로 시작 스펙 생성 전에: ``` "프로젝트를 안내할 스티어링 문서 생성" ``` ### 2. 요구사항에서 구체적으로 좋음: ``` "다음을 포함하는 사용자 인증을 위한 스펙 생성: - 이메일/비밀번호 로그인 - OAuth2 (Google, GitHub) - 2FA 지원 - 비밀번호 재설정 흐름" ``` 이상적이지 않음: ``` "로그인 스펙 생성" ``` ### 3. 구현 전 검토 항상 다음을 검토하고 승인: 1. 요구사항 문서 2. 설계 문서 3. 작업 분류 ### 4. 점진적으로 구현 - 순서대로 작업 완료 - 각 주요 섹션 후 테스트 - 작업 상태 정기적으로 업데이트 ### 5. 대시보드 사용 대시보드 제공: - 시각적 진행 추적 - 쉬운 문서 탐색 - 빠른 승인 작업 - 실시간 업데이트 ## 일반적인 워크플로우 ### 기능 개발 1. 스펙 생성: `"shopping-cart 기능을 위한 스펙 생성"` 2. 대시보드에서 요구사항 검토 3. 승인 또는 변경 요청 4. 설계 문서 검토 5. 설계 승인 6. 작업 순차적으로 구현 7. 대시보드에서 진행 상황 추적 ### 버그 수정 1. 버그 보고: `"체크아웃 오류에 대한 버그 보고서 생성"` 2. 분석: `"버그 #45의 근본 원인 분석"` 3. 수정 계획: `"버그 #45에 대한 수정 계획 생성"` 4. 구현: `"수정 구현"` 5. 검증: `"버그 #45 수정을 위한 테스트 계획 생성"` ### 리팩토링 1. 스펙 생성: `"데이터베이스 최적화를 위한 스펙 생성"` 2. 현재 상태 문서화 3. 개선 설계 4. 마이그레이션 단계 계획 5. 점진적으로 구현 6. 각 단계 검증 ## 팁 및 요령 ### 효율적인 작업 관리 - 관련 항목에 작업 그룹화 사용 - 정확성을 위해 대시보드에서 프롬프트 복사 - 완료 후 즉시 작업을 완료로 표시 ### 문서 관리 - 요구사항을 간결하지만 완전하게 유지 - 수락 기준 포함 - 설계에 기술적 제약 추가 - 필요할 때 외부 문서 참조 ### 협업 - 피드백을 위해 승인 댓글 사용 - 팀과 대시보드 URL 공유 - 외부 검토를 위해 문서 내보내기 - 수정 기록을 통해 변경 사항 추적 ## AI 어시스턴트와의 통합 ### 컨텍스트 인식 AI 어시스턴트가 자동으로: - 프로젝트 구조 알기 - 스펙 관계 이해 - 구현 진행 상황 추적 - 일관성 유지 ### 자연어 명령 자연스럽게 말하기: - "어떤 스펙이 있나요?" - "남은 작업 표시" - "다음 작업 시작" - "더 나은 성능을 위해 설계 업데이트" ### 연속 워크플로우 AI가 세션 간 컨텍스트 유지: - 중단한 지점에서 재개 - 이전 결정 참조 - 기존 작업 기반 구축 - 프로젝트 일관성 유지 ## 관련 문서 - [워크플로우 프로세스](WORKFLOW.md) - 상세한 워크플로우 가이드 - [프롬프팅 가이드](PROMPTING-GUIDE.md) - 예제 프롬프트 - [인터페이스 가이드](INTERFACES.md) - 대시보드 및 확장 프로그램 세부사항 - [도구 참조](TOOLS-REFERENCE.md) - 완전한 도구 문서