git:20261012.aa46794 to git:20261029.9a25015

- 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`