---
description: 요구사항 분석 및 Phase 계획 수립 (멀티 플랜)
---

# /weave-design - 요구사항 분석 및 계획 수립

## 개요

유저의 요구사항 문서를 분석하고, Phase별 실행 계획을 수립합니다.
**멀티 플랜**: 하나의 프로젝트에서 여러 플랜을 동시에 관리할 수 있습니다.

큰 계획(phase/시간 규모가 큰 경우)은 자동으로 여러 shard plan 파일로 분할되며,
각 shard는 독립적으로 세부 설계(task/checklist)를 갖습니다.

**입력 방식**: 
- 정확한 경로: `docs/`, `wiki/spec.md`
- 자연어 힌트: `기획 폴더`, `README`, `아까 만든 문서`

> AI가 자동으로 프로젝트를 탐색하여 관련 문서를 찾습니다.

**Maskweaver 통합**:
- **Memory**: 과거 유사 프로젝트 검색하여 계획 참조
- **Masks**: 아키텍처 분석에 Martin Fowler 마스크 자동 선택

---

## 사전 조건

`/weave-init`이 실행되어 있어야 합니다.
실행되지 않았다면 자동으로 init을 먼저 수행합니다:
1. `.opencode/weave/state.yaml` 존재 여부 확인
2. 없으면 → `/weave-init` 절차 자동 실행 후 계속 진행

---

## Expert Summoning Strategy (Critical)

### Principle: Summon Named Experts for Quality

You are the **Mask Weaver**. Your power lies in summoning the right expert for the right task. Don't try to do everything yourself — **delegate to specialists**.

---

### 1. Architecture & Design Decisions → Expert Council

For **critical architectural decisions**, summon multiple experts for consultation:

```
Complex Architecture Decision:

Task(dummy-human):
  Mask: Martin Fowler (Enterprise Architecture)
  Task: "Analyze these requirements and propose a layer structure,
         key components, and design patterns to use."

Task(dummy-human):
  Mask: Linus Torvalds (System Performance)
  Task: "Review the proposed architecture for performance bottlenecks
         and scalability concerns."

→ Mask Weaver synthesizes both perspectives into final decision.
```

**Why This Works**:
- Each expert focuses on their domain of excellence
- You maintain strategic oversight without context pollution
- Multiple perspectives prevent blind spots

---

### 2. Technology Choices → Squad Parallel Analysis

For **important technology selections** (framework, database, etc.):

```
Mask Weaver:
1. squad start → "Optimal Tech Stack Decision"
2. squad squad (arch-squad) → "Martin Fowler: Maintainability analysis"
3. squad squad (perf-squad) → "Linus Torvalds: Performance analysis"
4. squad squad (dx-squad) → "Dan Abramov: Developer experience analysis"

→ Collect results → Weigh trade-offs → Final decision
```

---

### 3. When to Summon vs Handle Directly

| Situation | Action |
|-----------|--------|
| Reading & summarizing requirements | Handle directly |
| Obvious tech stack (project already decided) | Handle directly |
| Architecture trade-offs with long-term impact | **Summon Martin Fowler** |
| Performance-critical design | **Summon Linus Torvalds** |
| Multiple valid approaches, need comparison | **Squad council** |

> **Rule of Thumb**: If the decision will be hard to reverse later, summon experts. If it's tactical, handle it yourself.

---

## 실행 흐름

```
0. INIT CHECK (weave 초기화 확인)
   ↓
1. RESOLVE (입력 해석 → 실제 경로 찾기)
   ↓
2. INTAKE (문서 분석)
   ↓
3. CLARIFY (불명확한 부분 질문)
   ↓
4. PLAN (계획서 제시 + 플랜 이름 제안)
   ↓
5. FEEDBACK (유저 피드백 → 수정)
   ↓
6. APPROVE (승인 시 플랜 파일 생성 + 활성 플랜 설정)
```

---

## 단계별 상세

### Step 0: INIT CHECK

```
.opencode/weave/state.yaml 존재?
  ├─ YES → 계속 진행
  └─ NO → /weave-init 자동 실행 후 계속
```

### Step 1: RESOLVE (경로 해석)

**입력 유형별 처리**:

| 입력 타입 | 예시 | 처리 방법 |
|----------|------|----------|
| 정확한 경로 | `docs/spec.md` | 그대로 사용 |
| 디렉토리 힌트 | `기획 폴더`, `스펙 폴더` | docs/, spec/, design/, wiki/ 등 탐색 |
| 파일 타입 힌트 | `README`, `기획서` | README.md, SPEC.md, *.spec.md 등 검색 |
| 시간 힌트 | `아까 만든`, `어제 정리한` | 최근 수정된 .md 파일 탐색 |
| 내용 힌트 | `요구사항`, `기능 목록` | 파일 내용 검색 (grep) |

**탐색 순서**:
1. 프로젝트 루트의 일반적 문서 위치 확인
   - `docs/`, `doc/`, `wiki/`, `spec/`, `design/`
2. 키워드 매칭으로 후보 파일 탐색
3. 최근 수정 시간 고려 (시간 힌트가 있는 경우)
4. 후보가 여러 개면 유저에게 확인

---

### Step 2: INTAKE

**수행 작업**:
1. 해석된 경로의 모든 문서 읽기
2. 핵심 기능 추출
3. 기술적 요구사항 식별
4. 과거 유사 프로젝트 검색 (Memory 시스템)

---

### Step 3: CLARIFY

불명확한 부분을 유저에게 질문합니다.

---

### Step 4: PLAN

**Phase 크기 기준**:
- 한 Phase = 반나절 ~ 하루 작업량
- 끝나면 유저가 뭔가 "해볼 수 있어야" 함

**플랜 이름 제안**:
계획서와 함께 **플랜 이름(kebab-case)**을 제안합니다:
```markdown
## 📋 실행 계획서

**플랜 이름**: `emotion-diary` (변경 가능)

### 비전
[전체 목표 요약]

### Phase 계획
| Phase | 이름 | 완료 조건 | 예상 시간 |
|-------|------|----------|----------|
| P1 | [...] | [...] | 2-3시간 |
| P2 | [...] | [...] | 2-3시간 |

---
이 계획이 괜찮으세요? 플랜 이름을 바꾸고 싶다면 말씀해주세요.
```

---

### Step 5: APPROVE

**플랜 파일 생성**: `.opencode/weave/plans/{plan-name}.yaml`

> ⚠️ **YAML 작성 규칙 (반드시 준수)**
>
> `done_when`, `vision` 등 **긴 문자열 값**은 반드시 아래 규칙을 따릅니다:
>
> | 상황 | 사용할 표기법 | 예시 |
> |------|-------------|------|
> | 한 줄로 끝나는 짧은 값 | double-quote (`"`) | `done_when: "로그인 기능 동작"` |
> | 여러 줄 또는 긴 값 | block scalar (`\|`) | 아래 예시 참고 |
> | ❌ 절대 금지 | 여러 줄에 걸친 double-quote | `done_when: "1단계...\n2단계..."` |
>
> ```yaml
> # ✅ 올바른 예시 - 짧은 값
> done_when: "유저가 감정을 선택할 수 있다"
>
> # ✅ 올바른 예시 - 긴 값 (block scalar)
> done_when: |
>   1. 유저가 감정을 선택할 수 있다
>   2. 선택한 감정이 저장된다
>   3. 저장 확인 메시지가 표시된다
>
> # ❌ 잘못된 예시 - 닫는 따옴표가 다른 줄에 있음 (YAML 파싱 실패!)
> done_when: "1. 유저가 감정을 선택할 수 있다
>   2. 선택한 감정이 저장된다
>   3. 저장 확인 메시지가 표시된다"
> ```
>
> **핵심 원칙**: `"` 로 시작했으면 **같은 줄에서** `"` 로 닫아야 합니다. 줄바꿈이 필요하면 `|` 를 사용하세요.

```yaml
plan_name: "emotion-diary"
project_name: "감정 일기 앱"
created_at: "2026-02-06"
status: "active"     # active | paused | completed | archived

vision: |
  [전체 비전]

architecture:
  frontend: "[...]"
  backend: "[...]"
  database: "[...]"

phases:
  - id: "P1"
    name: "[Phase 이름]"
    status: "pending"    # pending | in_progress | completed
    done_when: "[짧으면 한 줄 double-quote, 길면 | 블록 스칼라 사용]"
    started_at: null
    completed_at: null
    masks_used: []
    checklist:
      - "[체크 항목 1]"
      - "[체크 항목 2]"
    tasks: []
```

**state.yaml 업데이트**:

```yaml
active_plan: "emotion-diary"
```

**완료 메시지**:
```markdown
✅ 플랜이 승인되었습니다!

📁 생성된 파일: `.opencode/weave/plans/emotion-diary.yaml`
📌 활성 플랜으로 설정됨

### 다음 단계
Phase 1을 시작하려면:
`/weave-craft P1`
```

---

## 기존 플랜이 있는 경우

활성 플랜이 이미 존재하면:
```markdown
ℹ️ 현재 활성 플랜: `todo-app` (P2 진행 중)

새 플랜을 추가하면 기존 플랜은 유지되고, 새 플랜이 활성 플랜이 됩니다.
기존 플랜으로 돌아가려면: `/weave-switch todo-app`

계속 진행할까요?
```

---

## 주의사항

1. **Phase는 작게**: 큰 Phase는 분할
2. **복잡한 분석은 위임**: Task(dummy-human)으로 전문가 위임
3. **테스트 가능해야**: 각 Phase 끝에 유저가 확인할 수 있어야
4. **아키텍처는 유연하게**: "변경 가능"을 명시
5. **플랜 이름은 kebab-case**: 파일명이 되므로 영문 소문자, 하이픈만 사용