---
name: prd-generator
description: 아이디어나 docs/IDEA.md를 받아 "무엇을 만들 것인가"를 정의하는 PRD(docs/PRD.md)를 작성한다. 요구사항마다 고유 ID와 검증 가능한 수용 기준을 붙여, 이후 아키텍처·플랜·태스크·품질 게이트가 그대로 참조할 수 있게 만든다. 사용자가 "PRD 써줘", "요구사항 정리해줘", "기획서 만들어줘", "제품 스펙 문서", "유저 스토리 정리"라고 하거나, 아이디어 브레인스토밍을 마치고 다음 단계로 넘어갈 때 반드시 이 스킬을 사용한다. 무엇을 만들지는 정해졌는데 기능 목록과 수용 기준이 문서로 없는 상태에서 개발이나 설계를 시작하려 할 때도 이 스킬로 먼저 요구사항을 고정한다.
---

# PRD 작성 (Layer 1)

## 이 스킬의 목적

PRD는 **"무엇을 만들 것인가"**에 대한 합의문이다. 여기서 정의한 요구사항 하나하나가 뒤에서 이렇게 흘러간다.

```
PRD의 요구사항 FR-007
   → 아키텍처에서 어느 컴포넌트가 책임지는지 결정  (Layer 2)
   → 태스크로 쪼개져 구현                          (Layer 3~5)
   → 수용 기준이 그대로 검증 항목이 됨              (Layer 4 품질 게이트)
```

그래서 이 문서의 품질은 "읽기 좋은가"가 아니라 **"나중에 기계적으로 추적하고 검증할 수 있는가"**로 판정된다.
"사용자가 편리하게 로그인할 수 있다" 같은 문장은 읽기엔 좋지만, 태스크로 쪼갤 수도 없고 통과 여부를 판정할 수도 없다.
그런 문장이 PRD에 남으면 Layer 4의 task validation 단계에서 검증자가 무엇을 확인해야 할지 몰라 그냥 통과시키게 된다.

### 여기서 하는 일과 하지 않는 일

| 하지 않는 것 | 어디서 하는가 |
|---|---|
| 기술 스택, 프레임워크, DB, 배포 방식 | TRD (`trd-generator`) |
| 테이블 설계, API 엔드포인트, 컴포넌트 구조 | Layer 2 아키텍처 |
| 개발 순서, 일정, 태스크 분할 | Layer 3 마스터 플랜 |
| 화면 픽셀 디자인 | 별도 디자인 작업 |

PRD와 TRD를 나누는 이유는 형식이 아니다. **요구사항은 기술 선택보다 오래 살기 때문**이다.
"결제 기능이 필요하다"는 3년 뒤에도 유효하지만 "Stripe를 쓴다"는 6개월 만에 바뀔 수 있다.
둘을 한 문서에 섞으면 기술을 바꿀 때 요구사항까지 함께 흔들리고, 무엇이 합의된 것이고 무엇이 구현 선택이었는지 아무도 구별하지 못하게 된다.

다만 요구사항이 특정 기술을 **강제하는 제약**이라면(예: "관공서 납품이라 국내 리전에 저장해야 함) 그건 비기능 요구사항으로 PRD에 적는다.
선택이 아니라 제약이기 때문이다. 판단 기준은 이것이다 — **"이걸 다른 걸로 바꿔도 사용자에게 약속한 것이 지켜지는가?"** 지켜지면 기술 선택(TRD), 안 지켜지면 제약(PRD).

---

## 1단계. 입력 확보

**`docs/PRD.md` 가 이미 있으면 작성(1~6단계)을 다시 돌지 않는다** — 남은 미결을 푸는 것이면 7단계(미결 해소 세션), 내용을 바꾸는 것이면 8단계(부분 갱신)만 한다. 7단계로 풀었는데 뒤 문서(TRD 이후)가 이미 있으면, 끝에 8단계의 버전·`변경 이력` 한 줄·뒤 문서 맞추기를 한다 — 미결 해소도 PRD 를 바꾼 것이고, 버전이 그대로면 뒤 스킬이 알아채지 못한다. 처음부터 다시 쓰면 FR 번호와 사용자와 푼 미결이 초기값으로 덮이고, 그 번호를 가리키는 뒤 문서가 전부 엉뚱한 요구사항을 가리킨다. 사용자가 처음부터 다시 쓰라고 명시하면 그때만 1단계부터 돈다 — 뒤 문서가 이미 있으면 번호가 흔들려 뒤 문서의 참조가 엉뚱한 항목을 가리킨다는 것을 먼저 알린다.

먼저 `docs/IDEA.md` 가 있는지 확인한다. 있으면 그것이 주 입력이다.

**IDEA.md 가 있는 경우** — 전부 읽고, 특히 **'미결 사항'과 '(가정)' 표기를 최우선으로 처리한다.**
아이디어 단계에서 미뤄 둔 결정이 PRD에 그대로 넘어오면, 요구사항이 가정 위에 세워진다. 그 가정이 틀어지면 요구사항 절반이 무효가 된다.

미결 항목마다 아래 넷 중 하나로 처리하고, 어느 쪽인지 문서에 남긴다.

1. **지금 결정한다** — 사용자에게 선택지와 함께 묻는다. 요구사항의 존재 여부를 가르는 것이면 반드시 여기에 해당한다.
2. **가정으로 확정하고 표시한다** — 세부 사항이면 합리적 값으로 정하고 `(가정)` 표기를 유지한다.
3. **범위 밖으로 밀어낸다** — 이번 버전에서 안 다루기로 하고 '범위 밖'에 적는다.
4. **미결로 남기되, 흘러갈 경로를 만든다** — 아래를 따른다.

미결을 미결인 채로 요구사항 본문에 섞어 넣는 것만은 하지 않는다. 뒤 레이어는 PRD 본문을 확정된 합의로 읽는다.

**처리하다가 범위가 바뀌면 IDEA.md 에도 돌려놓는다(변경 전파).** 3번처럼 IDEA 의 MVP 포함 항목을 범위 밖으로 보내거나, 사용자가 대화에서 타깃·핵심 흐름을 바꾸면
IDEA 와 PRD 가 서로 다른 제품을 말하게 된다. 사용자가 그 결정을 내린 자리에서 `idea-brainstorm` 7단계(부분 갱신)로 해당 줄만 고치고(부를 수 없으면 같은 규칙으로 직접 — 해당 줄만, 버전·`변경 이력` 한 줄)
PRD 머리의 `입력 문서` 버전을 맞춘 뒤 이어 간다. 세부(수용 기준·NFR 수치)는 PRD 가 덮으므로 IDEA 에 옮기지 않는다.

### 즉답으로 풀리지 않는 미결 다루기

미결을 전부 "사용자에게 물어보면 되는 것"으로 취급하면 안 된다. 실제로는 종류가 다르고, 종류마다 푸는 방법이 다르다.
이걸 구분하지 않으면 모델은 둘 중 하나를 하게 된다 — 그럴듯한 값으로 가정해 확정해 버리거나, 표에 적어 두고 잊거나.
둘 다 나중에 요구사항 여러 개를 무효로 만든다.

**이 분류는 잠정이다.** 모델이 제안하는 것이고, 확정하는 사람은 사용자다.
같은 항목이 사용자에게는 다르게 보일 수 있다 — 모델이 "물어보면 되는 것"으로 본 항목을 사용자는
"인터뷰 끝나기 전엔 정하면 안 되는 것"으로 알 수 있다. 그쪽이 맞다. 사용자가 맥락을 더 안다.
그래서 문서에는 종류를 `질문(잠정)` 처럼 적고, 6단계 보고에서 **"이 분류가 틀렸으면 알려달라"**고 명시적으로 요청한다.

| 종류 | 어떤 미결인가 | 어떻게 푸는가 |
|---|---|---|
| **질문** | 사용자의 선호·방침. 물으면 바로 답이 나온다 | 선택지와 함께 묻는다 |
| **확인** | 사용자도 모른다. 외부 사실 확인이 필요하다 (사내 정책, 법 규정, 외부 서비스 지원 여부) | 누가 무엇을 확인할지 적는다. 확인 자체가 하나의 할 일이다 |
| **실험** | 해봐야 안다 (기술적 실현 가능성, 성능 한계) | 스파이크로 전환한다. Layer 3에서 검증용 태스크가 된다 |
| **유예** | 지금 정하면 오히려 틀린다 (사용자 인터뷰 전, 초기 데이터 전) | 무엇을 보면 정할 수 있는지와 시점을 적는다 |

### 미결은 만들기 전에 한 번 걸러낸다

미결은 공짜가 아니다. 하나 만들 때마다 사용자가 답해야 할 항목이 늘고, 뒤 레이어에는 blocked 태스크가 생기고,
STATE.md에 추적할 것이 붙는다. **미결 목록이 길수록 좋은 문서가 아니라, 결정을 미룬 문서다.**

그래서 미결로 올리기 전에 세 가지를 자문한다. 하나라도 "아니오"면 미결로 만들지 말고 그 자리에서 처리한다.

1. **이 답에 따라 요구사항이 생기거나 사라지거나 바뀌는가?**
   아니라면 미결이 아니다. 성공 지표의 숫자, 문서 문구, 화면 문구 같은 것은 기본값으로 정하고 넘어간다.
   나중에 바꿔도 요구사항이 흔들리지 않는다.
2. **틀렸을 때 되돌리는 비용이 실제로 큰가?**
   작다면 가정으로 확정한다. `(가정)` 표기와 리스크 표 한 줄이면 충분하다.
3. **사용자만 답할 수 있는가?**
   문서 안에서 이미 답이 나오거나(IDEA.md에 있는데 못 찾은 경우), 업계 표준으로 정해도 되는 것이면 묻지 않는다.

**미결이 다른 미결에 흡수되는지도 본다.** "클라이언트가 확인 버튼을 누를 수 있는가"는 "전자서명을 넣는가"의 답에 따라
자동으로 정해진다. 이런 것은 독립 미결로 세우지 말고 상위 미결의 선택지 설명에 녹인다.
미결 12개 중 절반이 사실 3개의 파생이라면, 사용자는 같은 결정을 네 번 하게 된다.

### 미결이 남은 채로 진행할 때의 규칙

미결이 있다고 PRD 작성을 멈추지 않는다. 대신 두 가지를 지킨다.

**첫째, 미결이 P0 요구사항을 막으면 그 요구사항은 가정으로 덮지 않는다.**
P0는 "없으면 출시 불가"인 것들이다. 그 근거가 흔들리는 상태로 확정하면, 나중에 뒤집혔을 때 제품의 뼈대가 함께 무너진다.
이런 미결은 미결 표에서 **차단(blocking)** 으로 표시하고, 사용자에게 보고할 때 맨 위에 올린다.
P1 이하라면 기본값으로 진행해도 된다. 되돌리는 비용이 감당 가능한 범위이기 때문이다.

**둘째, 모든 미결에 '미해소 시 기본값'과 '되돌리기 비용'을 적는다.**
기본값이 있으면 답을 못 받아도 프로젝트가 멈추지 않는다. 되돌리기 비용이 있으면 무엇을 걸고 진행하는지가 분명해진다.

되돌리기 비용은 "이 기본값이 나중에 틀렸다고 판명되면 무엇을 다시 해야 하는가"이다. 예를 들면 이렇게 쓴다.

> **미결**: 전자서명을 이번 버전에서 빼도 되는가
> **기본값**: 뺀다 (PDF 생성 + 링크 공유까지)
> **되돌리기 비용**: FR-010~013 재작성, 서명 관련 FR 3~5개 추가. 외부 연동까지 필요하면 인보이스 기능 전체를 다음 버전으로 이동

이걸 적는 이유가 셋 있다.
사용자가 답의 무게를 알게 되고("빼도 되죠?"에 쉽게 동의하지 않게 된다),
어떤 미결을 먼저 풀지 정할 수 있으며(비싼 것부터),
실제로 되돌릴 상황이 왔을 때 그때의 판단 근거가 남아 있다.

### 미결은 소멸하지 않고 뒤 레이어로 간다

PRD의 미결은 여기서 끝나는 항목이 아니라 **다음 레이어가 이어받는 객체**다. 흐름은 이렇다.

```
PRD의 미결 OQ-003 (외부 API 전송 가능 여부, 차단)
   → 차단하는 요구사항 표시:  FR-005, FR-009
   → Layer 3에서 그 FR의 태스크는 status: blocked 로 생성된다
   → '확인' 액션 자체가 별도 태스크가 된다
   → 해소되면 blocked 해제, STATE.md·LOG.md에 기록
```

그래서 미결에는 **OQ-001** 형태의 ID를 붙이고, 차단하는 FR 번호를 반드시 적는다.
ID가 없으면 뒤 레이어에서 "무엇 때문에 막힌 태스크인지" 가리킬 방법이 없다.

**IDEA.md 가 없는 경우** — Layer 0을 건너뛴 것이므로 사용자 설명이 유일한 입력이다.
이때는 PRD를 쓰기 전에 최소한 이것들을 묻는다. 답이 없으면 요구사항을 쓸 수 없는 것들이다.

- 이 제품의 사용자는 누구이고, 지금은 그 일을 어떻게 처리하고 있는가
- 첫 버전에 반드시 있어야 하는 기능과 없어도 되는 기능
- 무엇이 되면 성공이라고 말할 수 있는가
- 반드시 지켜야 하는 제약(법·보안·성능·기간)이 있는가

질문은 한 번에 1~2개씩, 선택지를 붙여서 한다. 아이디어가 많이 모호하면 PRD를 억지로 쓰지 말고
`idea-brainstorm` 스킬로 먼저 정리하자고 제안한다.

**기존 코드베이스가 있는 경우** — 기존 기능을 추측으로 적지 말고 실제로 확인한다. README, 라우트 파일, 화면 목록을 훑어
"이미 있는 것 / 새로 만드는 것 / 바꾸는 것"을 구분한다. 이 구분이 없으면 뒤에서 이미 있는 기능을 다시 만드는 태스크가 생긴다.

## 2단계. 사용자와 유저 스토리 정리

요구사항을 바로 나열하지 말고 **사용자 → 스토리 → 요구사항** 순서로 간다.
기능부터 쓰면 "있으면 좋을 것 같은" 기능이 섞여 들어오는데, 스토리에서 출발하면 그 기능이 누구의 무엇을 위한 것인지 자동으로 검사된다.

- **사용자 유형**을 2~4개로 정리한다. 각 유형은 목표와 기술 숙련도가 실제로 다른 사람이어야 한다.
  "관리자"와 "슈퍼 관리자"처럼 권한만 다르면 하나로 합친다.
- **유저 스토리**는 `(사용자)로서, (무엇)을 하고 싶다. 왜냐하면 (이유)이기 때문이다` 형태로 쓴다.
  '왜냐하면'을 빼먹지 않는 것이 중요하다. 구현 단계에서 판단이 갈릴 때 개발자가 되돌아보는 것이 바로 그 이유다.
- 각 스토리에 **US-001** 형태의 ID를 붙인다.

## 3단계. 기능 요구사항

### 작성 규칙

각 요구사항은 아래 형태를 갖춘다.

```markdown
#### FR-003. 견적서 PDF 내보내기
- **관련 스토리**: US-002
- **우선순위**: P0
- **차단 미결**: 없음 (있으면 OQ-00x 를 적는다. 그 미결이 풀리기 전에는 이 요구사항을 구현하지 않는다)
- **설명**: 사용자는 작성한 견적서를 PDF 파일로 내려받을 수 있다.
- **수용 기준**:
  - [ ] 견적서 상세 화면에서 '내보내기'를 누르면 PDF 파일이 다운로드된다
  - [ ] PDF에는 화면에 표시된 항목·금액·합계가 동일하게 포함된다
  - [ ] 항목이 30개를 넘으면 페이지가 나뉘고 각 페이지에 합계가 표시되지 않는다
  - [ ] 견적서가 없거나 권한이 없으면 404를 반환하고 파일은 생성되지 않는다
```

### 수용 기준이 이 문서의 핵심이다

수용 기준은 나중에 **다른 세션의 검증자가 이 제품을 처음 보고도 통과/실패를 판정할 수 있어야** 한다(Layer 4의 task validation은
구현한 세션과 분리된 세션에서 돌아간다. 구현자의 머릿속 맥락이 검증에 새는 것을 막기 위해서다).
그 검증자에게는 이 문장이 전부다. 그러니 아래를 지킨다.

- **관찰 가능한 것만 쓴다.** 화면에 무엇이 보이는지, 무엇이 저장되는지, 어떤 응답이 오는지. "빠르게", "직관적으로", "안정적으로"는 판정할 수 없다.
- **실패 경로를 반드시 하나 이상 넣는다.** 성공 경로만 적힌 요구사항은 절반만 검증된다. 빈 입력, 권한 없음, 없는 리소스, 중복 요청 중 이 기능에서 실제로 일어날 것을 고른다.
- **숫자가 필요한 곳에는 숫자를 쓴다.** "많은 항목" 대신 "30개 초과", "곧" 대신 "3초 이내".
- 하나의 수용 기준은 하나만 검사한다. "저장되고 이메일도 발송된다"는 두 줄로 나눈다.

### 우선순위

P0(없으면 출시 불가) / P1(첫 버전에 포함 목표) / P2(다음 버전) 세 단계로만 나눈다.
단계를 더 늘리면 판단이 흐려지고, 실제로는 "지금 만드나 안 만드나"의 이진 결정이기 때문이다.
**P0가 전체의 절반을 넘으면 범위가 과하다는 신호다.** 사용자에게 그 사실을 알리고 함께 줄인다.

## 4단계. 비기능 요구사항

기능이 아니라 **품질과 제약**이다. 이것들도 검증 대상이므로 똑같이 ID와 측정 가능한 기준을 붙인다.
"보안을 준수한다" 같은 문장은 아무것도 검증하지 못한다.

아래 항목들을 훑어보고 이 제품에 **실제로 해당하는 것만** 적는다. 해당 없는 항목을 형식적으로 채우면
뒤 레이어가 그것을 만족시키려고 불필요한 작업을 만든다.

| 범주 | 무엇을 정하나 | 나쁜 예 → 좋은 예 |
|---|---|---|
| 성능 | 응답 시간, 동시 사용자, 데이터 규모 | "빠르게" → "목록 조회 P95 500ms 이내, 데이터 1만 건 기준" |
| 보안·권한 | 인증 방식의 요구, 역할별 접근 범위, 민감정보 | "안전하게" → "타인의 견적서는 URL을 알아도 열람 불가(403)" |
| 데이터 | 보관 기간, 삭제·백업 정책, 개인정보 범위 | "잘 보관" → "계약 종료 후 3년 보관, 이후 자동 파기" |
| 가용성 | 목표 가동률, 장애 시 허용 범위 | — |
| 접근성·호환 | 지원 브라우저·기기, 다국어 | "모바일 지원" → "iOS Safari 최신 2개 버전에서 전 기능 동작" |
| 법·규정 | 준수 대상 규정, 지역 제약 | "법 준수" → "개인정보 국외 이전 불가, 국내 리전 저장" |

## 5단계. `docs/PRD.md` 작성

경로는 프로젝트 루트 기준 `docs/PRD.md`. 아래 구조를 그대로 사용한다.

```markdown
# PRD: (제품 이름)

- **버전**: 0.1 (초안)
- **작성일**: YYYY-MM-DD
- **입력 문서**: docs/IDEA.md (0.1) (없으면 "사용자 설명")
- **상태**: 사람 검토 대기
- **변경 이력**: (없음 — 고칠 때마다 `0.2 (YYYY-MM-DD, <고친 스킬>) — <무엇을 왜>. 영향: <뒤 문서의 ID·절>` 한 줄씩)

## 1. 개요
### 1.1 한 줄 정의
### 1.2 배경과 문제
(왜 지금 이걸 만드는가. 현재의 대안과 그 한계.)
### 1.3 목표와 비목표
- **목표**: (이 제품이 달성하려는 것)
- **비목표**: (일부러 하지 않는 것. 여기 적어 두면 나중에 범위가 새는 것을 막는다.)

## 2. 사용자
| 유형 | 설명 | 주요 목표 | 기술 숙련도 |
|---|---|---|---|

## 3. 유저 스토리
| ID | 사용자 | 스토리 | 우선순위 |
|---|---|---|---|
| US-001 | | ...로서 ...하고 싶다. 왜냐하면 ... | P0 |

## 4. 기능 요구사항
(FR-001부터. 3단계의 형식을 따른다. 관련 있는 것끼리 묶어 소제목을 둔다.)

## 5. 비기능 요구사항
(NFR-001부터. 범주 / 요구사항 / 측정 기준 형태로.)

## 6. 범위 밖 (Out of Scope)
| 항목 | 이유 | 언제 다시 볼 것인가 |
|---|---|---|

## 7. 성공 지표
| 지표 | 목표값 | 측정 방법 |
|---|---|---|

## 8. 가정과 미결 사항
### 확정된 가정
| 가정 | 근거 | 틀리면 영향받는 요구사항 |
|---|---|---|
### 미결 사항
| ID | 결정할 것 | 종류 | 차단하는 요구사항 | 해소 방법 | 미해소 시 기본값 | 되돌리기 비용 |
|---|---|---|---|---|---|---|
| OQ-001 | | 질문(잠정)/확인/실험/유예 | FR-00x (차단이면 굵게) | | | |

## 9. 요구사항 추적표
| 요구사항 | 관련 스토리 | 우선순위 | 차단 미결 | 담당 태스크 | 상태 |
|---|---|---|---|---|---|
| FR-001 | US-001 | P0 | — | (Layer 3에서 채움) | 정의됨 |
| FR-006 | US-003 | P0 | **OQ-007** | (Layer 3에서 채움) | 정의됨 (차단) |
```

**9번 추적표를 생략하지 않는다.** 뒤 레이어에서 태스크를 만들 때 "이 요구사항이 어느 태스크로 갔는가",
반대로 "이 태스크가 어느 요구사항을 위한 것인가"를 확인하는 곳이 여기다. 이 표가 없으면 구현 중 조용히 빠지는 요구사항이 생긴다.

### 9절 `차단 미결` 열과 `상태` 열은 짝이다

`상태` 열의 값은 이 단계에서 둘뿐이다 — `정의됨` / `정의됨 (차단)`.
**`차단 미결` 열에 적힌 OQ가 8절에서 차단(굵게)이면 `상태` 는 반드시 `정의됨 (차단)` 이고, 아니면 `정의됨` 이다.**
두 열을 따로 고치지 않는다.
예외는 하나 — 8단계(부분 갱신)에서 폐기한 요구사항은 `상태` 가 `폐기` 이고, 뒤 레이어는 그 행에 태스크를 만들지 않는다.

이렇게 못 박는 이유가 있다. Layer 3은 어느 태스크를 `blocked` 로 만들지를 **`상태` 열의 `(차단)` 을 1순위 신호**로 판정한다.
`차단 미결` 열에는 OQ가 있는데 `상태` 가 그냥 `정의됨` 이면 Layer 3이 스스로 판정하게 되고, 같은 PRD로 두 번 만든 플랜이 서로 다르게 막힌다.
8절 표의 "차단하는 요구사항" 열에 적힌 FR이 전부 차단인 것은 아니다 — **차단 여부는 OQ 단위(P0를 막는가)로 정하고, 9절에는 그 결과를 옮겨 적는다.**

### `CLAUDE.md` · `AGENTS.md` 갱신

`docs/PRD.md` 를 쓴 뒤 프로젝트 루트의 `CLAUDE.md` 와 `AGENTS.md` 를 **같은 내용으로** 갱신한다. 사용자가 직접 연 세션과 루프의 자식 세션은 이 스킬을 읽지 않고 시작하는데,
그때 자동으로 읽히는 파일은 Claude Code 는 `CLAUDE.md`, Codex 는 `AGENTS.md` 뿐이다. 그래서 **지금 어느 호스트에서 돌든 둘 다 쓴다** —
한쪽만 쓰면 다른 호스트의 세션이 규칙을 모른 채 시작한다. 내용은 **어느 세션에서든 반드시 지킬 것**만 두고 세부 규칙은 문서를 가리킨다 —
규칙을 옮겨 적으면 두 곳이 곧 어긋나고, 어긋나면 세션은 짧은 쪽을 믿는다.

- 둘 다 없으면 아래 뼈대로 만든다. 있으면 **`## 제품 (docs/PRD.md)` 절과 `현재 단계` 줄만** 고친다. 다른 절과 사용자가 손으로 적은 내용은 건드리지 않는다
- 두 파일이 서로 다르면 지금 호스트의 파일을 기준으로 다른 쪽을 맞춘다. 손으로 적은 줄은 양쪽에 남긴다
- 파일은 있는데 `## 문서 지도`·`## 공통 규칙` 이 없으면(예: `/init` 이 만든 파일) 기존 내용 **아래에** 뼈대 두 절을 더한다. 기존 내용은 손대지 않는다
- 절이 없으면 `공통 규칙` 뒤에 제품·기술·구조·플랜·하네스·루프 순서의 자리에 더한다
- 전체 **100줄 안팎, 200줄을 넘기지 않는다.** 넘치면 규칙을 문서 쪽으로 돌려보내고 가리키는 줄만 남긴다

```markdown
# <프로젝트 이름>

> harness-loop-fullstack 스킬이 만들고 갱신하는 파일이다. 각 절은 그 레이어의 스킬만 고친다.
> `CLAUDE.md` 와 `AGENTS.md` 는 같은 내용이다. 한쪽을 손으로 고치면 다른 쪽도 같이 고친다.
> 세부 규칙은 각 문서에 있다 — 여기에는 어느 세션에서든 반드시 지킬 것만 둔다. 200줄을 넘기지 않는다.

## 문서 지도
- `docs/IDEA.md` → `docs/PRD.md` → `docs/TRD.md` → `docs/ARCHITECTURE/` → `plan_setup/` → `harness_setup/` → `loop_setup/LOOP.md`
- 뒤 문서는 앞 문서를 근거로 한다. 어긋나면 앞 문서가 이긴다 — 바꿔야 하면 사용자 확인 뒤 **가장 앞 문서부터** 고치고(버전·`변경 이력` 한 줄. 프로젝트 완료 뒤에는 `feature-add`·`refactor-plan` 의 후미 절로) 사이 문서를 맞춘 다음 이어 간다(변경 전파). 손으로 고칠 때도 같다. 루프 세션은 앞 문서를 고치지 않고 LOOP.md 대로 멈춘다
- 현재 단계: <마지막으로 끝낸 스킬> → 다음: <다음 스킬>

## 공통 규칙
- 앞 레이어의 **파일**만 입력이다. 대화 기억이나 추측으로 요구사항·기술 결정을 만들지 않는다
- ID(`FR-`·`NFR-`·`US-`·`OQ-`·`TD-`·`phase-NN-task-MM`)는 참조만 한다. 새 ID 는 마지막 번호 다음으로만 만든다 — OQ 는 프로젝트 전체(`HARNESS.md`·`LOOP.md` 의 미결 표까지)에서, 나머지는 그 문서에서 센다(변경 전파로 앞 문서에 더할 때도)
- 사용자가 말하지 않은 값은 `(가정)` 으로 표시한다. 모호하면 추측하지 말고 묻는다
- 요청된 범위를 조용히 넓히거나 줄이지 않는다. 범위 판단은 보고한다
```

`## 제품 (docs/PRD.md)` 절에는 이것만 적는다.

```markdown
## 제품 (docs/PRD.md)
- <한 줄 정의>
- P0 <n>개 · 차단 OQ: <ID 목록, 없으면 "없음">
- 범위 밖: <6절에서 핵심 2~3개>
- PRD 에 없는 기능을 만들지 않는다. 더하려면 PRD 와 9절 추적표를 먼저 고친다
```

## 6단계. 자체 점검 후 인계

파일을 쓴 뒤 처음부터 다시 읽으면서 아래를 확인한다. 방향이 헷갈리지 않도록 '통과 조건'을 그대로 적었다.

| 확인할 것 | 통과 조건 | 걸렸을 때 |
|---|---|---|
| 수용 기준 | 모든 FR에 있고, 전부 관찰 가능한 서술 | 고친다 |
| 실패 경로 | 실패 경로가 하나도 없는 FR이 0개 | 고친다. 단 계산 규칙처럼 실패 경로가 본래 없는 FR이면 그 사실을 보고한다 |
| 기술 선택 | 프레임워크·DB·라이브러리 이름이 본문에 0건 | 지우고 TRD로 넘긴다 |
| 스토리 연결 | 어떤 스토리에도 안 걸린 FR이 0개 | 정말 필요한 기능인지 다시 보고, 애매하면 보고한다 |
| P0 비중 | 전체의 절반 이하 | 임의로 줄이지 말고 후보와 함께 사용자에게 보고한다 |
| 미결 처리 | IDEA.md의 미결이 전부 결정/가정/범위 밖/미결(OQ) 중 하나로 매핑됨 | 빠진 항목을 채운다 |
| 미결 형식 | 모든 미결에 ID·종류·기본값·되돌리기 비용이 있음 | 채운다 |
| 미결 개수 | 세 가지 필터를 통과한 것만 남음. 서로의 파생이 아님 | 가정으로 내리거나 상위 미결에 흡수한다 |
| 9절 두 열 | `차단 미결` 열의 OQ가 차단이면 `상태` 가 `정의됨 (차단)`, 아니면 `정의됨`. 어긋난 행 0개 (7·8단계로 이미 있는 PRD 를 고칠 때는 `폐기` 행과, 플랜이 이미 올려 둔 `계획됨` 행은 그대로 둔다 — `계획됨` 이면 괄호의 `(차단)` 만 맞춘다) | 맞춘다. Layer 3이 `상태` 열을 1순위 신호로 읽는다 |
| `CLAUDE.md` · `AGENTS.md` | 두 파일이 같고 `## 제품` 절이 갱신됐고 각 200줄 이하 | 자기 절만 고친다. 넘치면 규칙을 문서로 돌려보내고 가리키는 줄만 남긴다 |

**임의로 고쳐도 되는 것과 보고해야 하는 것이 다르다.** 형식 문제(수용 기준 누락, 기술명 혼입)는 고치면 된다.
범위 판단(P0 비중, 필요 없어 보이는 FR)은 사용자의 결정이므로 고치지 말고 보고한다.
여기서 조용히 범위를 줄이면, 사용자는 자기가 요청한 것이 빠진 줄 모른 채 다음 레이어로 넘어간다.

그다음 사용자에게 보고한다.

1. `docs/PRD.md` 를 만들었다는 사실과 요구사항 개수(FR n개, NFR n개, P0 n개)
2. **미결 사항 목록 — 차단(P0를 막는 것)을 맨 위에 둔다.** 이게 보고의 핵심이다. PRD는 사람이 검토하고 함께 고치라고 만드는 문서다.
   각 미결에 "답을 못 주시면 이 기본값으로 갑니다"를 함께 적어, 사용자가 지금 답하지 못해도 진행이 멈추지 않게 한다.
   그리고 **미결의 종류 분류가 잠정이라는 것과, 틀렸으면 바꿔 달라는 것을 함께 알린다.** 그다음 7단계로 하나씩 처리한다.
3. 자체 점검에서 걸렸지만 임의로 고치지 않은 것
4. 다음 단계 안내: "검토하시고, 괜찮으면 TRD로 넘어갈까요? (`trd-generator`)"

사용자 검토 전에 TRD로 넘어가지 않는다. PRD가 틀린 채로 넘어가면 그 뒤 모든 문서가 같이 틀린다.

## 7단계. 미결 해소 세션

PRD를 넘기고 끝이 아니다. 사용자가 검토를 시작하면 **미결을 하나씩 함께 처리해서, 여기서 최대한 태운다.**
한 번에 다 던지면 사용자는 앞의 두세 개만 답하고 나머지는 "일단 그렇게 하죠"가 된다. 그러면 미결을 만든 의미가 없다.

### 왜 여기서 태워야 하는가

미결 하나를 다음 레이어로 넘기면 비용이 하나로 끝나지 않는다. 레이어를 지날 때마다 불어난다.

```
PRD에 미결 1건 (전자서명 필요 여부)
  → TRD:      서명 저장·검증 방식을 정할 수 없어 인증·저장 설계에 분기가 생긴다
  → 아키텍처:  두 갈래를 다 감당하는 설계를 하거나, 한쪽으로 정하고 나중에 갈아엎는다
  → 플랜:      영향받는 FR 4개가 태스크 8~10개로 쪼개지는데 전부 blocked 로 시작한다
  → 루프:      blocked 태스크는 실행 순서에서 계속 밀리고, 의존하는 후속 태스크까지 막힌다
```

**PRD에서 5분이면 끝날 대화가, 플랜 단계에서는 태스크 10개의 재작성이 된다.**
지금 사용자 앞에 문서와 맥락이 다 있고 사용자의 주의도 여기 있다. 이만큼 싸게 결정할 수 있는 시점은 뒤에 없다.

그래서 목표는 "미결을 목록으로 잘 정리하는 것"이 아니라 **"이 세션이 끝났을 때 미결 개수를 최대한 줄이는 것"**이다.
차단 미결은 0개가 되어야 하고, 나머지도 '확인/실험 때문에 물리적으로 지금 못 푸는 것'만 남기는 것을 목표로 한다.
사용자가 피곤해하면 남겨도 되지만, 남길 때는 그것이 뒤에서 무엇을 막는지 알려주고 남긴다.

### 순서

**차단(P0를 막는 것) 먼저, 그다음 되돌리기 비용이 큰 순서**로 제시한다.
싼 것부터 처리하면 사용자의 집중력이 성공 지표 숫자 같은 데 소모되고, 정작 제품을 뒤집을 결정에 남는 게 없다.

### 한 항목을 제시하는 방법

```
OQ-001 (차단 · 질문으로 분류) — 전자서명을 이번 버전에서 빼도 될까요?

  왜 이걸 질문으로 봤는지: 사용자의 방침 결정이고, 외부 확인 없이 답할 수 있다고 판단했습니다.
  막고 있는 것: FR-006, FR-008, FR-009, FR-011 (전부 P0)
  답이 없으면: 뺀다 (PDF + 링크 공유까지)
  나중에 되돌리면: 인보이스 기능 전체가 다음 버전으로 밀립니다

  A) 뺀다   B) 동의 기록만 남긴다   C) 법적 효력 있는 서명이 필수다
  ─ 종류가 틀렸다면 그것부터 알려주세요. "이건 알아봐야 안다"거나 "지금 정하면 안 된다"면 답 대신 그렇게 말씀해 주시면 됩니다.
```

마지막 줄이 중요하다. 이 문장이 없으면 사용자는 **주어진 선택지 안에서만 답해야 한다고 느낀다.**
모르는 것도 찍게 만드는 건 결국 이 지점이다. 선택지를 거부할 길을 열어 두는 것이 분류 오류에 대한 진짜 안전망이다.

### 사용자가 종류를 바꾸면

종류가 바뀌면 그 항목의 나머지도 전부 다시 계산해야 한다. 종류는 라벨이 아니라 처리 방식을 결정하는 값이기 때문이다.

| 사용자가 이렇게 말하면 | 바뀌는 것 |
|---|---|
| "그건 알아봐야 알아" → **확인** | 선택지를 치운다. 누가 무엇을 언제까지 확인할지 적는다. 기본값은 유지하되 "확인 전 잠정"으로 표시 |
| "해봐야 알지" → **실험** | 스파이크로 전환. 무엇을 만들어 무엇을 보면 판정되는지 적는다. Layer 3에서 검증 태스크가 된다 |
| "지금 정하면 틀려" → **유예** | 재검토 시점과 그때 볼 근거를 적는다. 그때까지 영향받는 FR을 P1 이하로 내릴지 사용자에게 확인한다 |
| "그건 안 할래" → **범위 밖** | 미결에서 빼고 6절로 옮긴다. 관련 FR을 삭제하거나 P2로 내린다 |
| "그게 왜 문제가 되지?" → **불필요** | 미결을 지운다. 물어볼 필요가 없었던 것이다 |

마지막 줄을 가볍게 보지 않는다. **미결이 애초에 필요 없었던 경우가 실제로 자주 있다.**
사용자가 이미 답한 것을 못 알아들었거나, 다른 결정에 자동으로 딸려 오는 것이었거나,
업계에서 답이 정해져 있는 것을 모델이 몰랐던 경우다. 이럴 때는 억지로 결정으로 만들지 말고 그냥 지운다.
지운 미결은 관련 FR의 `차단 미결`도 함께 '없음'으로 되돌린다.

바뀐 내용은 **그 자리에서 PRD에 반영한다.** 대화에서만 합의하고 문서를 안 고치면, 다음 레이어는 옛날 문서를 읽는다.

### 처리 결과별 문서 갱신

- **결정됨** → 미결 표에서 제거하고 '확정된 가정'으로 옮기거나 FR에 직접 반영. 관련 FR의 `차단 미결`을 '없음'으로,
  9절의 `차단 미결` 열을 `—` 로, `상태` 를 `정의됨` 으로 함께 되돌린다(플랜이 이미 `계획됨 (차단)` 으로 올려 둔 행이면 `계획됨` 으로 — 괄호만 뗀다)
- **확인/실험으로 재분류** → 미결 표에 남기되 해소 방법과 담당·시점을 채운다. 관련 FR의 `차단 미결`은 그대로 둔다
- **유예** → 기본값으로 진행하고, 재검토 시점을 적는다

### 세션을 마칠 때

남은 미결을 한 번 더 훑고 사용자에게 이렇게 정리해 준다.

- 처리한 것: 결정 n건, 재분류 n건, 불필요로 삭제 n건, 범위 밖으로 이동 n건
- 남은 것: 각각이 **뒤에서 무엇을 막는지**와 함께. ("OQ-007이 남으면 계약서 템플릿 태스크 3개가 blocked로 시작합니다.")
- 남은 미결의 해소 담당과 시점

이 요약을 PRD 8절에도 반영해서, 다음 레이어가 문서만 보고도 무엇이 열려 있는지 알게 한다.

### 언제 멈추는가

미결이 다 풀리지 않아도 TRD로 넘어갈 수 있다. **단 하나의 조건은 차단 미결이 남아 있지 않은 것**이다.
차단 미결은 P0 요구사항의 존재 근거를 흔드는 것들이라, 그 위에 기술 설계를 얹으면 설계를 통째로 다시 하게 된다.
확인·실험 종류라 지금 당장 못 푸는 차단 미결이 있다면, 사용자에게 두 가지 중 하나를 고르게 한다.

1. 확인/실험을 먼저 하고 그 결과를 기다린다
2. 기본값으로 진행하되, 되돌리기 비용을 감수한다고 명시적으로 확인한다

임의로 2번을 선택하지 않는다. 되돌리기 비용을 치르는 건 사용자다.

## 8단계. 이미 `docs/PRD.md` 가 있을 때 — 부분 갱신

PRD 는 한 번 쓰고 끝나지 않는다. 뒤 레이어가 쓰는 동안 **요구사항을 바꿔야 하는 결정**이 나온다 — 아키텍처의 충돌(CF) 해소가 NFR 수치를 조정하거나,
TRD·설계가 PRD 에 없는 요구사항을 필요로 하거나("설계 유발"), 사용자가 설계를 시키면서 "이것도 넣어줘"라고 하거나, 하네스가 관찰할 수 없는 수용 기준을 발견한다.
그 결정이 PRD 에 안 돌아오면 뒤 문서마다 같은 모순을 다시 경고하고, 루프는 옛 수용 기준으로 검증한다. 이 단계가 그 결정을 받는다.

**불린 자리에 따라 셋으로 나뉜다.**

- **다른 스킬이 불렀다(변경 전파)** — 결정은 이미 사용자가 그 스킬에서 내렸다. 여기서는 그 결정을 PRD 형식으로 기록하고 돌아간다. 다만 기록하려면 **새 결정이 더 필요한 경우**가 많다 — "이것도 넣자"로 생긴 FR 의 수용 기준·우선순위, 범위에 새로 들어온 기능의 실패 경로. 그것은 2~4단계 규칙대로 사용자에게 묻고(답을 받기 전에는 쓰지 않는다) 채운다. 뒤 문서 연쇄는 부른 스킬이 한다. `CLAUDE.md` 의 `현재 단계` 줄은 건드리지 않는다 — 단계가 바뀐 것이 아니다
- **사용자가 직접 불렀다**("요구사항 바꾸자", "FR-003 수용 기준 고쳐줘") — 프로젝트가 완료됐으면(`STATE.md` 의 `Phase Overview` 가 전부 `completed`) 이 단계로 본문을 고치지 않고 `feature-add`(요구 변경)·`refactor-plan`(기술·구조 변경)으로 안내한다 — 완료 뒤에는 후미 절로 반영하는 것이 원본 규칙이다. 아니면 바꿀 것을 2~4단계 규칙대로 사용자와 정하고, 끝에 아래 "뒤 문서 맞추기"까지 한다
- **Layer 6(`feature-add`)이 후미 절 모드로 불렀다** — 그 지시가 우선이다. 본문을 고치지 않고 `## 추가 N` 절에 적는다(대체한 항목의 제목 아래 `> 대체됨 — '## 추가 N' (날짜)` 한 줄만 예외). 아래 규칙 중 번호·추적표·버전은 그대로 적용하고(Layer 6 후미 절 모드면 `변경 이력` 줄은 쓰지 않고 버전만 올린다 — 후미 절 첫 줄(날짜·요청·ID)이 이력이다), 뒤 문서는 부른 스킬이 순서대로 부르므로 여기서 부르지 않는다

**지킬 것.**

- **바뀐 항목만 고친다.** 파일을 통째로 다시 쓰지 않는다. 사용자가 손으로 고친 문장이 있다
- **ID 는 유지한다.** 새 FR·NFR·US·OQ 는 **마지막 번호 다음**(OQ 는 프로젝트 전체 — TRD·아키텍처·`HARNESS.md`·`LOOP.md` 의 미결 표까지 — 에서 마지막 번호 다음). 없어진 요구사항은 지우지 않고 `폐기 — 대체: FR-0xx`(대체가 없으면 `폐기 — (이유)`)로 표시한다 —
  TRD 추적표·설계 단위·태스크가 그 번호를 가리키고 있어, 지우면 뒤 문서의 참조가 허공을 가리킨다
- 수용 기준을 바꾸면 3단계 규칙(관찰 가능·실패 경로 하나 이상·숫자)을 그대로 지킨다. 바뀐 기준 줄 끝에 `(0.2 변경)` 을 붙여 뒤 레이어가 어느 줄이 새것인지 알게 한다
- 풀린 미결은 7단계 "처리 결과별 문서 갱신" 그대로 옮긴다. 옮긴 자리에 `(OQ-007 해소)` 를 남겨 루프의 차단 해소가 찾을 수 있게 한다
- **9절 추적표를 함께 맞춘다** — 새 FR 은 행을 더하고 `상태` 는 `정의됨`(차단이면 `정의됨 (차단)`), `담당 태스크` 는 비운다(플랜이 채운다). 폐기한 FR 은 `상태` 를 `폐기` 로
- **버전을 올리고 `변경 이력` 에 한 줄** — `0.2 (YYYY-MM-DD, <부른 스킬>) — <무엇을 왜>. 영향: <TRD·설계·태스크의 ID·절>`.
  뒤 문서는 `입력 문서` 에 PRD 버전을 적어 두었으므로, 이 줄이 뒤 스킬이 "무엇이 낡았는가"를 찾는 출발점이다
- 범위가 바뀌었으면(MVP 포함/제외, 타깃, 핵심 흐름) `idea-brainstorm` 7단계로 IDEA.md 도 맞춘다. 반대로 IDEA 버전이 머리의 `입력 문서` 버전보다 높으면 IDEA 의 `변경 이력` 에서 그 뒤 줄을 읽어 PRD 부터 맞춘다
- 6단계 자체 점검 중 바뀐 항목에 걸리는 행만 다시 돌린다

**뒤 문서 맞추기(사용자가 직접 불렀을 때. `idea-brainstorm` 7단계가 연쇄를 시작해 이 단계를 불렀으면 그 세션이 같은 순서로 한다).** 뒤 문서가 이미 있으면 앞에서 뒤 순서로 그 레이어의 갱신을 이어서 부른다 —
TRD(바뀐 FR·NFR 이 근거인 TD 가 있을 때만 `trd-generator` 9단계) → 아키텍처(`architecture-generator` 9단계) → 플랜(`plan-generator` 10단계) → 하네스(`harness-update`) → 루프(`loop-update`, DAG 가 바뀔 때).
각 스킬이 자기 승인 규칙(완료 태스크 불변, 하네스 약화의 승인)을 지킨다. **루프가 도는 중(`STATE.md` 의 `Phase Overview` 에 `in_progress`)이면 플랜부터는 부르지 않고** 무엇이 낡았는지 보고한다 — 그 문서들의 필자는 루프다.
보고에는 `앞 문서 반영`·`뒤 문서 반영` 묶음(문서·새 버전·바뀐 ID)을 둔다.

---

## 에이전트별 참고

- Claude Code에서 실행 중이면: `references/claude-code.md`
- Codex에서 실행 중이면: `references/codex.md`