dev-goraebap/requirements-refiner

requirements-refiner 스킬

ddd-workshop 파이프라인의 입구. 막연한 입력을 받아 다음 스킬들이 쓸 수 있는 정제된 요구사항 + 맥락 + 도메인 브리프로 내보낸다.

이 스킬 하나가 v1의 project-kickoff + domain-research + requirement-clarifier를 모두 담당한다. 이유: 사용자 경험상 초기에 스킬을 3개 돌리는 것보다 한 스킬 안에서 단계적으로 진행하는 것이 흐름이 매끄럽다.

---

대화 UX 규약 (필수)

• 카테고리 선택은 숫자 메뉴 ("1) ... 2) ..."). 자유 입력 금지.
• 1문 1답 기본. 단순 Yes/No만 2~3개까지 번호 달아 묶기 허용.
• 진행 표시: [Q 3/12 · 근거: 자가 진단 #5]
• "나중에" / "모름" / "스킵" 항상 허용 → 산출물에 ⚠️ 미정으로 기록. 초기 단계 답 강요 금지.
• 자가 진단·평가는 ✅/⚠️/❌ 3단계. 숫자 점수 금지.
• 정답보다 올바른 질문 생성이 이 스킬의 핵심 가치.

---

1. 언제 트리거하는가

• /ddd-workshop:requirements-refiner
• "~~ 만들고 싶어", "DDD 시작", "프로젝트 킥오프", "아이디어 정리"
• PRD·요구사항 문서를 던지며 "여기서부터 시작"
• 기존 requirements.md가 있고 "업데이트하자" → --update 모드

---

2. 입력

• 사용자의 자유 서술 (한 문장도 가능)
• 또는 기존 PRD / 기획 문서 경로
• 또는 이전 requirements.md (--update 모드)

부분 진입 허용: 입력이 빈약해도 맥락 판별부터 시작. 모르는 항목은 ⚠️ 미정으로 남김.

---

3. 4단계 진행

내부적으로 4단계를 거치며, 각 단계가 끝날 때마다 사용자에게 중간 산출물을 보여주고 확인받는다.

Step 1 — 맥락 판별

첫 발화에서 맥락을 추정하고, 모호하면 숫자 메뉴로 한 번만 확인한다.

이 프로젝트는 어떤 성격인가요? (번호로 답해주세요)

1) 학습/취미 — 배우거나 손맛으로
2) 개인 도구 — 내가 쓰려고
3) 사내 도구/솔루션 — 우리 팀·회사 내부
4) B2B — 외부 기업 고객에게 납품
5) B2C 제품 — 외부 일반 사용자에게 제공

단서 표:

| 발화 | 추정 | |---|---| | "연습", "공부" | 학습 | | "내가 쓰려고" | 개인 | | "우리 팀", "사내" | 사내 | | "고객사", "납품" | B2B | | "사용자 모으고", "런칭" | B2C |

확정 후 confidence: {high|medium|low} 기록.

Step 1-b — Ubiquitous Language 기본 언어 결정

파이프라인 전체에서 쓸 UL 기본 언어를 1회 고정한다. 이후 후속 스킬들이 이 설정을 따라 이중 표기(한국어/영어 + Code Identifier)를 생성.

UL(Ubiquitous Language) 기본 언어를 정해주세요.

사용자와 에이전트가 주로 쓸 언어를 고르면, 후속 스킬들은
"용어(사용자 언어) | Code Identifier(영어) | 의미" 3열로
용어집을 작성합니다.

1) 한국어 기본 (코드 식별자는 영어 병기) — 기본값
2) 영어 기본 (단일 컬럼)
3) 기타 언어 기본 (직접 입력)

판단 기본값: 사용자가 한국어로 대화 중이면 1번. 영어면 2번.

Step 2 — 핵심 5질문 + 맥락별 추가

1문 1답으로 진행. 큐 순서:

공통 5질문 (맥락 무관):

1. 이 시스템은 무엇을 하는가? (한 문장)
2. 누가 사용하는가? (액터·역할)
3. 어떤 문제를 풀거나 어떤 가치를 주는가? (Why)
4. 반드시 포함 / 명시적 제외할 것은?
5. 기존 시스템·제약(기술/일정/인력)?

맥락별 추가:

• 학습: "어디까지가 완성인가", "배우고 싶은 기술". 시장·지표 질문 금지.
• 개인: "내가 쓰기 시작하는 상황", "혼자 유지보수 가능 범위". 페르소나 질문 금지.
• 사내: As-Is 프로세스, 연동 시스템, 이해관계자, 규제·감사.
• B2B: 계약 단위, 멀티테넌시, SLA, 보안, 커스터마이징.
• B2C: 타깃 사용자, 경쟁 차별점, 성공 지표.

각 답변은 진행 표시 [Q N/M] 와 함께. 답 강요 금지("나중에"/"모름" 허용).

Step 3 — 에이전트 자가 진단 (리터럴 체크리스트, 생략 금지)

맥락·기본 정보가 모이면 에이전트 스스로 다음 8문항을 ✅/⚠️/❌ 3단계로 평가하고 사용자에게 공개한다.

🔍 에이전트 자가 진단

이 도메인에 대해:

1. [?] 핵심 개념 5개를 설명할 수 있는가?
2. [?] 업계 고유 용어(전문 용어, 약어)를 구분할 수 있는가?
3. [?] 이 업계에 적용되는 법/규제를 최소 하나라도 아는가?
4. [?] 일반적 업무 프로세스를 단계별로 기술할 수 있는가?
5. [?] 이 업계의 자주 발생하는 엣지 케이스를 예로 들 수 있는가?
6. [?] 유사 기존 서비스를 최소 3개 들 수 있는가?
7. [?] 다른 시스템과 통합되는 전형적 방식을 아는가?
8. [?] 최근 1~2년간 이 업계의 변화가 있었는지 아는가?
   → "없다"에 특히 의심. 모름을 "없음"으로 착각하기 쉬움.

평가: ✅ 자신 있음 / ⚠️ 얕음 / ❌ 모름

공개 후, ⚠️ 또는 ❌ 항목에 대해 사용자에게 선택지 제시:

아래 항목이 얕거나 모르는 상태입니다. 어떻게 메울까요?

1) 웹 리서치 (에이전트가 공식 출처 기준으로 조사, 출처 명시)
2) 사용자가 알려줌 (직접 답변)
3) 나중으로 미룸 (`⚠️ 미정`으로 기록, 다음 스킬에 경고 전파)

리서치가 선택되면 Step 4에서 수행.

필수 원칙 (얼버무림 금지):

• 출처 없는 주장 금지.
• 자체 지식과 리서치 결과를 명확히 구분 표기.
• 의료·법률·세무·금융 등 전문 영역은 "실제 전문가 확인 필요" 경고 필수.
• "잘 아는 도메인"이라도 최근 1~2년 변화는 웹으로 재확인.

Step 4 — (옵션) 도메인 리서치 + 빈틈·모순 질문 큐

웹 리서치 (Step 3에서 요청된 경우만):

• 공식 출처 우선 (정부, 업계 협회, 서비스 공식 문서 > 블로그 > SNS)
• 모든 정보에 URL + 조회일 + 인용 구절
• 결과를 도메인 브리프 섹션에 정리

빈틈·모순 질문 큐 (내부 생성 → 1문 1답):

질문 후보 카테고리(내부에서 큐에 적재):

1. 모순·충돌 — 최우선. 진행을 막으므로 즉시 해소.
2. 비정상 경로 — 실패, 취소, 환불, 타임아웃, 중복.
3. 다른 액터 — 관리자, 운영자, 외부 시스템, 봇, 감사자.
4. 시간 요소 — 만료, 스케줄, 배치, 시간대.
5. 상태 전이 — 어떤 상태 → 어떤 상태, 역전이.
6. 데이터 생명주기 — 생성·수정·삭제·보관·파기, 보존 기간.
7. 권한·접근 — 누가 볼 수 있나, 누가 바꿀 수 있나.
8. 규정·정책 — 법적 제약, 감사 추적성.
9. 수량·규모 — 동시 사용자, 데이터 크기.
10. 동시성 — 같은 리소스 동시 접근.
11. 도메인 특화 — 리서치·자가 진단에서 도출.
12. 암묵 가정 — "당연히 그럴 것"으로 여긴 내용.

1문 1답 루프:

[Q 3/12 · 근거: 비정상 경로]
결제 실패 시 주문의 재고는 즉시 복원하나요, 아니면 타임아웃까지 예약 상태로 두나요?
(답변 외에 "나중에" / "모름" / "스킵" 도 가능합니다)

답변이 새 질문을 열면 큐에 추가. 기존 질문을 무의미하게 만들면 제거 + 사용자에게 알림("답변 덕분에 Q7은 생략합니다").

---

4. 산출물

기본 경로 docs/shared/requirements.md. 프로젝트 관례가 다르면 사용자에게 확인.

YAML frontmatter 없음. 본문만.

# 요구사항

## 프로젝트 정체성
- 한 줄 정의:
- 맥락: {학습|개인|사내|B2B|B2C}
- UL 기본 언어: {한국어|영어|기타}
- Why (해결하려는 문제):
- 핵심 가치:

## 액터
- ...

## 범위
- 반드시 포함 (MUST):
- 명시적 제외 (영영 안 함):
- 나중으로 미룸 (Later):

## 제약 조건
- 기술 / 일정 / 인력:
- (사내) As-Is 프로세스:
- (사내) 연동 시스템:
- (사내) 규제·감사:
- (B2B) 계약·멀티테넌시·SLA:
- (B2C) 타깃 사용자·차별점·성공 지표:

---

## 에이전트 자가 진단
(Step 3 결과. 투명성을 위해 그대로 포함)

### ✅ 일반 상식 수준에서 아는 것
- ...

### ⚠️ 얕게 아는 것
- ...

### ❌ 모르는 것
- ...

---

## 도메인 브리프 (리서치 수행 시)

### 업계 일반 지식
- [내용] — 출처: [제목](URL) — YYYY-MM-DD 조회

### 관련 법규 및 규제
- [법규명]: [내용] — 출처: ...
  ⚠️ 세부 해석은 법무/변호사 확인 필요

### 업계 표준 프로세스
- ...

### 주요 플레이어 및 관행
- ...

### 자주 발생하는 엣지 케이스
- ...

### 후속 스킬을 위한 힌트
- `event-storming-explorer`가 주의할 이벤트·동음이의어: ...
- `subdomain-classifier`가 참고할 경쟁 차별점: ...
- `context-designer`가 참고할 업계 표준 경계: ...
- `screen-inventory`가 다룰 주요 화면 후보: ...
- `aggregate-designer`가 누락하기 쉬운 이벤트: ...

---

## 정제된 요구사항

### 기능 요구사항 (MUST)
- [기능명]: [설명]
  - 성공 기준:
  - 실패 처리:

### 기능 요구사항 (SHOULD)
- ...

### 비기능 요구사항
- 성능 / 보안 / 접근성:

---

## 암묵 가정
- ⚠️ 가정: ...

## 모순/충돌
- ⚠️ 충돌: ... (해결 방향은 사용자 결정)

## 미정 항목 (사용자가 스킵한 것)
- ⚠️ 미정: ...

## 다음 단계
→ `event-storming-explorer`로 Big Picture Event Storming + 서브도메인 후보 식별.

---

5. 업데이트 모드 (--update)

기존 docs/requirements.md가 있고 변경 요청이 들어오면:

1. 기존 frontmatter + 본문 읽어 메모리에 로드.
2. 사용자에게 "무엇이 바뀌었나요?" (숫자 메뉴):

   1) 새 요구사항 추가
   2) 기존 요구사항 수정
   3) 맥락 변화 (예: 개인→B2C)
   4) 자가 진단 재실행
   5) 미정 항목 해소
   6) 기타(자유 입력)
   

3. 선택된 영역에 대해서만 delta 질문 큐 구성. 전체 재수행 금지.
4. 반영 후 updated_at 갱신, 변경된 섹션만 업데이트.
5. sources:를 통해 이 문서를 참조하는 downstream 스킬들에게 "stale 알림" 유도 (downstream의 Step 0에서 감지).

전면 재작성: 사용자가 명시적으로 "처음부터 다시 하자"고 할 때만 수행. 확인 필수.

---

6. 강제 체크리스트 (산출물 내기 전)

□ 맥락 판별됨 (5종 중 하나) + confidence 기록
□ UL 기본 언어 결정됨 (Step 1-b)
□ 한 줄 정의 · Why · 액터 · 범위 · 제약 모두 채워짐 (미정은 ⚠️)
□ 자가 진단 8문항 평가됨 (✅/⚠️/❌)
□ ⚠️/❌ 항목에 대해 "리서치/사용자/미정" 선택됨
□ 리서치 수행 시 모든 항목에 출처 명시
□ 정제된 요구사항이 MUST/SHOULD로 레이블됨
□ 암묵 가정 최소 2개 명시
□ 모순 있으면 명시 (없으면 "모순 없음")
□ 미정 항목 별도 섹션에 모음
□ 산출물 경로: docs/shared/requirements.md
□ Frontmatter 없음 (본문만)

---

7. 맥락별 조정 요약

| 맥락 | 자가 진단 깊이 | 리서치 권장 | 질문 큐 크기 | |---|---|---|---| | 학습 | 최소 | 거의 없음 | 10개 이하 | | 개인 | 중간, 사용자 전문성 우선 | 필요시 | 10~15개 | | 사내 | 중간 (사용자가 내부 전문가) | 규제만 | 15~20개 | | B2B | 깊게 | 최대 | 20개 이상 | | B2C | 깊게 | 최대 | 20개 이상 |

---

8. 절대 하지 말 것

• 자가 진단 8문항을 산문으로 풀거나 생략하기. 리터럴 체크리스트 유지.
• 자가 진단 결과를 사용자에게 숨기기.
• 카테고리 선택을 자유 입력으로 받기.
• 한 메시지에 질문 4개 이상 쏟기 (작은 Yes/No 묶음 예외).
• 리서치 결과와 자체 지식을 구분 없이 섞어 서술.
• 출처 없는 법규·통계·관행 단정.
• 의료·법률·세무·금융에 전문가 수준 조언 (경고 필수).
• "최근 변화 없음"을 쉽게 결론 (모름을 가린 표현일 가능성 높음).
• 사용자가 "나중에"라고 답했는데 다시 압박하기.
• 전면 재작성을 사용자 확인 없이 수행.