Spec Workflow MCP

# 인터페이스 가이드 이 가이드는 Spec Workflow MCP의 두 가지 주요 인터페이스인 웹 대시보드와 VSCode 확장 프로그램을 다룹니다. ## 개요 Spec Workflow MCP는 두 가지 인터페이스를 제공합니다: 1. **웹 대시보드** - CLI 사용자를 위한 브라우저 기반 인터페이스 2. **VSCode 확장 프로그램** - VSCode 사용자를 위한 통합 IDE 환경 두 인터페이스 모두 플랫폼별 최적화와 함께 동일한 핵심 기능을 제공합니다. ## 웹 대시보드 ### 개요 웹 대시보드는 스펙, 작업 및 승인 워크플로우에 대한 시각적 액세스를 제공하는 실시간 웹 애플리케이션입니다. ### 대시보드 시작 #### 독립형 대시보드 ```bash # 임시 포트 사용 npx -y @pimzino/spec-workflow-mcp@latest /path/to/project --dashboard # 사용자 지정 포트 npx -y @pimzino/spec-workflow-mcp@latest /path/to/project --dashboard --port 3000 ``` #### MCP 서버와 함께 ```bash # MCP와 함께 자동 시작 npx -y @pimzino/spec-workflow-mcp@latest /path/to/project --AutoStartDashboard ``` ### 대시보드 기능 #### 메인 뷰 대시보드 홈에 표시되는 내용: - **프로젝트 개요** - 활성 스펙 수 - 총 작업 수 - 완료 비율 - 최근 활동 - **스펙 카드** - 스펙 이름 및 상태 - 진행률 표시줄 - 문서 표시기 - 빠른 작업 #### 스펙 상세 뷰 스펙을 클릭하면 표시: - **문서 탭** - 요구사항 - 설계 - 작업 - **문서 내용** - 렌더링된 마크다운 - 구문 강조 - 목차 - **승인 작업** - 승인 버튼 - 변경 요청 - 거부 옵션 - 댓글 필드 #### 작업 관리 작업 뷰에서 제공: - **계층적 작업 목록** - 번호가 매겨진 작업 (1.0, 1.1, 1.1.1) - 상태 표시기 - 진행 추적 - **작업 액션** - 프롬프트 복사 버튼 - 완료 표시 - 메모 추가 - 종속성 보기 - **진행 시각화** - 전체 진행률 표시줄 - 섹션 진행 - 시간 추정 #### 스티어링 문서 프로젝트 가이드 액세스: - **제품 스티어링** - 비전 및 목표 - 사용자 페르소나 - 성공 메트릭 - **기술 스티어링** - 아키텍처 결정 - 기술 선택 - 성능 목표 - **구조 스티어링** - 파일 구성 - 명명 규칙 - 모듈 경계 ### 대시보드 탐색 #### 키보드 단축키 | 단축키 | 작업 | |----------|--------| | `Alt + S` | 스펙 목록에 포커스 | | `Alt + T` | 작업 보기 | | `Alt + R` | 요구사항 보기 | | `Alt + D` | 설계 보기 | | `Alt + A` | 승인 대화상자 열기 | | `Esc` | 대화상자 닫기 | #### URL 구조 특정 뷰에 대한 직접 링크: - `/` - 홈 대시보드 - `/spec/{name}` - 특정 스펙 - `/spec/{name}/requirements` - 요구사항 문서 - `/spec/{name}/design` - 설계 문서 - `/spec/{name}/tasks` - 작업 목록 - `/steering/{type}` - 스티어링 문서 ### 실시간 업데이트 대시보드는 실시간 업데이트를 위해 WebSocket을 사용: - **자동 새로고침** - 새 스펙이 즉시 표시 - 작업 상태 업데이트 - 진행 변경 - 승인 알림 - **연결 상태** - 녹색: 연결됨 - 노란색: 재연결 중 - 빨간색: 연결 끊김 - **알림 시스템** - 승인 요청 - 작업 완료 - 오류 경고 - 성공 메시지 ### 대시보드 사용자 지정 #### 테마 설정 밝은 모드와 어두운 모드 간 전환: - 헤더의 테마 아이콘 클릭 - 세션 간 유지 - 시스템 기본 설정 존중 #### 언어 선택 인터페이스 언어 변경: 1. 설정 아이콘 클릭 2. 드롭다운에서 언어 선택 3. 인터페이스가 즉시 업데이트 지원 언어: - English (en) - Japanese (ja) - Chinese (zh) - Spanish (es) - Portuguese (pt) - German (de) - French (fr) - Russian (ru) - Italian (it) - Korean (ko) - Arabic (ar) #### 표시 옵션 뷰 기본 설정 사용자 지정: - 컴팩트/확장 스펙 카드 - 완료된 작업 표시/숨기기 - 문서 글꼴 크기 - 코드 구문 테마 ## VSCode 확장 프로그램 ### 설치 VSCode 마켓플레이스에서 설치: 1. VSCode 확장 프로그램 열기 (Ctrl+Shift+X) 2. "Spec Workflow MCP" 검색 3. 설치 클릭 4. VSCode 리로드 또는 명령줄을 통해: ```bash code --install-extension Pimzino.spec-workflow-mcp ``` ### 확장 프로그램 기능 #### 사이드바 패널 활동 표시줄 아이콘을 통해 액세스: - **스펙 탐색기** - 모든 스펙의 트리 뷰 - 문서를 보려면 확장 - 상태 표시기 - 컨텍스트 메뉴 작업 - **작업 목록** - 필터링 가능한 작업 뷰 - 진행 추적 - 빠른 작업 - 검색 기능 - **아카이브 뷰** - 완료된 스펙 - 기록 데이터 - 복원 옵션 - 대량 작업 #### 문서 뷰어 편집기에서 문서 열기: - **구문 강조** - 마크다운 렌더링 - 코드 블록 - 작업 체크박스 - 링크 및 참조 - **문서 액션** - 제자리 편집 - 미리보기 모드 - 분할 뷰 - 내보내기 옵션 #### 통합 승인 다음을 위한 네이티브 VSCode 대화상자: - **승인 요청** - 팝업 알림 - 인라인 주석 - 빠른 승인/거부 - 상세한 피드백 - **수정 워크플로우** - 변경 사항 추적 - 주석 스레드 - 버전 비교 - 승인 기록 #### 컨텍스트 메뉴 액션 편집기에서 마우스 오른쪽 버튼 클릭 액션: - **스펙 파일에서** - 문서 승인 - 변경 요청 - 대시보드에서 보기 - 스펙 경로 복사 - **작업 항목에서** - 완료 표시 - 프롬프트 복사 - 하위 작업 추가 - 세부 정보 보기 ### 확장 프로그램 설정 VSCode 설정에서 구성: ```json { "specWorkflow.language": "en", "specWorkflow.notifications.enabled": true, "specWorkflow.notifications.sound": true, "specWorkflow.notifications.volume": 0.5, "specWorkflow.archive.showInExplorer": true, "specWorkflow.tasks.autoRefresh": true, "specWorkflow.tasks.refreshInterval": 5000, "specWorkflow.theme.followVSCode": true } ``` #### 설정 설명 | 설정 | 설명 | 기본값 | |---------|-------------|---------| | `language` | 인터페이스 언어 | "en" | | `notifications.enabled` | 알림 표시 | true | | `notifications.sound` | 사운드 경고 재생 | true | | `notifications.volume` | 사운드 볼륨 (0-1) | 0.5 | | `archive.showInExplorer` | 아카이브된 스펙 표시 | true | | `tasks.autoRefresh` | 작업 자동 새로고침 | true | | `tasks.refreshInterval` | 새로고침 간격 (ms) | 5000 | | `theme.followVSCode` | VSCode 테마 일치 | true | ### 확장 프로그램 명령어 명령 팔레트에서 사용 가능 (Ctrl+Shift+P): | 명령어 | 설명 | |---------|-------------| | `Spec Workflow: Create Spec` | 새 스펙 시작 | | `Spec Workflow: List Specs` | 모든 스펙 표시 | | `Spec Workflow: View Dashboard` | 웹 대시보드 열기 | | `Spec Workflow: Archive Spec` | 아카이브로 이동 | | `Spec Workflow: Restore Spec` | 아카이브에서 복원 | | `Spec Workflow: Refresh` | 스펙 데이터 다시 로드 | | `Spec Workflow: Show Steering` | 스티어링 문서 보기 | | `Spec Workflow: Export Spec` | 마크다운으로 내보내기 | ### 사운드 알림 확장 프로그램에는 다음에 대한 오디오 경고가 포함됩니다: - **승인 요청** - 부드러운 차임 - **작업 완료** - 성공 사운드 - **오류** - 경고 톤 - **업데이트** - 부드러운 알림 설정에서 구성: ```json { "specWorkflow.notifications.sound": true, "specWorkflow.notifications.volume": 0.3 } ``` ## 기능 비교 | 기능 | 웹 대시보드 | VSCode 확장 프로그램 | |---------|--------------|------------------| | 스펙 보기 | ✅ | ✅ | | 작업 관리 | ✅ | ✅ | | 승인 | ✅ | ✅ | | 실시간 업데이트 | ✅ | ✅ | | 아카이브 시스템 | ❌ | ✅ | | 사운드 알림 | ❌ | ✅ | | 편집기 통합 | ❌ | ✅ | | 컨텍스트 메뉴 | ❌ | ✅ | | 키보드 단축키 | 제한적 | 전체 | | 다중 프로젝트 | 수동 | 자동 | | 오프라인 액세스 | ❌ | ✅ | | 내보내기 옵션 | 기본 | 고급 | ## 올바른 인터페이스 선택 ### 웹 대시보드를 사용해야 하는 경우: - CLI 기반 AI 도구 사용 - 여러 IDE에서 작업 - 브라우저 기반 액세스 필요 - 팀 구성원과 공유 - 빠른 프로젝트 개요 필요 ### VSCode 확장 프로그램을 사용해야 하는 경우: - 주요 IDE가 VSCode - 통합 환경 원함 - 편집기 기능 필요 - 네이티브 대화상자 선호 - 사운드 알림 원함 ## 인터페이스 동기화 두 인터페이스 모두 동일한 데이터를 공유: - **실시간 동기화** - 하나의 변경 사항이 다른 것에 반영 - 공유 승인 상태 - 일관된 작업 상태 - 통합 진행 추적 - **데이터 저장** - 단일 진실 공급원 - 파일 기반 저장소 - 동기화 불필요 - 즉각적인 업데이트 ## 모바일 및 태블릿 액세스 ### 모바일에서 웹 대시보드 대시보드는 반응형: - **휴대전화 뷰** - 스택형 스펙 카드 - 접을 수 있는 탐색 - 터치 최적화 버튼 - 스와이프 제스처 - **태블릿 뷰** - 나란히 레이아웃 - 터치 상호작용 - 최적화된 간격 - 가로 모드 지원 ### 모바일의 제한사항 - VSCode 확장 프로그램 없음 - 제한된 키보드 단축키 - 감소된 멀티태스킹 - 단순화된 상호작용 ## 접근성 기능 ### 웹 대시보드 - **키보드 탐색** - 요소 간 탭 이동 - 활성화하려면 Enter - 취소하려면 Escape - 목록용 화살표 키 - **스크린 리더 지원** - ARIA 레이블 - 역할 속성 - 상태 알림 - 포커스 관리 - **시각적 접근성** - 고대비 모드 - 조정 가능한 글꼴 크기 - 색맹 친화적 - 포커스 표시기 ### VSCode 확장 프로그램 VSCode 접근성 상속: - 스크린 리더 지원 - 키보드 탐색 - 고대비 테마 - 확대/축소 기능 ## 성능 최적화 ### 대시보드 성능 - **지연 로딩** - 문서가 필요할 때 로드 - 긴 목록에 페이지 매김 - 프로그레시브 렌더링 - 이미지 최적화 - **캐싱 전략** - 브라우저 캐싱 - 서비스 워커 - 오프라인 지원 (제한적) - 빠른 탐색 ### 확장 프로그램 성능 - **리소스 관리** - 최소 메모리 사용 - 효율적인 파일 감시 - 디바운스된 업데이트 - 백그라운드 처리 ## 인터페이스 문제 해결 ### 대시보드 문제 | 문제 | 해결책 | |-------|----------| | 로드되지 않음 | 서버가 실행 중인지 확인, URL 검증 | | 업데이트 없음 | WebSocket 연결 확인, 페이지 새로고침 | | 승인이 작동하지 않음 | 대시보드와 MCP가 연결되었는지 확인 | | 스타일 깨짐 | 브라우저 캐시 지우기, 콘솔 확인 | ### 확장 프로그램 문제 | 문제 | 해결책 | |-------|----------| | 스펙이 표시되지 않음 | 프로젝트에 .spec-workflow 디렉터리가 있는지 확인 | | 명령어가 작동하지 않음 | VSCode 창 리로드 | | 알림 없음 | 확장 프로그램 설정 확인 | | 아카이브가 보이지 않음 | 설정에서 활성화 | ## 고급 사용법 ### 사용자 지정 대시보드 URL 여러 터미널에서 구성: ```bash # 터미널 1: MCP 서버 npx -y @pimzino/spec-workflow-mcp@latest /project # 터미널 2: 대시보드 npx -y @pimzino/spec-workflow-mcp@latest /project --dashboard --port 3000 ``` ### 확장 프로그램 다중 루트 작업 공간 확장 프로그램은 VSCode 다중 루트 작업 공간을 지원: 1. 여러 프로젝트 폴더 추가 2. 각각 별도 스펙 표시 3. 프로젝트 간 전환 4. 독립적인 구성 ## 관련 문서 - [구성 가이드](CONFIGURATION.md) - 설정 및 구성 - [사용자 가이드](USER-GUIDE.md) - 인터페이스 사용 - [워크플로우 프로세스](WORKFLOW.md) - 개발 워크플로우 - [문제 해결](TROUBLESHOOTING.md) - 일반적인 문제