uc-review

UseCase 문서 리뷰

개요

UseCase 초안(draft) 또는 메인 설계서를 체계적으로 리뷰한다. 5개 관점에서 검토하고, 발견된 이슈를 등급별로 분류하여 리뷰 리포트 파일에 기록한다.

---

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

이 스킬은 클로드 코드 환경에서 사용한다. 리뷰 결과는 채팅이 아닌 파일에 기록한다.

원칙

1. 리뷰 결과를 파일에 기록한다. 리뷰 리포트를 .md 파일로 저장한다.
2. 채팅에는 요약만. "리뷰를 완료했습니다. CRITICAL 2건, WARNING 3건입니다." 정도만 안내한다.
3. 수정도 파일에서. 수정 반영 시 원본 파일을 직접 편집하고 리포트를 갱신한다.

채팅 출력 패턴

# 리뷰 완료 시 (예시)
리뷰를 완료했습니다.
→ docs/usecase/drafts/[feature]/review-report.md

요약: ❌ CRITICAL 2건 | ⚠️ WARNING 3건 | ℹ️ INFO 1건
자세한 내용은 리포트를 확인해주세요.
수정을 바로 반영할까요?

---

시작 절차

1. 리뷰 대상 확인

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

리뷰 대상이 될 수 있는 파일:

• docs/usecase/drafts/[feature]/[feature]-draft.md — 통합 초안
• docs/usecase/drafts/[feature]/step*.md — 개별 단계 파일
• docs/usecase/[project-name]-usecase-design.md — 메인 통합 문서

2. 리뷰 범위 결정

사용자에게 리뷰 범위를 질문한다:

• 전체 리뷰: 5개 관점 모두 검토 (기본값)
• 부분 리뷰: 특정 관점만 검토
• 비교 리뷰: 초안과 메인 문서 간의 정합성 검토

---

리뷰 5개 관점

관점 1: 완전성 (Completeness)

항목	검토 내용
8단계 존재 여부	유스케이스 목록, 시나리오, 변수 식별, 도메인 모델, 상태 모델, 경계 분리, 예외, 사전/사후조건 모두 있는가?
UC별 시나리오	모든 UC에 대해 기본 흐름이 작성되었는가?
UC별 변수 식별	모든 UC에 대해 독립변수, 상수, 종속변수가 식별되었는가?
상태 모델 존재 여부	상태 모델이 작성되었는가? "이벤트 식별 → 이벤트-전이 매핑 → 상태 확정 → 불허 전이" 4단계가 모두 포함되었는가?
예외 커버리지	모든 시나리오 단계에 대해 예외가 검토되었는가?
사전/사후조건	모든 UC에 대해 사전/사후조건이 작성되었는가?
Mermaid 다이어그램	2~6단계에 필수 다이어그램이 모두 포함되어 있는가? (2단계: 시퀀스, 3단계: 변수 관계도, 4단계: 클래스, 5단계: 상태, 6단계: 시스템 경계 + UC 다이어그램)
메타 정보	프로젝트명, 작성일, 상태가 기재되어 있는가?

관점 2: 일관성 (Consistency)

항목	검토 내용
ID 연속성	UC ID, UC-INT ID가 빠짐이나 중복 없이 연속인가?
액터 일관성	시나리오의 액터가 6단계 액터 목록에 모두 포함되어 있는가?
엔티티 일관성	시나리오의 명사가 도메인 모델에 반영되어 있는가?
변수-시나리오 정합성	변수 식별의 시나리오 근거가 실제 시나리오 단계와 일치하는가?
변수-도메인 정합성	독립변수와 종속변수가 엔티티 속성으로 반영되어 있는가?
상태-도메인 모델 정합성	상태 모델의 엔티티가 도메인 모델에 있는가? 상태가 엔티티 속성(status 등)으로 반영되어 있는가?
이벤트-시나리오 정합성	비즈니스 이벤트가 시나리오의 동사(행위)에서 도출되었는가? UC 시나리오 근거가 실제 단계와 일치하는가?
이벤트-전이 도출 순서	이벤트에서 전이를 도출하고, 전이에서 상태를 확정하는 순서를 따랐는가? (상태를 먼저 나열하지 않았는가?)
상태-사후조건 정합성	상태 전이 결과가 해당 UC의 사후조건에 반영되어 있는가?
종속변수-사후조건 정합성	종속변수가 사후조건에 빠짐없이 반영되어 있는가?
상수-사전조건 정합성	상수의 전제 조건이 사전조건에 반영되어 있는가?
용어 통일	같은 개념에 다른 이름을 사용하고 있지 않은가?
참조 정합성	내부 UC가 트리거를 정확히 참조하고 있는가?
다이어그램-표 정합성	다이어그램 노드가 표 내용과 1:1 일치하는가?
다이어그램 간 정합성	6단계(UC 다이어그램)↔1단계(UC 목록), 4단계(클래스)↔3단계(변수), 5단계(상태)↔4단계(도메인 모델), 5단계(상태)↔2단계(시나리오) 다이어그램이 서로 대응하는가?

관점 3: 품질 (Quality)

항목	검토 내용
시나리오 구체성	"누가 무엇을 한다" 형식으로 명확한가?
대안 흐름	합리적인 대안 흐름이 누락되지 않았는가?
변수 분류 타당성	독립/상수/종속 분류가 UC 맥락에서 논리적인가?
종속변수 결정 요인	결정 요인이 명시되어 있고 누락이 없는가?
상수 근거	상수의 근거/출처가 명확한가?
도메인 규칙	비즈니스 불변식이 충분히 정의되었는가?
이벤트 식별 완전성	시나리오에서 엔티티 상태를 변화시키는 모든 행위(동사)가 이벤트로 식별되었는가?
상태 도출 완전성	이벤트-전이 매핑에서 도출된 모든 상태가 상태 확정 테이블에 포함되었는가?
이벤트 구체성	비즈니스 이벤트가 구체적이고, UC 시나리오 단계가 정확히 연결되었는가?
불허 전이 타당성	불허 전이의 사유가 비즈니스 규칙에 기반하고 있는가?
예외 대응	시스템 대응이 구체적인가?
사전/사후조건	검증 가능한 형태로 작성되었는가?
다이어그램 가독성	Mermaid 문법이 올바른가? 10개 초과 노드는 분할되었는가?
다이어그램 정보 밀도	표의 단순 반복이 아니라 관계·흐름을 시각화하는가?

관점 4: 구조적 적절성 (Structural Adequacy)

항목	검토 내용
유스케이스 크기	하나의 UC가 적정한가? (시나리오 3~10단계)
내/외부 분리	분류가 올바른가?
의존성 방향	순환 참조가 없는가?
관계 정합성	1:1/1:N/N:M 표기가 논리적인가?
상태 모델 범위	상태 모델이 개념 수준(비즈니스 상태)인가? 구현 수준(DB 컬럼) 세부사항이 혼입되지 않았는가?

관점 5: 기존 문서 정합성 (Cross-document Alignment)

기존 메인 문서나 다른 초안이 있는 경우에만 수행한다.

항목	검토 내용
ID 충돌	기존 문서와 ID가 충돌하지 않는가?
액터 재사용	기존 액터를 올바르게 참조하고 있는가?
엔티티 충돌	같은 이름의 엔티티가 다른 속성으로 정의되어 있지 않은가?
도메인 규칙 모순	새 규칙이 기존 규칙과 모순되지 않는가?
상태 모델 충돌	같은 엔티티의 상태 목록이 기존 문서와 모순되지 않는가? 기존 전이를 깨뜨리는 신규 전이가 없는가?

---

리뷰 리포트 파일

파일 위치:

• 초안 리뷰 시: docs/usecase/drafts/[feature]/review-report.md
• 메인 문서 리뷰 시: docs/usecase/review-report-[날짜].md

리포트 형식:

# UseCase 리뷰 결과

> 대상: [파일명]
> 리뷰일: [날짜]
> 범위: 전체 리뷰 / 부분 리뷰 ([관점])

## 요약

| 관점 | 상태 | 이슈 수 |
|------|------|--------|
| 완전성 | ✅/⚠️/❌ | N개 |
| 일관성 | ✅/⚠️/❌ | N개 |
| 품질 | ✅/⚠️/❌ | N개 |
| 구조적 적절성 | ✅/⚠️/❌ | N개 |
| 기존 문서 정합성 | ✅/⚠️/❌/N/A | N개 |

## 이슈 목록

### [CRITICAL] 반드시 수정 필요

1. **[관점]** 설명...
   - 위치: 섹션/파일
   - 제안: ...

### [WARNING] 수정 권장

1. **[관점]** 설명...
   - 위치: 섹션/파일
   - 제안: ...

### [INFO] 참고/개선 가능

1. **[관점]** 설명...

상태 기준: ✅ 이슈 없음 | ⚠️ WARNING만 | ❌ CRITICAL 있음

---

리뷰 후 행동

리포트 파일을 저장한 뒤, 사용자에게 다음 선택지를 채팅으로 안내한다:

1. 즉시 수정: CRITICAL/WARNING 이슈를 원본 파일에 반영하고, 리포트의 해당 항목에 [수정 완료] 표시를 추가한다.
2. 리뷰만 확인: 리포트만 참고하고, 사용자가 나중에 수정한다.
3. 부분 수정: 특정 이슈만 선택하여 수정한다.

수정 반영 시 원본 파일(step*.md 또는 draft.md)을 직접 편집하고, 리포트 파일에 수정 이력을 기록한다:

## 수정 이력

| 이슈 | 수정 내용 | 수정일 |
|------|----------|--------|
| CRITICAL-1 | step2-scenarios.md UC-03 기본 흐름 3단계 주어 추가 | [날짜] |