uc-new-project

새로운 프로젝트 UseCase 초안 만들기

개요

새 프로젝트의 UseCase 설계를 처음부터 시작한다. 8단계 워크플로우를 순서대로 진행하며, 각 단계 산출물을 개별 마크다운 파일에 기록한다. 사용자는 파일을 확인하고 피드백하며, 완료 후 하나의 초안 파일로 통합한다.

---

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

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

원칙

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

채팅 출력 패턴

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

확인 후 피드백 주세요. 수정할 부분이 있으면 말씀해주시고,
괜찮으면 다음 단계로 진행하겠습니다.

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

---

디렉토리 구조

[project-root]/
└── docs/
    └── usecase/
        ├── [project-name]-usecase-design.md    ← 메인 통합 문서 (uc-merge로 생성)
        ├── drafts/
        │   └── [feature-name]/                  ← 기능별 폴더
        │       ├── 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/

---

단계별 파일 공통 헤더

모든 단계 파일은 아래 헤더로 시작한다:

# Step N: [단계명]

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

사용자가 확인하면 상태를 ✅ 확인완료로 변경한다.

---

진행 규칙

1. 반드시 순서대로 진행한다. 단계를 건너뛰지 않는다.
2. 각 단계를 파일로 저장한 뒤 확인을 요청한다.
3. 사용자가 수정을 요청하면 해당 파일을 직접 편집하고 다시 확인을 요청한다.
4. 이전 단계의 파일을 다음 단계 작성 시 참조한다.
5. 8단계 완료 후 통합 파일을 생성한다.

---

시작 절차

1. 사용자에게 프로젝트 이름과 구현할 시스템/기능 개요를 질문한다.
2. 디렉토리를 생성한다:

   mkdir -p docs/usecase/drafts/[feature-name]
   mkdir -p docs/usecase/deprecated
   

3. 8단계 워크플로우를 시작한다.

---

Mermaid 다이어그램 규칙

모든 단계의 산출물에는 Mermaid 다이어그램을 필수로 포함한다. (단, 1단계는 다이어그램 없음) 다이어그램은 표/텍스트 산출물 아래에 배치하며, 마크다운 코드 블록(```mermaid)으로 작성한다.

공통 작성 규칙:

• 노드 텍스트에 한글을 사용한다.
• 복잡한 다이어그램은 하위 그래프(subgraph)로 그룹핑한다.
• 노드 ID는 영문으로, 표시 레이블은 한글로 작성한다. 예: UC01["UC-01: 주문 생성"]
• 다이어그램이 지나치게 커지면 UC 단위 또는 도메인 단위로 분할한다.

---

8단계 워크플로우

1단계: 유스케이스 작성

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

사용자에게 구현할 기능이나 시스템에 대해 질문하여 정보를 수집한 뒤, 유스케이스를 식별하고 파일에 기록한다.

파일 내용:

# Step 1: 유스케이스 목록

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

## 유스케이스 목록

| ID | 유스케이스명 | 주요 액터 | 목적 (한 줄 설명) |
|----|-------------|----------|------------------|
| UC-01 | ... | ... | ... |
| UC-02 | ... | ... | ... |

주의사항:

• 사용자의 설명이 모호하면, 구체적으로 질문하여 명확히 한다.
• 유스케이스는 "액터가 시스템을 통해 달성하는 목표" 단위로 식별한다.

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

→ 파일 저장 후 확인 요청. 확인되면 상태를 ✅로 변경하고 2단계로 진행.

---

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

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

1단계 파일(step1-usecases.md)을 읽고, 각 유스케이스에 대해 기본 흐름과 대안 흐름을 작성한다.

파일 내용:

# Step 2: 유스케이스 시나리오

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

## UC-01: [유스케이스명]

### 기본 흐름 (Main Flow)
1. 액터가 ...한다.
2. 시스템이 ...한다.
3. ...

### 대안 흐름 (Alternative Flow)
- **2a.** [조건] → 시스템이 ...한다.

### 시퀀스 다이어그램

(Mermaid sequenceDiagram)

---

## UC-02: [유스케이스명]
(동일 형식 반복)

주의사항:

• 각 단계는 "누가 무엇을 한다" 형식으로 주어를 명확히 한다.
• 기본 흐름은 성공 경로(Happy Path), 대안 흐름은 분기를 기술한다.

Mermaid: 시퀀스 다이어그램 — UC마다 하나씩, alt/else 블록으로 대안 흐름을 표현한다.

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

---

3단계: 변수 식별 (독립변수 · 상수 · 종속변수)

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

2단계 파일(step2-scenarios.md)을 읽고, 시나리오를 분석하여 변수를 세 범주로 분류한다.

각 범주의 정의:

• 독립변수 — 액터/시스템이 의도적으로 변경 가능한 요소 (입력값, 설정, 파라미터)
• 상수 — 시스템 운영 중 변경 불가한 요소 (규제, 정책, 계약 조건)
• 종속변수 — 독립변수의 변화에 따라 결정되는 결과 (출력, 상태 변화, 목표)

파일 내용:

# Step 3: 변수 식별

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

## UC-01: [유스케이스명]

### 독립변수 (변경 가능 — 조작할 수 있는 것)

| 변수 | 설명 | 변경 주체 | 시나리오 근거 |
|------|------|----------|-------------|
| ... | ... | ... | 기본 흐름 N단계 |

### 상수 (변경 불가 — 주어진 조건/제약)

| 상수 | 설명 | 근거/출처 |
|------|------|----------|
| ... | ... | ... |

### 종속변수 (달성 목표 — 결과로 보장해야 하는 것)

| 변수 | 설명 | 결정 요인 | 시나리오 근거 |
|------|------|----------|-------------|
| ... | ... | 독립변수X, 상수Y | 기본 흐름 N단계 |

### 변수 관계도

(Mermaid flowchart — 독립변수·상수 → 종속변수)

---

## UC-02: [유스케이스명]
(동일 형식 반복)

주의사항:

• 시나리오의 각 단계를 읽으면서 "바꿀 수 있는가? 바꿀 수 없는가? 결과인가?"를 판별한다.
• 종속변수의 결정 요인에는 관련 독립변수와 상수를 명시한다.
• 하나의 요소가 UC에 따라 다른 범주에 속할 수 있다.

Mermaid: 변수 관계도 — 독립변수·상수·종속변수를 subgraph로 구분, 실선(결정 관계)과 점선(제약 관계)으로 연결한다.

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

---

4단계: 도메인 모델 설계

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

시나리오에서 등장하는 핵심 개념(명사)을 추출하여 도메인 모델을 설계한다.

파일 내용:

# Step 4: 도메인 모델

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

## 엔티티 목록

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

## 관계

- Order → OrderItem: 1:N (하나의 주문은 여러 주문항목을 가진다)

## 도메인 규칙

- [규칙 1]: ...

## 클래스 다이어그램

(Mermaid classDiagram)

주의사항:

• 시나리오의 명사에서 엔티티 후보, 동사에서 행위/이벤트를 식별한다.
• 엔티티 간 관계(1:1, 1:N, N:M)를 명시한다.

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

---

5단계: 상태 모델

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

2단계 시나리오(step2-scenarios.md)와 4단계 도메인 모델(step4-domain-model.md)을 읽고, 이벤트 → 전이 → 상태 도출 순서로 개념 수준의 상태 모델을 확정한다.

핵심 흐름:

1. 시나리오의 동사에서 비즈니스 이벤트를 먼저 식별한다.
2. 각 이벤트가 어떤 엔티티에 어떤 변화(전이) 를 일으키는지 분석한다.
3. 전이를 모으면 상태가 자연스럽게 도출된다.
4. 도출된 상태들로 전체 생애주기를 확정하고, 불허 전이를 정의한다.

파일 내용:

# Step 5: 상태 모델

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

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

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

| 이벤트 | 설명 | 대상 엔티티 | UC 시나리오 근거 |
|--------|------|-----------|----------------|
| 주문 생성 | 사용자가 새 주문을 생성함 | Order | UC-01 기본흐름 3단계 |
| 주문 확인 | 관리자가 주문을 확인함 | Order | UC-02 기본흐름 2단계 |
| 결제 완료 | 결제 시스템이 결제 성공을 통보함 | Order | UC-02 기본흐름 5단계 |
| 주문 취소 | 사용자가 주문을 취소함 | Order | UC-03 기본흐름 1단계 |

## 2. 이벤트-전이 매핑

각 이벤트가 대상 엔티티에 일으키는 상태 전이를 도출한다.

| 이벤트 | 출발 상태 | 도착 상태 |
|--------|----------|----------|
| 주문 생성 | [초기] | CREATED |
| 주문 확인 | CREATED | CONFIRMED |
| 결제 완료 | CONFIRMED | PAID |
| 주문 취소 | CREATED | CANCELLED |

## 3. 엔티티별 상태 확정

전이를 모아서 각 엔티티의 전체 상태 목록을 확정한다.

### Order 상태 목록

| 상태 | 설명 | 진입 이벤트 |
|------|------|-----------|
| CREATED | 주문이 생성됨 | 주문 생성 |
| CONFIRMED | 주문이 확인됨 | 주문 확인 |
| PAID | 결제가 완료됨 | 결제 완료 |
| CANCELLED | 주문이 취소됨 | 주문 취소 |

### Order 전이 전체도

| 출발 상태 | 이벤트 | 도착 상태 | UC 시나리오 근거 |
|----------|--------|----------|----------------|
| [초기] | 주문 생성 | CREATED | UC-01 기본흐름 3단계 |
| CREATED | 주문 확인 | CONFIRMED | UC-02 기본흐름 2단계 |
| CONFIRMED | 결제 완료 | PAID | UC-02 기본흐름 5단계 |
| CREATED | 주문 취소 | CANCELLED | UC-03 기본흐름 1단계 |

## 4. 불허 전이

비즈니스 규칙에 의해 명시적으로 금지되는 전이를 정의한다.

| 출발 상태 | 도착 상태 | 불허 사유 |
|----------|----------|----------|
| PAID | CREATED | 결제 완료된 주문은 생성 상태로 되돌릴 수 없음 |
| CANCELLED | CONFIRMED | 취소된 주문은 확인할 수 없음 |

## 5. 상태 다이어그램

(Mermaid stateDiagram-v2)

---

## [다른 엔티티명] 상태 모델
(동일하게 1~5 순서로 반복)

주의사항:

• 이벤트가 출발점이다. 상태를 먼저 나열하지 않는다. 시나리오의 동사(행위)에서 이벤트를 식별하고, 이벤트가 일으키는 전이를 통해 상태를 도출한다.
• 이 모델은 개념 수준(비즈니스 이벤트, 비즈니스 상태)이다. 구현 수준(DB 컬럼, 이벤트 큐, 메시지 브로커)은 다루지 않는다.
• 하나의 이벤트가 여러 출발 상태에서 서로 다른 도착 상태를 만들 수 있다.
• 하나의 엔티티가 여러 UC에 걸쳐 전이되는 경우, 모든 관련 UC를 근거에 포함한다.
• 도출된 상태에서 "이 전이는 비즈니스적으로 있어서는 안 된다"를 불허 전이로 명시한다.

Mermaid: 상태 다이어그램 — stateDiagram-v2로 작성. 상태명은 한글, 전이 레이블에 트리거 이벤트를 표기한다.

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

---

6단계: 시스템 경계 분리

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

시스템 경계를 명확히 하여 외부 요청과 내부 로직을 구분한다.

파일 내용:

# Step 6: 시스템 경계 분리

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

## 외부 액터

| 액터 | 유형 | 상호작용 방식 |
|------|------|-------------|
| 사용자 | 사람 | Web UI |
| 결제 시스템 | 외부 시스템 | API 연동 |

## 외부 유스케이스 (사용자/외부 시스템이 직접 호출)

| ID | 유스케이스명 | 호출 액터 |
|----|-------------|----------|
| UC-01 | ... | 사용자 |

## 내부 유스케이스 (시스템 내부에서만 실행)

| ID | 유스케이스명 | 트리거 |
|----|-------------|--------|
| UC-INT-01 | ... | UC-01의 3단계에서 호출 |

## 시스템 경계 다이어그램

(Mermaid flowchart TB — 외부 액터, 외부/내부 UC를 subgraph로 분리)

## 유스케이스 다이어그램 (UML)

(Mermaid flowchart LR — 시스템 경계를 subgraph로 감싸고 그 안에 UC 배치,
 액터는 경계 밖에 배치. include/extend 관계 표현.)

Mermaid: 유스케이스 다이어그램 (UML 스타일) — subgraph System["시스템명"]으로 시스템 경계를 표현하고, 그 안에 UC 노드를 배치한다. 액터 노드는 subgraph 바깥에 두고, 실선으로 UC와 연결한다. include 관계는 점선 -.->|include|, extend는 점선 -.->|extend|로 표현한다.

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

---

7단계: 예외 정리

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

각 시나리오의 각 단계 전후로 발생할 수 있는 예외 상황을 정리한다.

파일 내용:

# Step 7: 예외 정리

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

## UC-01: [유스케이스명]

| 시나리오 단계 | 시점 | 예외 상황 | 시스템 대응 |
|-------------|------|----------|-----------|
| 2. 시스템이 검증한다 | 전 | 입력 데이터가 누락됨 | 400 에러, 필수 항목 안내 |
| 2. 시스템이 검증한다 | 후 | DB 저장 실패 | 재시도 후 500 에러 |

---

## UC-02: [유스케이스명]
(동일 형식 반복)

주의사항:

• "전"은 해당 단계 실행 전, "후"는 실행 중/직후에 발생하는 예외이다.
• 기술적 예외와 비즈니스 예외를 모두 고려한다.
• 5단계 상태 모델의 불허 전이도 예외 상황의 근거가 된다.

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

---

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

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

# Step 8: 사전조건 / 사후조건

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

## UC-01: [유스케이스명]

**사전조건 (Precondition):**
- 사용자가 로그인되어 있어야 한다.

**사후조건 (Postcondition) - 성공 시:**
- 주문이 생성되고 상태가 "대기중"이다.

**사후조건 (Postcondition) - 실패 시:**
- 시스템 상태가 변경되지 않는다 (롤백).

---

## UC-02: [유스케이스명]
(동일 형식 반복)

주의사항:

• 사전조건에 5단계 상태 모델의 "출발 상태"를 반영한다 (예: "주문 상태가 CREATED여야 한다").
• 사후조건에 5단계 상태 모델의 "도착 상태"를 반영한다 (예: "주문 상태가 CONFIRMED으로 변경된다").

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

---

최종 통합

8단계 파일이 모두 ✅ 확인완료 상태가 되면, 하나의 초안 파일로 통합한다.

통합 방법:

1. step1 ~ step8 파일을 순서대로 읽는다.
2. 각 파일의 헤더(Step N, 상태 등)를 제거하고 본문만 추출한다.
3. 초안 문서 구조에 맞게 재구성한다.

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

# [기능명] UseCase 초안

> 프로젝트: [project-name]
> 작성일: [날짜]
> 상태: 초안 (draft)

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

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

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

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

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

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

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

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

통합 완료 후 사용자에게 파일 경로를 안내하고 다음 단계를 제안한다:

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