uc-merge

메인 문서에 UseCase 병합하기

개요

하나 이상의 UseCase 초안(draft) 파일을 메인 통합 설계서에 병합한다. 메인 문서가 없으면 새로 생성하고, 있으면 기존 내용에 초안을 합산한다. ID 정리, 도메인 모델 통합, 상태 모델 통합, 중복 제거, Mermaid 다이어그램 재생성을 수행한다.

---

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

이 스킬은 클로드 코드 환경에서 사용한다. 병합 결과는 파일에 기록한다.

원칙

1. 메인 문서를 파일로 생성/갱신한다.
2. 병합 리포트를 별도 파일로 저장한다.
3. 채팅에는 요약만 안내한다.

채팅 출력 패턴

# 병합 완료 시 (예시)
병합을 완료했습니다.

메인 문서: docs/usecase/[project]-usecase-design.md
병합 리포트: docs/usecase/merge-report-[날짜].md

추가된 UC: UC-06 ~ UC-08 (3건)
추가된 엔티티: Refund, Payment (2건)
추가된 상태: Order에 REFUND_REQUESTED, REFUNDED (2건)

---

디렉토리 구조

[project-root]/
└── docs/
    └── usecase/
        ├── [project-name]-usecase-design.md    ← 메인 문서 (이 스킬이 생성/갱신)
        ├── merge-report-[날짜].md               ← 병합 리포트
        ├── drafts/
        │   └── [feature]/
        │       └── [feature]-draft.md           ← 병합 대상 초안
        └── deprecated/

---

시작 절차

1. 파일 확인

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

확인 사항:

• 메인 문서 존재 여부
• 병합 대상 초안 파일 목록

2. 병합 대상 선택

사용자에게 병합할 초안 파일을 확인한다:

• 전체 병합: drafts/ 내의 모든 초안을 병합
• 선택 병합: 특정 초안만 선택

3. 리뷰 권고

아직 리뷰하지 않은 초안이 있으면 uc-review를 권장한다.

---

병합 시나리오

시나리오 A: 메인 문서가 없는 경우 (최초 병합)

1. 초안 파일을 모두 읽는다.
2. UC ID를 UC-01부터 순서대로 재정렬한다.
3. 변수 식별을 하나로 통합 (중복 제거, 시나리오 근거 갱신).
4. 도메인 모델을 하나로 통합 (중복 엔티티 병합).
5. 상태 모델을 하나로 통합 (같은 엔티티의 상태 목록 합산, 전이 중복 제거, UC 참조 갱신).
6. 외부/내부 유스케이스 목록을 통합한다.
7. 예외, 사전/사후조건을 재정렬된 UC ID로 갱신한다.
8. Mermaid 다이어그램을 재생성한다.
9. 메인 문서를 생성한다.

시나리오 B: 메인 문서가 있는 경우 (추가 병합)

1. 메인 문서와 초안 파일을 모두 읽는다.
2. 기존 UC ID 범위를 확인한다.
3. 초안의 UC ID를 기존 범위 다음부터 재부여한다.
4. 변수 식별을 통합한다:
   • 초안의 변수를 재정렬된 UC ID로 갱신
   • 동일 변수가 다른 범주로 분류된 경우, UC 맥락이 다르면 각각 유지
   • 결정 요인의 UC ID 참조를 갱신
5. 도메인 모델을 통합한다:
   • 기존 엔티티 유지, 신규 엔티티 추가
   • 속성 추가 반영, 중복 관계 제거
   • 도메인 규칙 병합 (모순 검사)
6. 상태 모델을 통합한다:
   • 기존 엔티티의 상태 모델에 신규 상태/전이 추가
   • 신규 엔티티의 상태 모델 추가
   • 전이 트리거의 UC ID 참조를 갱신
7. 외부/내부 유스케이스 목록에 추가한다.
8. 예외, 사전/사후조건을 추가한다.
9. Mermaid 다이어그램을 재생성한다.
10. 메인 문서를 갱신한다.

---

통합 시 주의사항

ID 재정렬

• 병합 시 메인 문서 기준으로 ID를 재부여한다.
• ID 변경 시 문서 전체에서 참조하는 모든 곳을 갱신한다.

변수 식별 통합

• UC별로 독립변수, 상수, 종속변수를 그대로 유지한다.
• 같은 변수가 다른 UC에서 다른 범주로 분류된 경우 각각 유지한다.
• "시나리오 근거"와 "결정 요인"의 UC ID 참조를 갱신한다.

도메인 모델 통합

• 같은 이름의 엔티티가 양쪽에 있으면 속성을 합산한다.
• 관계가 중복되면 하나만 유지한다.
• 도메인 규칙이 모순되면 사용자에게 확인을 요청한다.

상태 모델 통합

• 같은 엔티티에 대한 비즈니스 이벤트를 합산하고, 이벤트-전이 매핑을 통합한다.
• 동일 이벤트/전이가 중복되면 하나만 유지한다.
• 이벤트와 전이의 UC 시나리오 근거를 재정렬된 UC ID로 갱신한다.
• 통합된 전이에서 상태를 재도출하여 상태 확정 테이블을 갱신한다.
• 신규 전이가 기존 불허 전이와 충돌하면 사용자에게 확인을 요청한다.

용어 통일

• 초안의 용어가 메인 문서와 다르면 메인 문서의 용어로 통일한다.

Mermaid 다이어그램 통합

초안의 것을 그대로 붙여넣지 않고 통합 내용 기반으로 재생성한다:

• 2단계: UC별 개별 시퀀스 다이어그램 (ID/참여자 갱신)
• 3단계: UC별 변수 관계도 + UC 간 의존 관계 통합도
• 4단계: 통합 도메인 모델 클래스 다이어그램
• 5단계: 엔티티별 통합 상태 다이어그램 (stateDiagram-v2)
• 6단계: 시스템 경계 포함 통합 UML 유스케이스 다이어그램 + 시스템 경계 다이어그램

---

메인 문서 형식

파일: docs/usecase/[project-name]-usecase-design.md

# [프로젝트명] 유스케이스 설계서

> 최종 갱신일: [날짜]
> 포함된 기능: [기능A], [기능B], ...
> UC 범위: UC-01 ~ UC-[N]

## 목차

1. [유스케이스 목록](#1-유스케이스-목록)
2. [유스케이스 시나리오](#2-유스케이스-시나리오)
3. [변수 식별](#3-변수-식별)
4. [도메인 모델](#4-도메인-모델)
5. [상태 모델](#5-상태-모델)
6. [시스템 경계 분리](#6-시스템-경계-분리)
7. [예외 정리](#7-예외-정리)
8. [사전조건 / 사후조건](#8-사전조건--사후조건)

---

## 1. 유스케이스 목록
(통합 표)

## 2. 유스케이스 시나리오
(모든 UC 시나리오 + UC별 시퀀스 다이어그램)

## 3. 변수 식별
(모든 UC 변수 + UC별 관계도 + UC 간 의존 관계 통합도)

## 4. 도메인 모델
(통합 엔티티, 관계, 규칙 + 통합 클래스 다이어그램)

## 5. 상태 모델
(통합 상태 모델 + 엔티티별 상태 다이어그램)

## 6. 시스템 경계 분리
(통합 액터, 외부/내부 UC + UML 유스케이스 다이어그램 + 시스템 경계 다이어그램)

## 7. 예외 정리
(모든 UC 예외)

## 8. 사전조건 / 사후조건
(모든 UC 사전/사후조건)

---

병합 리포트 파일

파일: docs/usecase/merge-report-[날짜].md

# 병합 결과 리포트

> 병합일: [날짜]
> 메인 문서: docs/usecase/[project-name]-usecase-design.md

## 병합 대상

| 초안 파일 | 기능명 |
|----------|--------|
| drafts/[feature-A]/[feature-A]-draft.md | 기능A |

## 변경 내역

### UC 추가
| 신규 ID | (초안 ID) | 유스케이스명 |
|---------|----------|-------------|
| UC-06 | (UC-06) | 환불 처리 |

### 엔티티 추가/변경
| 엔티티 | 변경 유형 | 내용 |
|--------|----------|------|
| Refund | 신규 | 환불 엔티티 |
| Order | 속성 추가 | refundStatus |

### 상태 모델 추가/변경
| 엔티티 | 변경 유형 | 내용 |
|--------|----------|------|
| Order | 이벤트 추가 | 환불 요청, 환불 승인 |
| Order | 전이 추가 | PAID →(환불 요청)→ REFUND_REQUESTED |
| Order | 상태 도출 | REFUND_REQUESTED, REFUNDED |
| Refund | 신규 | 전체 상태 모델 (이벤트 → 전이 → 상태) |

### ID 재정렬 (있는 경우)
| 초안 ID | → 메인 ID |
|---------|----------|
| UC-07 | → UC-06 |

### 용어 통일 (있는 경우)
| 초안 용어 | → 메인 용어 |
|----------|------------|
| 고객 | → 사용자 |

### 도메인 규칙 충돌 (있는 경우)
(상세 내역)

### 상태 모델 충돌 (있는 경우)
(신규 전이가 기존 불허 전이와 충돌하는 경우 상세 내역)

### Mermaid 다이어그램 재생성
- 시퀀스 다이어그램 (N개)
- 변수 관계도 (N개)
- 통합 클래스/ER 다이어그램
- 통합 상태 다이어그램 (N개)
- 통합 UML 유스케이스 다이어그램 (시스템 경계 포함)
- 통합 시스템 경계 다이어그램

---

병합 후 처리

초안 파일 상태 갱신

병합 완료된 초안의 메타 정보를 변경한다:

> 상태: 병합 완료 (merged) — [날짜]
> 병합 대상: docs/usecase/[project-name]-usecase-design.md

초안 파일은 삭제하지 않고 이력 용도로 보존한다.

채팅 안내

병합 완료 후 채팅에 간략히 안내한다:

• 메인 문서 경로
• 병합 리포트 경로
• 주요 변경 사항 한 줄 요약