Spec Workflow MCP

# 프롬프팅 가이드 AI 어시스턴트를 통해 Spec Workflow MCP와 상호작용하기 위한 예제와 모범 사례가 포함된 종합 가이드입니다. ## 빠른 참조 ### 필수 명령어 ``` "[기능]에 대한 spec 만들어줘" "내 모든 spec 목록 보여줘" "[spec-name]의 상태 보여줘" "[spec]의 작업 [번호] 구현해줘" "steering 문서 만들어줘" ``` ## 사양 작성하기 ### 기본 Spec 작성 #### 간단한 요청 ``` "사용자 인증에 대한 spec 만들어줘" ``` AI가 다음을 생성합니다: - 요구사항 문서 - 설계 문서 (승인 후) - 작업 분해 (설계 승인 후) #### 상세한 요청 ``` "payment-processing이라는 이름으로 spec 만들어줘: - Stripe를 통한 신용카드 결제 - PayPal 통합 - 환불 처리 - 결제 이벤트를 위한 Webhook 처리 - PCI 규정 준수 고려사항" ``` #### 기존 문서로부터 ``` "@product-requirements.md의 PRD로부터 spec 만들어줘" ``` ``` "@figma-export.md의 설계 문서를 기반으로 spec 만들어줘" ``` ### 고급 Spec 작성 #### 기술적 제약사항 포함 ``` "다음 조건을 만족하는 실시간 알림 spec 만들어줘: - 실시간 업데이트를 위해 WebSocket 사용 - 구형 브라우저를 위한 폴링 대체 방안 - 최대 10,000개의 동시 연결 처리 - 메시지 순서 유지 - 오프라인 큐 지원 포함" ``` #### 수락 기준 포함 ``` "다음 수락 기준을 가진 검색 기능 spec 만들어줘: - 200ms 이내 결과 표시 - 퍼지 매칭 지원 - 날짜, 카테고리, 작성자 필터 포함 - 관련성 점수 표시 - 오타 및 동의어 처리" ``` #### 마이크로서비스 사양 ``` "다음 조건의 재고 마이크로서비스 spec 만들어줘: - REST API 노출 - 스토리지로 PostgreSQL 사용 - Kafka로 이벤트 발행 - CQRS 패턴 구현 - 헬스 체크 엔드포인트 포함" ``` ## 사양 관리하기 ### 목록 및 상태 #### 개요 보기 ``` "내 모든 spec 목록 보여줘" "모든 spec과 진행 상황 보여줘" "어떤 spec이 승인 대기 중이야?" "현재 진행 중인 spec은 뭐야?" ``` #### 특정 상태 ``` "user-auth spec의 상태 보여줘" "payment-processing의 진행 상황은?" "notification spec에서 남은 작업 보여줘" "user-profile에서 완료된 작업은 뭐야?" ``` #### 필터링 ``` "50% 이상 완료된 spec 보여줘" "내 승인을 기다리는 spec 목록 보여줘" "아직 작업이 완료되지 않은 spec은?" "차단되거나 중단된 spec 보여줘" ``` ### 문서 관리 #### 문서 보기 ``` "user-auth의 요구사항 보여줘" "payments의 설계 문서 표시해줘" "알림 시스템의 작업은 뭐야?" "search spec의 모든 문서 보여줘" ``` #### 문서 업데이트 ``` "user-auth 요구사항을 2FA 포함하도록 업데이트해줘" "payment 설계를 Stripe Connect 사용하도록 수정해줘" "user-profile에 보안 테스트 작업 추가해줘" "피드백을 기반으로 요구사항 업데이트: [피드백]" ``` ## 구현 프롬프트 ### 개별 작업 #### 기본 구현 ``` "user-auth의 작업 1.2 구현해줘" "payment spec의 작업 2.1.3 완료해줘" "notifications의 다음 대기 중인 작업 처리해줘" ``` #### 컨텍스트 포함 ``` "TypeScript와 Express를 사용해서 user-auth의 작업 1.2 구현해줘" "Prisma를 사용해서 데이터베이스 마이그레이션 작업 완료해줘" "REST 규칙에 따라 API 엔드포인트 작업 구현해줘" ``` ### 배치 구현 #### 섹션별 ``` "user-auth의 모든 데이터베이스 작업 구현해줘" "dashboard spec의 모든 프론트엔드 작업 완료해줘" "payments의 모든 API 작업 처리해줘" ``` #### 우선순위별 ``` "모든 중요 작업을 먼저 구현해줘" "user-profile의 MVP 작업 완료해줘" "데모에 필요한 작업에 집중해줘" ``` #### 순차적 ``` "user-auth의 작업 1.1부터 1.5까지 구현해줘" "섹션 2의 모든 하위 작업 완료해줘" "설정 작업을 순서대로 처리해줘" ``` ### 구현 전략 #### 테스트 주도 ``` "작업 1.2는 테스트를 먼저 작성한 후 구현해줘" "작업 2.1을 전체 테스트 커버리지와 함께 구현해줘" "서비스 작업을 구현하면서 유닛 테스트 작성해줘" ``` #### 문서화 포함 ``` "작업 1.3을 구현하고 API 문서화해줘" "인라인 주석과 함께 인증 작업 완료해줘" "작업 2.2를 구현하고 사용 예제 만들어줘" ``` ## Steering 문서 ### Steering 생성 #### 전체 세트 ``` "내 전자상거래 프로젝트를 위한 steering 문서 만들어줘" "SaaS 애플리케이션을 위한 steering 설정해줘" "모바일 앱을 위한 프로젝트 가이드 만들어줘" ``` #### 개별 문서 ``` "사용자 경험에 집중하는 product steering 문서 만들어줘" "마이크로서비스 아키텍처를 위한 technical steering 만들어줘" "모노레포 설정을 위한 structure steering 만들어줘" ``` #### 컨텍스트로부터 ``` "@project-brief.md를 기반으로 steering 문서 만들어줘" "@architecture.md의 기술적 결정사항으로 steering 생성해줘" ``` ### Steering 업데이트 ``` "product steering을 B2B 기능 포함하도록 업데이트해줘" "technical steering을 REST 대신 GraphQL 사용하도록 수정해줘" "새로운 모듈 시스템을 위한 structure steering 업데이트해줘" ``` ## 승인 워크플로우 ### 피드백 요청 #### 특정 우려사항 포함 ``` "user-auth 요구사항 승인 요청 - 특히 보안 섹션 확인해줘" "payment 설계 검토 요청 - 에러 처리에 집중해줘" "작업 분해 피드백 요청 - 너무 세분화된 거 아니야?" ``` #### 수정 요청 ``` "요구사항에 더 자세한 내용이 필요합니다: - 에러 처리 시나리오 - 성능 요구사항 - 보안 고려사항 수정 후 다시 제출해주세요" ``` ### 승인 결정 #### 승인하기 ``` "user-auth 요구사항 승인해줘" "설계가 괜찮아 보여, 승인해줘" "작업 분해를 그대로 수락해줘" ``` #### 변경 요청 ``` "요구사항 변경 요청: - 멀티 테넌트 지원 추가 - 속도 제한 포함 - 데이터 보관 정책 명시" ``` #### 거부하기 ``` "현재 설계 거부 - 대신 이벤트 주도 아키텍처를 사용해야 해" "요구사항 다시 시작 - 범위가 너무 넓어" ``` ## 버그 워크플로우 ### 버그 보고 #### 상세 보고서 ``` "버그 보고서 만들어줘: 제목: 특수 문자 사용 시 로그인 실패 단계: 1) '+' 포함된 이메일 입력 2) 폼 제출 3) 에러 발생 예상: 로그인 성공 실제: 500 에러 우선순위: 높음 환경: 프로덕션" ``` #### 에러 로그로부터 ``` "이 에러로 버그 보고서 만들어줘: [스택 트레이스 붙여넣기]" "Sentry 알림에서 이 버그 문서화해줘: [링크]" ``` ### 버그 해결 #### 조사 ``` "버그 #45의 근본 원인 조사해줘" "payment webhook이 실패하는 이유 분석해줘" "search 엔드포인트의 성능 문제 디버그해줘" ``` #### 수정 구현 ``` "사용자 인증의 버그 #45 수정 만들어줘" "결제 타임아웃 문제 해결 방법 구현해줘" "알림 서비스의 메모리 누수 수정해줘" ``` ## 구현 중 변경사항 ### 개발 중 Spec 변경 시 요구사항과 설계는 구현 중에 자주 변경됩니다. 이런 경우 완료된 작업을 보존하면서 tasks.md를 현재 spec에 맞게 유지해야 합니다. ### 작업 새로고침 기능 사용 AI는 refresh-tasks 프롬프트를 통해 포괄적인 작업 새로고침 지침에 접근할 수 있습니다. AI에게 변경사항을 간단히 알려주세요: #### 기본 작업 새로고침 ``` "요구사항이 업데이트되었습니다. 현재 requirements.md와 design.md에 맞게 tasks.md를 새로고침해주세요." ``` #### 컨텍스트를 포함한 상세 작업 새로고침 ``` "다음 변경사항으로 spec을 업데이트했습니다: - 보고 모듈 제거 - 데이터베이스를 MongoDB에서 PostgreSQL로 변경 - 소셜 로그인 기능 추가 다음 작업 새로고침 프로세스에 따라 tasks.md를 새로고침해주세요: 1. 모든 완료 및 진행 중인 작업 보존 2. 데이터베이스 변경을 위한 마이그레이션 작업 추가 3. 보고 모듈에 대한 대기 중인 작업 제거 4. 소셜 로그인을 위한 새 작업 추가" ``` #### 마이그레이션이 필요한 아키텍처 변경 ``` "REST API에서 GraphQL로 전환하고 있습니다. 여러 REST 엔드포인트가 이미 구현되어 있습니다. 다음과 같이 tasks.md를 업데이트해주세요: 1. 완료된 모든 REST 작업 보존 2. REST 로직을 GraphQL 리졸버로 래핑하는 마이그레이션 작업 3. 새로운 GraphQL 구현 작업 4. GraphQL 검증 후 REST 제거를 위한 정리 작업" ``` ### 예상 AI 동작 작업 새로고침을 요청하면 AI는 다음을 수행합니다: 1. **현재 상태 분석** - 현재 spec을 위해 requirements.md와 design.md 읽기 - 완료, 진행 중, 대기 중인 작업 식별 - 추가, 제거 또는 변경된 기능 결정 2. **완료된 작업 보존** - 모든 [x] 완료된 작업을 변경하지 않고 유지 - 모든 [-] 진행 중인 작업을 변경하지 않고 유지 - 제거된 기능에 대한 완료된 작업에 메모 추가 3. **아키텍처 변경 처리** - 업데이트가 필요한 완료된 작업 뒤에 마이그레이션 작업 추가 - 점진적 마이그레이션을 위한 전환 작업 생성 - 이전 구현 제거 전 검증 작업 포함 4. **대기 중인 작업 업데이트** - 삭제된 기능에 대한 대기 중인 작업 제거 - 변경된 요구사항에 대한 대기 중인 작업 업데이트 - 새 기능에 대한 새 작업 추가 5. **작업 구조 유지** - 순차적 번호 매기기 유지 - 작업 형식 보존 - 요구사항 참조 포함 - 종속성 순서 유지 ### 예제 시나리오 #### 기능 제거 ``` "spec에서 보고 모듈을 제거하기로 했습니다. 그에 따라 tasks.md를 업데이트해주세요." ``` 예상 AI 동작: - 모든 완료된 보고 작업을 [x] 상태와 함께 유지 - 모든 진행 중인 보고 작업을 [-] 상태와 함께 유지 - 대기 중인 [ ] 보고 작업만 제거 - 메모 추가: "_참고: 보고 기능이 spec에서 제거되었지만 완료된 작업은 보존됨_" #### 완료된 작업이 있는 아키텍처 변경 ``` "MongoDB에서 PostgreSQL로 전환하고 있습니다. 대기 중인 데이터베이스 작업을 업데이트해주세요. 이미 MongoDB 스키마와 연결 로직을 구현했습니다." ``` 예상 AI 동작: - 완료된 모든 MongoDB 작업을 그대로 보존 - 진행 중인 모든 MongoDB 작업을 그대로 보존 - 완료된 MongoDB 작업 바로 뒤에 새로운 마이그레이션 작업 추가: - MongoDB 스키마를 PostgreSQL 테이블로 마이그레이션 - MongoDB 연결 로직을 PostgreSQL 클라이언트로 교체 - 데이터베이스 쿼리를 MongoDB에서 PostgreSQL 구문으로 업데이트 - 기존 MongoDB 데이터를 PostgreSQL로 마이그레이션 - PostgreSQL을 위한 환경 구성 업데이트 - 마이그레이션 검증 후 MongoDB 종속성 제거 - 나머지 대기 중인 데이터베이스 작업을 PostgreSQL 사용하도록 업데이트 - 작업 번호 매기기 순서 유지 #### 기능 추가 ``` "인증 spec에 소셜 로그인 추가해줘. 요구사항과 설계가 업데이트되었습니다." ``` 예상 AI 동작: - 논리적 삽입 지점을 위한 현재 작업 구조 분석 - 적절한 번호로 새로운 소셜 로그인 작업 추가 - 소셜 로그인에 대한 특정 요구사항 참조 - 새 작업이 종속성 순서를 유지하도록 보장 - 기본 인증이 이미 구현된 경우 통합 작업 추가 ### 아키텍처 마이그레이션 처리 이미 구현된 코드에 영향을 미치는 아키텍처 변경 시: #### REST에서 GraphQL 마이그레이션 ``` "REST에서 GraphQL로 변경하고 있습니다. 여러 REST 엔드포인트가 이미 구현되어 있습니다." ``` 예상 작업 추가: - 완료된 REST 엔드포인트 작업 보존 - GraphQL 스키마 정의 작업 추가 - 리졸버 구현 작업 추가 - 기존 REST 로직을 GraphQL 리졸버로 래핑하는 마이그레이션 작업 추가 - 클라이언트 코드를 GraphQL 사용하도록 업데이트하는 작업 추가 - GraphQL 검증 후 REST 엔드포인트 제거를 위한 정리 작업 추가 #### 모놀리스에서 마이크로서비스로 분할 ``` "모놀리식 사용자 서비스를 별도의 인증 및 프로필 서비스로 분할하고 있습니다." ``` 예상 작업 추가: - 완료된 모놀리식 서비스 작업 보존 - 서비스 분리 작업 추가 - 서비스 간 통신 작업 추가 - 데이터베이스가 분할되는 경우 데이터 마이그레이션 작업 추가 - 새 서비스에 대한 배포 구성 작업 추가 - 서비스 검증 후 모놀리식 코드 제거를 위한 정리 작업 추가 ### 마이그레이션을 위한 작업 형식 마이그레이션 작업은 목적을 명확히 표시해야 합니다: ``` "작업을 새로고침한 후 다음이 추가된 것을 확인했습니다: - [ ] 2.4 MongoDB 스키마를 PostgreSQL 테이블로 마이그레이션 - 파일: src/database/migrations/mongo-to-postgres.ts - 문서 스키마를 관계형 테이블로 변환 - 임베디드 문서를 외래 키 관계로 매핑 - 모든 기존 데이터 관계 보존 - 목적: 데이터베이스 레이어를 새 아키텍처로 전환 - _활용: 작업 2.1-2.3에서 완료된 MongoDB 스키마_ - _요구사항: 설계 섹션 3.2_" ``` ### AI에게 변경사항 전달 spec 변경사항을 AI에게 알릴 때: #### 변경사항과 영향에 대해 구체적으로 설명 ``` "결제 처리 요구사항이 변경되었습니다. PayPal 대신 Stripe가 필수입니다. 이미 PayPal webhook 핸들러를 구현했습니다. 마이그레이션 작업을 포함하여 이 변경사항을 반영하도록 tasks.md를 업데이트해주세요." ``` #### 보존 및 마이그레이션을 위한 컨텍스트 제공 ``` "MongoDB에서 PostgreSQL로 이동하더라도 이미 완료된 작업이므로 완료된 모든 MongoDB 작업을 유지해주세요. 구현된 MongoDB 코드를 PostgreSQL로 전환하는 마이그레이션 작업을 추가해주세요." ``` #### 검증 요청 ``` "tasks.md 업데이트 후 requirements.md의 모든 요구사항에 해당 작업이 있는지, 아키텍처 변경을 위한 마이그레이션 경로가 존재하는지, 제거된 기능에 대한 대기 중인 작업이 없는지 확인해주세요." ``` ### 점진적 마이그레이션 전략 주요 아키텍처 변경의 경우 AI는 점진적 마이그레이션을 지원하는 작업을 생성해야 합니다: 1. 기존 것과 함께 새 아키텍처 구현 2. 호환성 레이어 작업 추가 3. 기능을 점진적으로 마이그레이션 4. 각 마이그레이션 단계 검증 5. 전체 검증 후에만 이전 구현 제거 이를 통해 전환 기간 동안 애플리케이션이 계속 작동하도록 보장합니다. ### Refresh Tasks 프롬프트 사용 refresh tasks 프롬프트를 명시적으로 호출할 수도 있습니다: ``` "user-auth spec에 대해 refresh-tasks 프롬프트를 사용해줘. 변경사항은: 인증을 JWT에서 OAuth2로 전환." ``` 그러면 AI는 포괄적인 새로고침 지침에 따라 완료된 모든 작업을 보존하면서 작업을 업데이트합니다. ## 고급 패턴 ### 멀티 Spec 워크플로우 #### 관련 Spec ``` "다음과 통합되는 admin-dashboard spec 만들어줘: - user-management spec - analytics spec - reporting spec" ``` #### Spec 종속성 ``` "다음에 의존하는 notifications spec 만들어줘: - user-auth 완료 - message-queue 구현 - email-service 사용 가능" ``` ### 점진적 개발 #### MVP 우선 ``` "다음만 포함하는 user-profiles MVP spec 만들어줘: - 기본 프로필 생성 - 표시 이름과 아바타 - 공개 프로필 보기 (소셜 기능은 나중에 추가할게요)" ``` #### 개선 Spec ``` "다음을 추가하는 user-auth 개선 spec 만들어줘: - 소셜 로그인 (Google, GitHub) - 생체 인증 - 향상된 세션 관리 - 계정 연결" ``` ### 복잡한 시나리오 #### 마이그레이션 Spec ``` "MongoDB에서 PostgreSQL로 마이그레이션하는 spec 만들어줘: - 현재 스키마 문서화 - 새 관계형 구조 설계 - 무중단 마이그레이션 계획 - 롤백 절차 포함" ``` #### 리팩토링 Spec ``` "다음을 위한 리팩토링 spec 만들어줘: - 모놀리스를 서비스로 분할 - 공유 컴포넌트 추출 - 테스트 커버리지를 80%로 개선 - 하위 호환성 유지" ``` #### 성능 Spec ``` "성능 최적화 spec 만들어줘: - 현재 병목 지점 프로파일링 - 캐싱 전략 설계 - 데이터베이스 인덱싱 계획 - 모니터링 구현" ``` ## 워크플로우 조합 ### 완전한 기능 흐름 ``` 1. "프로젝트를 위한 steering 문서 만들어줘" 2. "사용자 인증을 위한 spec 만들어줘" 3. "요구사항 검토 및 승인" 4. "설계 검토 및 승인" 5. "작업 1.1 구현 - 데이터베이스 스키마" 6. "작업 1.2 구현 - 인증 서비스" 7. "인증 흐름에 대한 테스트 만들어줘" 8. "모든 작업을 완료로 표시" ``` ### 병렬 개발 ``` "내가 요구사항을 검토하는 동안 API 설계 초안을 시작해줘" "프론트엔드와 백엔드 spec을 병렬로 만들어줘" "백엔드 팀이 API 작업을 하는 동안 UI 작업 처리해줘" ``` ### 반복적 개선 ``` 1. "검색을 위한 초기 spec 만들어줘" 2. "기본 검색 구현 (작업 1-3)" 3. "고급 검색을 위한 개선 spec 만들어줘" 4. "필터링 및 정렬 기능 추가" 5. "검색 성능을 위한 최적화 spec 만들어줘" ``` ## 컨텍스트 인식 프롬프트 ### 프로젝트 컨텍스트 사용 ``` "우리의 기존 패턴을 따르는 spec 만들어줘" "우리 코드베이스와 일관되게 이 작업 구현해줘" "우리의 현재 아키텍처와 통합되도록 이 기능 설계해줘" ``` ### 다른 Spec 참조 ``` "user-auth와 유사하지만 관리자 인증을 위한 spec 만들어줘" "payment spec과 동일한 설계 패턴 사용해줘" "우리 notification spec의 작업 구조를 따라줘" ``` ### 이전 작업을 기반으로 구축 ``` "user-auth spec을 팀 관리 포함하도록 확장해줘" "기존 REST API spec에 GraphQL 지원 추가해줘" "search spec을 머신러닝 기능으로 개선해줘" ``` ## 효과적인 프롬프팅을 위한 팁 ### 구체적으로 ❌ **모호함**: "로그인 spec 만들어줘" ✅ **구체적**: "2FA, 자동 로그인 유지, 비밀번호 재설정이 포함된 이메일/비밀번호 로그인 spec 만들어줘" ### 컨텍스트 제공 ❌ **컨텍스트 없음**: "작업 구현해줘" ✅ **컨텍스트 포함**: "우리의 기존 Express 미들웨어와 PostgreSQL 데이터베이스를 사용해서 작업 1.2 구현해줘" ### 명확한 기대치 설정 ❌ **불명확**: "더 좋게 만들어줘" ✅ **명확**: "200ms 미만의 응답 시간으로 현재 트래픽의 10배를 처리하도록 설계를 개선해줘" ### 점진적 요청 사용 ❌ **너무 많음**: "5개의 spec 만들고 모든 것 구현해줘" ✅ **점진적**: "먼저 user-auth spec을 만들고 다음으로 넘어가기 전에 검토할게요" ### 기존 작업 참조 ❌ **새로 시작**: "새 결제 시스템 만들어줘" ✅ **기반 구축**: "우리의 payment spec을 구독 청구 추가하도록 개선해줘" ## 일반 패턴 라이브러리 ### CRUD 작업 ``` "다음을 포함하는 제품에 대한 CRUD 작업 spec 만들어줘: - 검증과 함께 생성 - 페이지네이션 및 필터링과 함께 읽기 - 낙관적 잠금과 함께 업데이트 - 복구 옵션이 있는 소프트 삭제" ``` ### 인증 및 권한 부여 ``` "다음을 포함하는 인증 spec 만들어줘: - JWT 기반 인증 - 역할 기반 접근 제어 - API 키 관리 - 세션 처리 - 리프레시 토큰 로테이션" ``` ### 실시간 기능 ``` "다음을 포함하는 실시간 채팅 spec 만들어줘: - WebSocket 연결 - 메시지 지속성 - 타이핑 표시기 - 읽음 확인 - 오프라인 메시지 큐" ``` ### 파일 관리 ``` "다음을 포함하는 파일 업로드 spec 만들어줘: - 대용량 파일을 위한 청크 업로드 - 진행 상황 추적 - 재개 기능 - 바이러스 스캔 - CDN 통합" ``` ### 분석 및 보고 ``` "다음을 포함하는 분석 spec 만들어줘: - 이벤트 추적 - 사용자 정의 차원 - 실시간 대시보드 - 예약된 보고서 - 데이터 내보내기 옵션" ``` ## 문제 해결 프롬프트 ### 문제 발생 시 ``` "이 spec이 표시되지 않는 이유는?" "작업이 완료되지 않는 이유 디버그해줘" "승인을 막고 있는 것은 뭐야?" "이 에러를 이해하도록 도와줘" ``` ### 막힘 해소 ``` "다음에 뭘 해야 해?" "진행을 막고 있는 것 보여줘" "기다리는 동안 처리할 수 있는 작업은 뭐야?" "이 종속성을 어떻게 해결해?" ``` ## 관련 문서 - [사용자 가이드](USER-GUIDE.md) - 일반 사용 지침 - [워크플로우 프로세스](WORKFLOW.md) - 워크플로우 이해 - [도구 참조](TOOLS-REFERENCE.md) - 완전한 도구 문서 - [문제 해결](TROUBLESHOOTING.md) - 일반적인 문제 해결