# Spec

> 요구사항을 질의응답으로 구체화하여 스펙 문서 생성. "스펙 작성", "기능 정의", "컴포넌트 명세", "무엇을 만들지" 등의 요청 시 사용 Use when this capability is needed.

- Skill: `tomevault-io/spec-4` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/spec-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/spec-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/spec-4

---


argument: $1

# Spec Skill: 요구사항 구체화 및 스펙 문서 작성

이 스킬은 **사용자가 무엇을 만들어야 하는지**를 질의응답을 통해 구체화하고, 명확한 스펙 문서를 생성합니다.

## 🎯 핵심 원칙

1. **What & Why에 집중**: 코드 세부사항(How)이 아닌, 무엇을(What)과 왜(Why)를 명확히
2. **상위 수준 비전 우선**: 큰 그림부터 시작해서 세부사항으로 확장
3. **질의응답 기반 구체화**: 모호한 부분은 가정하지 말고 사용자에게 질문
4. **살아있는 문서**: 프로젝트와 함께 진화하는 스펙

## 📋 실행 프로세스

### Phase 1: 초기 분석 (Understand)

사용자의 인풋(`$1`)을 분석하고 다음을 파악합니다:

- 핵심 목표 (Goal)
- 대상 사용자 (Who)
- 해결하려는 문제 (Problem)
- 기대하는 결과 (Expected Outcome)

### Phase 2: 명확화 질문 (Clarify)

모호하거나 누락된 정보에 대해 **한국어로** 질문합니다.
질문은 다음 카테고리로 구성됩니다:

#### 필수 질문 (항상 확인)

- [ ] **범위(Scope)**: 이 기능/컴포넌트의 경계는 어디까지인가?
- [ ] **사용자(User)**: 누가 이것을 사용하는가? 어떤 상황에서?
- [ ] **성공 기준(Success Criteria)**: 완료되었다고 판단하는 기준은?

#### 상황별 질문 (필요시)

- 기존 시스템과의 통합 포인트
- 의존하는 다른 기능/컴포넌트
- 제약 조건 (시간, 성능, 접근성 등)
- 예외 상황 및 에러 처리 방식

### Phase 3: 스펙 문서 생성 (Generate)

질의응답 완료 후, `SPEC.md` 파일을 프로젝트 루트에 생성합니다.

---

## 📄 SPEC.md 템플릿

```markdown
# [기능/컴포넌트명] 스펙

> 📅 작성일: 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)

스펙 문서에는 다음을 **포함하지 않습니다**:

1. **코드 구현 세부사항**
   - ❌ "useState를 사용하여 상태를 관리한다"
   - ✅ "컴포넌트는 선택 상태를 유지해야 한다"

2. **특정 라이브러리/프레임워크 강제**
   - ❌ "Zustand store로 전역 상태를 관리한다"
   - ✅ "애플리케이션 전역에서 접근 가능한 상태가 필요하다"

3. **파일/폴더 구조**
   - ❌ "src/components/Button/Button.tsx에 생성"
   - ✅ "재사용 가능한 버튼 컴포넌트"

4. **CSS/스타일링 상세**
   - ❌ "padding: 16px, border-radius: 8px"
   - ✅ "적절한 여백과 둥근 모서리로 친근한 느낌"

---

## ✅ 체크리스트: 좋은 스펙인가?

생성된 스펙을 다음 기준으로 검증합니다:

- [ ] **명확성**: 모호한 표현 없이 이해 가능한가?
- [ ] **완전성**: 필요한 정보가 모두 포함되었는가?
- [ ] **검증 가능성**: 성공 기준이 측정 가능한가?
- [ ] **독립성**: 구현 방식에 종속되지 않았는가?
- [ ] **추적 가능성**: 각 요구사항에 ID가 있는가?

---

## 🔄 워크플로우 연결

이 스펙은 다음 단계로 연결됩니다:

```
[spec.md] → [survey.md] → [plan.md] → [milestone.md]
    ↓            ↓            ↓            ↓
  무엇을      아키텍처      기술 계획     작업 분할
  만들까?     질문들       어떻게?       언제까지?
```

### 다음 단계 안내

스펙 작성 완료 후:

1. `/survey` 명령으로 아키텍처 관련 질문 생성
2. `/plan` 명령으로 기술 계획 수립
3. `/milestone` 명령으로 작업 분할 및 일정 수립

---

## 📝 실행 지침

1. 사용자의 초기 요청(`$1`)을 분석합니다.
2. 모호한 부분에 대해 **한국어로** 명확화 질문을 합니다.
3. 충분한 정보가 수집되면 위 템플릿에 맞춰 `SPEC.md`를 생성합니다.
4. 생성된 스펙을 사용자에게 보여주고 피드백을 받습니다.
5. 피드백 반영 후 최종본을 프로젝트 루트에 저장합니다.

**CRITICAL**:

- 모든 출력은 **한국어**로 작성합니다.
- 질문은 한 번에 3-5개로 제한하여 사용자를 압도하지 않습니다.
- 코드 레벨의 세부사항은 절대 포함하지 않습니다.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/gihwan-dev) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->