tomevault-io argument: $1
Spec Skill: 요구사항 구체화 및 스펙 문서 작성
이 스킬은 사용자가 무엇을 만들어야 하는지를 질의응답을 통해 구체화하고, 명확한 스펙 문서를 생성합니다.
🎯 핵심 원칙
- What & Why에 집중: 코드 세부사항(How)이 아닌, 무엇을(What)과 왜(Why)를 명확히
- 상위 수준 비전 우선: 큰 그림부터 시작해서 세부사항으로 확장
- 질의응답 기반 구체화: 모호한 부분은 가정하지 말고 사용자에게 질문
- 살아있는 문서: 프로젝트와 함께 진화하는 스펙
📋 실행 프로세스
Phase 1: 초기 분석 (Understand)
사용자의 인풋($1)을 분석하고 다음을 파악합니다:
- 핵심 목표 (Goal)
- 대상 사용자 (Who)
- 해결하려는 문제 (Problem)
- 기대하는 결과 (Expected Outcome)
Phase 2: 명확화 질문 (Clarify)
모호하거나 누락된 정보에 대해 한국어로 질문합니다. 질문은 다음 카테고리로 구성됩니다:
필수 질문 (항상 확인)
- 범위(Scope): 이 기능/컴포넌트의 경계는 어디까지인가?
- 사용자(User): 누가 이것을 사용하는가? 어떤 상황에서?
- 성공 기준(Success Criteria): 완료되었다고 판단하는 기준은?
상황별 질문 (필요시)
- 기존 시스템과의 통합 포인트
- 의존하는 다른 기능/컴포넌트
- 제약 조건 (시간, 성능, 접근성 등)
- 예외 상황 및 에러 처리 방식
Phase 3: 스펙 문서 생성 (Generate)
질의응답 완료 후, SPEC.md 파일을 프로젝트 루트에 생성합니다.
📄 SPEC.md 템플릿
# [기능/컴포넌트명] 스펙
> 📅 작성일: YYYY-MM-DD
> 📌 상태: Draft | In Review | Approved
> 🔗 관련 문서: survey.md → plan.md → milestone.md
---
## 1. 개요 (Overview)
### 1.1 목표 (Goal)
<!-- 한 문장으로 이 기능/컴포넌트의 목적 -->
### 1.2 배경 (Background)
<!-- 왜 이것이 필요한가? 어떤 문제를 해결하는가? -->
### 1.3 범위 (Scope)
#### 포함 사항 (In Scope)
-
#### 제외 사항 (Out of Scope)
- ***
## 2. 사용자 및 시나리오 (Users & Scenarios)
### 2.1 대상 사용자
| 사용자 유형 | 설명 | 주요 니즈 |
| ----------- | ---- | --------- |
| | | |
### 2.2 사용자 시나리오
#### 시나리오 1: [시나리오명]
- **사용자**:
- **상황**:
- **행동**:
- **기대 결과**:
---
## 3. 기능 요구사항 (Functional Requirements)
### 3.1 핵심 기능
| ID | 기능명 | 설명 | 우선순위 |
| --- | ------ | ---- | -------- |
| F1 | | | Must |
| F2 | | | Should |
| F3 | | | Could |
### 3.2 기능 상세
#### F1: [기능명]
- **입력**:
- **처리**:
- **출력**:
- **예외 처리**:
---
## 4. 비기능 요구사항 (Non-Functional Requirements)
### 4.1 성능
-
### 4.2 접근성
-
### 4.3 보안
-
### 4.4 호환성
- ***
## 5. 제약 조건 (Constraints)
### 5.1 기술적 제약
-
### 5.2 비즈니스 제약
-
### 5.3 의존성
- ***
## 6. 성공 기준 (Success Criteria)
### 6.1 기능적 완료 조건
- [ ]
### 6.2 품질 기준
- [ ]
### 6.3 인수 기준 (Acceptance Criteria)
- [ ]
---
## 7. 경계 조건 및 엣지 케이스 (Edge Cases)
| 상황 | 예상 동작 | 비고 |
| ---- | --------- | ---- |
| | | |
---
## 8. 용어 정의 (Glossary)
| 용어 | 정의 | 비고 |
| ---- | ---- | ---- |
| | | |
---
## 9. 미해결 사항 (Open Questions)
- [ ]
---
## 10. 변경 이력 (Changelog)
| 날짜 | 버전 | 변경 내용 | 작성자 |
| ---- | ---- | --------- | ------ |
| | 0.1 | 초안 작성 | |
🚫 금지 사항 (What NOT to Include)
스펙 문서에는 다음을 포함하지 않습니다:
코드 구현 세부사항
- ❌ "useState를 사용하여 상태를 관리한다"
- ✅ "컴포넌트는 선택 상태를 유지해야 한다"
특정 라이브러리/프레임워크 강제
- ❌ "Zustand store로 전역 상태를 관리한다"
- ✅ "애플리케이션 전역에서 접근 가능한 상태가 필요하다"
파일/폴더 구조
- ❌ "src/components/Button/Button.tsx에 생성"
- ✅ "재사용 가능한 버튼 컴포넌트"
CSS/스타일링 상세
- ❌ "padding: 16px, border-radius: 8px"
- ✅ "적절한 여백과 둥근 모서리로 친근한 느낌"
✅ 체크리스트: 좋은 스펙인가?
생성된 스펙을 다음 기준으로 검증합니다:
- 명확성: 모호한 표현 없이 이해 가능한가?
- 완전성: 필요한 정보가 모두 포함되었는가?
- 검증 가능성: 성공 기준이 측정 가능한가?
- 독립성: 구현 방식에 종속되지 않았는가?
- 추적 가능성: 각 요구사항에 ID가 있는가?
🔄 워크플로우 연결
이 스펙은 다음 단계로 연결됩니다:
[spec.md] → [survey.md] → [plan.md] → [milestone.md]
↓ ↓ ↓ ↓
무엇을 아키텍처 기술 계획 작업 분할
만들까? 질문들 어떻게? 언제까지?
다음 단계 안내
스펙 작성 완료 후:
/survey명령으로 아키텍처 관련 질문 생성/plan명령으로 기술 계획 수립/milestone명령으로 작업 분할 및 일정 수립
📝 실행 지침
- 사용자의 초기 요청(
$1)을 분석합니다. - 모호한 부분에 대해 한국어로 명확화 질문을 합니다.
- 충분한 정보가 수집되면 위 템플릿에 맞춰
SPEC.md를 생성합니다. - 생성된 스펙을 사용자에게 보여주고 피드백을 받습니다.
- 피드백 반영 후 최종본을 프로젝트 루트에 저장합니다.
CRITICAL:
- 모든 출력은 한국어로 작성합니다.
- 질문은 한 번에 3-5개로 제한하여 사용자를 압도하지 않습니다.
- 코드 레벨의 세부사항은 절대 포함하지 않습니다.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.