uc-add-feature

기존 프로젝트에 새 기능 UseCase 초안 만들기

개요

이미 존재하는 프로젝트에 새로운 기능의 UseCase를 추가한다. 기존 문서를 먼저 읽고 분석한 뒤, 8단계 워크플로우를 파일 기반으로 진행한다. 기존 내용과의 일관성과 ID 연속성을 보장하는 것이 핵심이다.

---

파일 기반 출력 규칙 (핵심)

이 스킬은 클로드 코드 환경에서 사용한다. 모든 산출물은 채팅이 아닌 파일에 기록한다.

원칙

1. 채팅에는 안내만, 내용은 파일에. 산출물 본문을 채팅에 출력하지 않는다.
2. 단계별 개별 파일. 각 단계의 산출물은 별도 .md 파일로 저장한다.
3. 파일로 확인 요청. 단계 완료 시 "파일을 확인해주세요"로 안내한다.
4. 파일을 직접 편집. 수정 요청이 오면 해당 파일을 편집한다.
5. 최종 통합. 8단계 완료 후 단계별 파일을 하나의 초안으로 합친다.

채팅 출력 패턴

# 단계 완료 시 (예시)
1단계 유스케이스 목록을 작성했습니다.
→ docs/usecase/drafts/[feature]/step1-usecases.md

기존 UC 범위(UC-01~UC-05)에 이어 UC-06부터 부여했습니다.
확인 후 피드백 주세요.

절대 하지 않을 것: 표, 다이어그램, 시나리오 본문을 채팅에 직접 출력하는 것.

---

디렉토리 구조

[project-root]/
└── docs/
    └── usecase/
        ├── [project-name]-usecase-design.md    ← 메인 통합 문서 (있으면 참조)
        ├── drafts/
        │   ├── [기존-feature]/                  ← 기존 초안들 (참조용)
        │   └── [새-feature]/                    ← 이 스킬이 생성하는 폴더
        │       ├── step0-existing-analysis.md   ← 기존 문서 분석 결과
        │       ├── step1-usecases.md
        │       ├── step2-scenarios.md
        │       ├── step3-variables.md
        │       ├── step4-domain-model.md
        │       ├── step5-state-model.md
        │       ├── step6-system-boundary.md
        │       ├── step7-exceptions.md
        │       ├── step8-conditions.md
        │       └── [feature-name]-draft.md
        └── deprecated/

---

시작 절차 (기존 문서 분석)

1. 프로젝트 디렉토리 확인

ls docs/usecase/
ls docs/usecase/drafts/

docs/usecase/ 디렉토리가 없으면 uc-new-project 사용을 안내한다.

2. 기존 문서 분석 → step0 파일로 저장

메인 문서가 있으면 메인 문서를, 없으면 drafts/ 내 초안 파일들을 읽고 분석 결과를 파일에 기록한다.

파일: docs/usecase/drafts/[새-feature]/step0-existing-analysis.md

# Step 0: 기존 문서 분석

> 프로젝트: [project-name]
> 분석 대상: [참조한 파일명]
> 분석일: [날짜]

## 기존 UC ID 범위

| 구분 | ID 범위 |
|------|---------|
| 외부 UC | UC-01 ~ UC-05 |
| 내부 UC | UC-INT-01 ~ UC-INT-03 |

## 기존 액터

| 액터 | 유형 |
|------|------|
| 사용자 | 사람 |
| 결제 시스템 | 외부 시스템 |

## 기존 엔티티

| 엔티티 | 주요 속성 |
|--------|----------|
| Order | orderId, status, createdAt |

## 기존 도메인 규칙

- [규칙 목록]

## 기존 상태 모델

| 엔티티 | 상태 목록 | 전이 수 |
|--------|----------|--------|
| Order  | CREATED, CONFIRMED, PAID, SHIPPED | 4개 |

## 신규 기능 ID 시작점

- 외부 UC: UC-06부터
- 내부 UC: UC-INT-04부터

→ 파일 저장 후 확인 요청. 사용자에게 새 기능에 대한 설명을 요청한다.

---

진행 규칙

1. 기존 문서와 동일한 8단계를 따른다 (uc-new-project와 동일).
2. ID는 기존 범위 다음부터 부여한다. (step0에서 파악한 시작점 사용)
3. 기존 액터를 재사용한다. 새 액터가 필요한 경우에만 추가한다.
4. 도메인 모델은 기존 모델을 확장한다. 기존 엔티티와 충돌하지 않도록 한다.
5. 상태 모델은 기존 모델을 확장한다. 기존 상태/전이를 유지하면서 신규 상태/전이를 추가한다.
6. 각 단계를 파일에 기록하고 확인을 받는다.

---

Mermaid 다이어그램 규칙

uc-new-project와 동일한 Mermaid 규칙을 따른다.

기존 프로젝트 확장 시 추가 규칙:

• 기존 문서의 노드 ID를 재사용한다.
• 신규 요소는 기존 다이어그램에 추가하는 형태로 작성한다.
• 기존 요소와의 연결 관계를 반드시 표현한다.

---

8단계 워크플로우

1단계: 유스케이스 작성

파일: docs/usecase/drafts/[feature]/step1-usecases.md

step0의 기존 분석을 참조하여 신규 유스케이스를 식별한다.

파일 내용에 기존 참조 정보를 포함한다:

# Step 1: 유스케이스 목록

> 프로젝트: [project-name]
> 기능: [feature-name]
> 작성일: [날짜]
> 상태: ✏️ 작성중

## 기존 유스케이스 참조
- 기존 UC 범위: UC-01 ~ UC-[N]
- 관련 기존 UC: UC-03 (주문 생성)과 연계

## 신규 유스케이스 목록

| ID | 유스케이스명 | 주요 액터 | 목적 (한 줄 설명) |
|----|-------------|----------|------------------|
| UC-[N+1] | ... | ... | ... |

추가 주의사항:

• 기존 유스케이스와 중복되지 않는지 확인한다.
• 기존 유스케이스와 의존 관계가 있으면 명시한다.

참고: 유스케이스 다이어그램(UML)은 시스템 경계가 정의되는 6단계에서 작성한다. 이 단계에서는 유스케이스 목록 테이블만 작성한다.

→ 파일 저장 후 확인 요청. 확인되면 2단계로 진행.

---

2단계: 유스케이스 시나리오 작성

파일: docs/usecase/drafts/[feature]/step2-scenarios.md

uc-new-project의 2단계와 동일한 형식. 기존 UC를 참조하는 경우 "UC-03의 4단계 이후 시작" 등으로 명시한다. 시퀀스 다이어그램에서 기존 UC 참조는 ref 블록으로 요약한다.

→ 파일 저장 후 확인 요청.

---

3단계: 변수 식별

파일: docs/usecase/drafts/[feature]/step3-variables.md

uc-new-project의 3단계와 동일한 형식.

추가 포함 내용:

## 기존 변수 참조
- UC-03의 종속변수 "주문 상태" → 이 UC에서 상수로 참조

기존 UC에서 상수로 분류된 요소가 새 기능에서 독립변수가 되는 등의 차이를 명시한다.

→ 파일 저장 후 확인 요청.

---

4단계: 도메인 모델 설계 (확장)

파일: docs/usecase/drafts/[feature]/step4-domain-model.md

기존 도메인 모델을 기반으로 확장한다.

# Step 4: 도메인 모델 (확장)

> ...

## 기존 엔티티 (변경 없음)
| 엔티티 | 비고 |
|--------|------|
| Order  | 기존 유지 |

## 기존 엔티티 (속성 추가)
| 엔티티 | 추가 속성 | 사유 |
|--------|----------|------|
| Order  | refundStatus | 환불 기능 추가로 필요 |

## 신규 엔티티
| 엔티티 | 설명 | 주요 속성 |
|--------|------|----------|
| Refund | 환불 | refundId, reason, amount |

## 신규 관계
- Order → Refund: 1:1

## 신규 도메인 규칙
- [규칙]: ...

## 클래스 다이어그램
(기존 엔티티를 포함한 통합 다이어그램)

→ 파일 저장 후 확인 요청.

---

5단계: 상태 모델 (확장)

파일: docs/usecase/drafts/[feature]/step5-state-model.md

2단계 시나리오와 4단계 도메인 모델을 읽고, 기존 상태 모델을 참조하여 이벤트 → 전이 → 상태 도출 순서로 확장한다.

# Step 5: 상태 모델 (확장)

> ...

## 기존 상태 모델 참조
- Order 엔티티: 기존 상태 [CREATED, CONFIRMED, PAID, SHIPPED]
- 기존 이벤트: [주문 생성, 주문 확인, 결제 완료, 배송 시작]

## 1. 신규 비즈니스 이벤트 식별

이 기능의 시나리오에서 엔티티의 상태를 변화시키는 행위(동사)를 추출한다.

| 이벤트 | 설명 | 대상 엔티티 | UC 시나리오 근거 |
|--------|------|-----------|----------------|
| 환불 요청 | 사용자가 환불을 요청함 | Order, Refund | UC-06 기본흐름 2단계 |
| 환불 승인 | 관리자가 환불을 승인함 | Order, Refund | UC-07 기본흐름 3단계 |

## 2. 이벤트-전이 매핑 (기존 엔티티 확장)

### Order — 신규 전이

| 이벤트 | 출발 상태 | 도착 상태 | 비고 |
|--------|----------|----------|------|
| 환불 요청 | PAID (기존) | REFUND_REQUESTED (신규) | 기존 상태에서 분기 |
| 환불 승인 | REFUND_REQUESTED (신규) | REFUNDED (신규) | |

## 3. 신규 엔티티 상태 모델

### Refund — 이벤트-전이 매핑

| 이벤트 | 출발 상태 | 도착 상태 |
|--------|----------|----------|
| 환불 요청 | [초기] | REQUESTED |
| 환불 승인 | REQUESTED | APPROVED |

### Refund — 상태 확정

| 상태 | 설명 | 진입 이벤트 |
|------|------|-----------|
| REQUESTED | 환불이 요청됨 | 환불 요청 |
| APPROVED | 환불이 승인됨 | 환불 승인 |

## 4. 불허 전이

| 엔티티 | 출발 상태 | 도착 상태 | 불허 사유 |
|--------|----------|----------|----------|
| Order | REFUNDED | PAID | 환불 완료된 주문은 결제 상태로 되돌릴 수 없음 |

## 5. 상태 다이어그램
(Mermaid stateDiagram-v2 — 기존 상태는 연한 스타일, 신규 상태는 강조 스타일)

주의사항:

• 이벤트가 출발점이다. 신규 시나리오의 동사에서 이벤트를 식별하고, 이벤트가 일으키는 전이를 통해 신규 상태를 도출한다.
• 기존 상태 모델의 상태와 이벤트를 먼저 참조하고, 신규 이벤트/전이/상태만 추가한다.
• 신규 이벤트가 기존 상태를 출발점으로 삼을 수 있다.
• Mermaid 다이어그램에서 기존 상태는 연한 스타일로, 신규 상태는 강조 스타일로 구분한다.

→ 파일 저장 후 확인 요청.

---

6단계: 시스템 경계 분리

파일: docs/usecase/drafts/[feature]/step6-system-boundary.md

기존/신규를 구분하여 기록한다. 유스케이스 다이어그램(UML)을 이 단계에서 작성한다. 기존 UC 노드를 연한 스타일로 포함시켜 신규 UC와의 관계를 보여준다.

→ 파일 저장 후 확인 요청.

---

7단계: 예외 정리

파일: docs/usecase/drafts/[feature]/step7-exceptions.md

신규 유스케이스에 대해서만 작성한다. 5단계 상태 모델의 불허 전이도 예외 상황의 근거가 된다.

→ 파일 저장 후 확인 요청.

---

8단계: 사전조건/사후조건 작성

파일: docs/usecase/drafts/[feature]/step8-conditions.md

신규 유스케이스에 대해서만 작성한다. 사전조건에 기존 UC의 사후조건이 필요한 경우 명시한다. 5단계 상태 모델의 출발/도착 상태를 사전/사후조건에 반영한다.

→ 파일 저장 후 확인 요청.

---

최종 통합

8단계 파일이 모두 확인되면 초안 파일로 통합한다.

파일: docs/usecase/drafts/[feature]/[feature-name]-draft.md

# [기능명] UseCase 초안

> 프로젝트: [project-name]
> 작성일: [날짜]
> 상태: 초안 (draft)
> 기존 문서 기반: [참조한 파일명]

## 기존 문서 참조 요약
- 기존 UC 범위: UC-01 ~ UC-[N]
- 기존 엔티티: [목록]
- 기존 상태 모델: [엔티티별 상태 수 요약]
- 이번 초안 UC 범위: UC-[N+1] ~ UC-[N+K]

## 1. 유스케이스 목록
(step1 내용)

## 2. 유스케이스 시나리오
(step2 내용)

## 3. 변수 식별
(step3 내용)

## 4. 도메인 모델 (확장)
(step4 내용)

## 5. 상태 모델 (확장)
(step5 내용)

## 6. 시스템 경계 분리 (확장)
(step6 내용)

## 7. 예외 정리
(step7 내용)

## 8. 사전조건 / 사후조건
(step8 내용)

통합 완료 후 다음 단계를 안내한다:

• uc-review로 초안 리뷰
• uc-merge로 메인 문서에 병합