---
description: 요구사항 정제 및 검증 기준 추출
---

# /weave-spec - 요구사항 정제

## 개요

기획 문서나 자연어 요구사항을 **구조화된 명세**로 정제합니다.
각 요구사항에서 **검증 기준(Acceptance Criteria)**을 추출하여, 이후 구현 완료의 성공 판정 기준으로 사용합니다.

**입력 방식**: `/weave-design`과 동일
- 정확한 경로: `docs/`, `wiki/spec.md`
- 자연어 힌트: `기획 폴더`, `README`

> 이 커맨드는 **선택 사항**입니다. `/weave-design`을 바로 실행해도 됩니다.
> 요구사항이 복잡하거나, 구현 완료 기준을 명확히 하고 싶을 때 사용합니다.

---

## 실행

```txt
weave command=spec docsPath="$ARGUMENTS"
```

---

## 사전 조건

`/weave-init`이 실행되어 있어야 합니다.
실행되지 않았다면 자동으로 init을 먼저 수행합니다.

---

## 실행 흐름

```
0. INIT CHECK
   ↓
1. RESOLVE (입력 해석 → 실제 경로 찾기)
   ↓
2. ANALYZE (문서에서 요구사항 추출)
   ↓
3. STRUCTURE (요구사항 분류 + 검증 기준 도출)
   ↓
4. REVIEW (유저에게 제시 → 피드백)
   ↓
5. SAVE (스펙 파일 생성)
```

---

## 단계별 상세

### Step 0: INIT CHECK

`.opencode/weave/state.yaml` 존재 확인. 없으면 `/weave-init` 자동 실행.

### Step 1: RESOLVE

`/weave-design`과 동일한 경로 해석 로직. (정확한 경로, 디렉토리 힌트, 시간 힌트, 내용 힌트 등)

### Step 2: ANALYZE

**수행 작업**:
1. 해석된 경로의 모든 문서 읽기
2. 기능 요구사항과 비기능 요구사항 분리
3. 암묵적 요구사항 식별 (명시되지 않았지만 당연히 필요한 것)
4. 요구사항 간 의존관계 파악
5. 과거 유사 프로젝트 검색 (Memory 시스템)

### Step 3: STRUCTURE

각 요구사항을 정제하고, **검증 기준**을 도출합니다.

#### 요구사항 분류

| 분류 | 설명 | 예시 |
|------|------|------|
| `functional` | 시스템이 해야 하는 동작 | 사용자가 로그인할 수 있다 |
| `constraint` | 기술적/비즈니스 제약 | 데이터를 외부 서버로 전송하지 않는다 |
| `performance` | 성능 요구 | 목록 로딩 2초 이내 |
| `ux` | 사용성/접근성 요구 | 모바일에서도 사용 가능해야 한다 |

#### 우선순위 (MoSCoW)

| 값 | 의미 |
|----|------|
| `must` | 없으면 출시 불가 |
| `should` | 강력히 권장, 가능하면 포함 |
| `could` | 있으면 좋지만 없어도 됨 |
| `wont` | 이번 범위에서 명시적으로 제외 |

#### 검증 기준 유형

| type | 의미 | 실행 방법 |
|------|------|----------|
| `e2e` | 브라우저/UI 시나리오 테스트 | Playwright, Cypress 등 |
| `integration` | API/서비스 간 통합 테스트 | supertest, httpx, curl 등 |
| `script` | CLI/스크립트 실행 결과 확인 | shell script, node script |
| `performance` | 성능 기준 충족 | benchmark, lighthouse 등 |
| `manual` | 자동화 불가, 사용자 확인 | 체크리스트로 유저 핸드오프에 포함 |

#### 검증 기준 작성 원칙

- **모호하지 않을 것**: "잘 동작한다" ✗ → "저장 후 목록에서 확인 가능" ✓
- **실행 가능할 것**: 구체적인 입력과 기대 결과를 명시
- **독립적일 것**: 하나의 기준이 하나의 시나리오만 검증
- **유형은 정직하게**: E2E가 불가능한 것은 `manual`로. 억지로 자동화하지 않음

### Step 4: REVIEW

구조화된 명세를 유저에게 제시합니다:

```markdown
## 요구사항 명세

**스펙 이름**: `emotion-diary` (변경 가능)

### 기능 요구사항 (Functional)

**R1** [must]: 사용자가 감정을 선택하고 일기를 저장할 수 있다
- [e2e] 감정 선택 → 텍스트 입력 → 저장 → 목록에서 확인
- [e2e] 빈 텍스트로 저장 시도 → 에러 메시지 표시

**R2** [must]: 저장된 일기 목록을 조회할 수 있다
- [e2e] 저장된 일기 3개가 목록에 최신순으로 표시

### 비기능 요구사항

**R3** [should]: 일기 목록이 2초 이내에 로딩된다
- [performance] 100개 일기 기준 로딩 시간 < 2000ms

**R4** [could]: 오프라인에서도 저장된 일기를 조회할 수 있다
- [manual] 네트워크 차단 후 기존 일기 목록 접근 가능

---
빠진 요구사항이 있거나, 검증 기준을 수정하고 싶으면 말씀해주세요.
```

### Step 5: SAVE

유저 승인 시 스펙 파일을 생성합니다.

**파일 경로**: `.opencode/weave/specs/{spec-name}.yaml`

```yaml
spec_name: "emotion-diary"
project_name: "감정 일기 앱"
created_at: "2026-02-06"
source_docs:
  - "docs/requirements.md"

requirements:
  - id: R1
    description: "사용자가 감정을 선택하고 일기를 저장할 수 있다"
    category: functional
    priority: must
    acceptance:
      - id: AC-R1-1
        scenario: "감정 선택 → 텍스트 입력 → 저장 → 목록에서 확인"
        type: e2e
      - id: AC-R1-2
        scenario: "빈 텍스트로 저장 시도 → 에러 메시지 표시"
        type: e2e

  - id: R2
    description: "저장된 일기 목록을 조회할 수 있다"
    category: functional
    priority: must
    acceptance:
      - id: AC-R2-1
        scenario: "저장된 일기 3개가 목록에 최신순으로 표시"
        type: e2e

  - id: R3
    description: "일기 목록이 2초 이내에 로딩된다"
    category: performance
    priority: should
    acceptance:
      - id: AC-R3-1
        scenario: "100개 일기 기준 로딩 시간 < 2000ms"
        type: performance

  - id: R4
    description: "오프라인에서도 저장된 일기를 조회할 수 있다"
    category: constraint
    priority: could
    acceptance:
      - id: AC-R4-1
        scenario: "네트워크 차단 후 기존 일기 목록 접근 가능"
        type: manual
```

**완료 메시지**:
```markdown
## 요구사항 명세가 생성되었습니다

📁 파일: `.opencode/weave/specs/emotion-diary.yaml`
📊 요구사항: 4개 (functional 2, performance 1, constraint 1)
🎯 검증 기준: 5개 (e2e 3, performance 1, manual 1)

### 다음 단계
이 명세를 기반으로 실행 계획을 세우려면:
`/weave-design emotion-diary`
```

---

## 완료 후 검증 (필수)

스펙 파일 생성 후, 반드시 다음을 확인합니다:

1. **스펙 파일 존재 확인**: `.opencode/weave/specs/{spec-name}.yaml` 존재 검증
2. **YAML 파싱 가능 확인**: 파일 내용이 유효한 YAML인지 검증
3. **검증 실패 시**: 유저에게 오류를 알리고 재생성 시도

---

## 핵심 원칙

1. **명세만 수립, 계획/구현 금지**: Phase 분할이나 코드 구현은 하지 않음
2. **검증 기준은 구체적으로**: 입력 → 기대결과 형태로 작성
3. **유형은 정직하게**: 자동화 불가능하면 `manual`. 억지로 끼워맞추지 않음
4. **스펙 이름은 kebab-case**: 이후 `/weave-design`의 플랜 이름으로 사용됨
5. **wont도 기록**: 명시적으로 제외한 것을 기록해야 나중에 "왜 안 했어?"를 방지