쓰기 전에 묻고, 쓴 뒤에 의심한다 — product-spec-harness
기획안에서 인수조건까지: product-spec-harness
product-spec-harness는 기획자(PM)가 요구·문제나 기획안 초안을 가지고 제품 기획문서(PRD) → 사용자 스토리 → 인수조건을 단계별로 작성하고 검증하도록 돕는 Claude Code 플러그인입니다. 개발 착수 전 단계의 기획 산출물에만 집중하고, 특정 도메인에 묶이지 않으며, 다른 플러그인 없이 단독으로 동작합니다.
7월에 처음 소개했을 때는 PRD와 사용자 스토리를 만드는 5단계 하네스였습니다. 그 뒤로 꽤 많이 바뀌었습니다.
- PRD를 한 에이전트가 한 번에 쓰던 방식을 계획 → 설계 → 비평 루프로 바꿨습니다.
- 사용자 스토리 다음에 인수조건(Given-When-Then) 단계와 두 번째 검증을 붙여 5단계가 7단계가 됐습니다.
- 점검 결과를 보여 주고 끝내던 자리에, 문서를 만들기 전에 답을 받아 반영하는 보완 문답을 넣었습니다.
- 문서를 만든 뒤 기획안이 바뀌면 닿는 범위만 다시 갱신하는 재갱신 경로를 만들었습니다.
- 만드는 파일을 딱 네 개로 줄였습니다.
이 글은 지금 버전을 처음부터 다시 설명합니다.
✍️ 한 줄 요약
기획 문서의 빈칸을 에이전트가 그럴듯한 숫자와 정책으로 채우는 순간, 그 발명은 합의된 적 없는 요구사항이 되어 개발까지 내려갑니다. 이 하네스는 문서를 쓰기 전에 빈칸을 묻고, 쓰는 동안 출처를 캐묻고, 쓴 뒤에는 문서 사이의 연결을 두 번 의심합니다. 그래도 남은 빈칸은 메우지 않고 '확인 필요'로 드러냅니다.
왜 이런 모양이 되었나
모호함은 나중에 재작업으로 돌아온다
"빠르게", "쉽게", "적절히" 같은 표현은 구현자와 QA에게 서로 다른 해석을 남기고, 그 차이는 QA 막바지나 출시 후 재작업으로 청구됩니다. 요구공학 연구에서도 불완전하거나 숨은 요구사항은 가장 많이 지목되는 문제입니다(NaPiRE 설문 응답자 228명 중 109명, Méndez Fernández 외 2017). 그래서 이 하네스는 문서를 만드는 것보다 만들기 전에 무엇이 비어 있는지 드러내는 것에 더 많은 단계를 씁니다.
에이전트는 빈칸을 그냥 두지 않는다
기획안에는 예외 흐름이 거의 없습니다. "이미 가입된 이메일이면?", "네트워크가 끊기면?" 같은 질문에 답이 적혀 있는 기획안은 드뭅니다. 그런데 에이전트에게 PRD를 쓰라고 하면 이 자리를 아주 자연스러운 문장으로 채웁니다. "중복 이메일이면 로그인 화면으로 안내한다." 읽기에는 그럴듯하지만, 누구도 합의한 적 없는 제품 정책입니다. 이 문장은 스토리가 되고 인수조건이 되고 결국 코드가 됩니다.
그래서 이 하네스 전체를 관통하는 규칙은 발명 금지입니다. 기획안이나 사용자 답변에 없는 수치·정책은 채우지 않고 '확인 필요' 표시로 남깁니다. 빈칸을 보여 주는 것은 하네스의 일이고, 빈칸을 채우는 결정은 기획자의 일입니다.
전체 흐름
| 단계 | 하는 일 | 맡는 에이전트 |
|---|---|---|
| Phase 0 문제 정의 | 문제·대상 사용자·목표·제약·성공지표 다섯 칸의 문제 정의 카드를 만든다 | requirements-analyst |
| Phase 1 기획 완성도 점검 | 원본 기획안이 착수 가능한 상태인지 진단하고 보완할 점 점검표를 낸다 | dor-evaluator |
| Phase 1.1 보완 문답 | 문서를 만들기 전에 미충족 항목을 하나씩 묻는다 | (오케스트레이터) |
| Phase 2 PRD 작성·확정 | 계획 → 설계 → 비평 루프를 돌아 PRD를 확정한다 | prd-planner, prd-designer, prd-critic |
| Phase 3 사용자 스토리 | 요구사항을 스토리로 풀고 요구별 연결 표를 붙인다 | story-writer |
| Phase 4 1차 검증 | PRD와 스토리 사이를 적대적으로 검증한다 | spec-reviewer |
| Phase 5 인수조건 | 스토리마다 Given-When-Then 시나리오를 쓴다 (최종 산출물) | acceptance-writer |
| Phase 6 2차 검증 | 스토리와 인수조건 사이를 적대적으로 검증한다 | spec-reviewer |
| 마무리 | 재갱신 경로, 점검 결과 저장, 산출물 요약 | (오케스트레이터) |
여덟 개 에이전트가 나눠 맡고, 오케스트레이터 스킬이 순서를 잡습니다. 모든 단계는 산출물을 보여 주고 승인을 받은 뒤에만 다음으로 넘어가며, 파일은 쓰기 전에 전체 미리보기를 보여 줍니다. 한 번에 한 가지씩 인터뷰하듯 묻고, 어려운 용어에는 쉬운 말 한 줄 정의를 붙입니다. 예를 들어 DoR은 '기획 완성도 점검', INVEST는 '좋은 스토리 6가지 기준', Given-When-Then은 '조건·행동·결과'로 풀어서 원어와 함께 씁니다. 기획자가 읽는 문서이기 때문입니다.
세 가지 시작 방식
시작할 때 입력을 보고 모드를 하나 정해 채팅에 선언합니다.
- 재갱신 모드 — 이미 만든 문서가 있고 "기획안 보완했어, 문서 갱신해줘"라고 하면, 처음부터 다시 돌지 않고 재갱신 경로로 바로 들어갑니다. 이 판별을 가장 먼저 합니다.
- 기획안 모드 — 기획안 초안을 주면 그 안에서 문제 정의를 뽑아내고, 문서를 만들기 전에 기획 완성도 점검을 거칩니다.
- 인터뷰 모드 — 기획안이 없으면 한 번에 한 질문으로 문제를 정의합니다. 평가할 원본이 없으므로 완성도 점검은 건너뜁니다.
경계가 애매하면 기획안 모드로 둡니다. 초기 버전에서 기획안을 줬는데도 완성도 점검을 건너뛰고 곧장 PRD로 가는 결함이 있었기 때문에, 지금은 기획안 모드에서 "기획 완성도 점검을 먼저 할까요?"라는 질문을 절대 생략하지 않습니다. 사용자가 정하는 것은 점검을 실행할지뿐입니다.
문서를 만들기 전: 완성도 점검과 보완 문답
기획 완성도 점검
원본 기획안을 다섯 가지 관점으로 봅니다. 착수 가능 여부를 항목별로 판정하는 완성도 게이트, 좋은 스토리 6가지 기준(INVEST) 점수표, 조건·행동·결과로 쓸 수 있는지, 모호한 표현, 필요한 외부 계약·의존이 명시됐는지입니다. 실패한 항목에는 반드시 기획안의 해당 문장을 인용합니다.
6가지 기준 중 검증 가능성(Testable)이나 독립성(Independent)이 0점이면 총점과 상관없이 착수를 막습니다. 테스트할 수 없는 스토리는 완료를 정의할 수 없고, 독립적이지 않은 스토리는 다른 미정 사항에 묶여 시작조차 못 하기 때문입니다. 종합 판정은 '착수 가능 / 보완 후 착수 / 착수 보류' 세 단계입니다.
결과의 핵심은 보완할 점 점검표입니다. 충족한 항목은 체크하고, 미충족 항목 아래에는 "이렇게 보강"이라는 Before → After 예시를 붙입니다. 예를 들어 "빠르고 쉽게"라는 표현에는 "입력 단계 수나 전환율처럼 관찰 가능한 기준으로 바꾸되, 임계값은 기획이 정한다"는 식입니다. 예시는 형식만 보여 줄 뿐 값을 정해 주지 않습니다.
이 점검이 하네스 전체에서 유일하게 점수를 매기는 곳입니다. 그리고 그 점수는 처음 평가할 때 한 번만 유효합니다. 기획안을 보완한 뒤 다시 점수를 매기면 두 점수의 차이가 '성숙도'처럼 읽히는데, 이 하네스는 그런 등급을 만들지 않습니다.
보완 문답: 하나씩, 언제든 건너뛸 수 있게
9월 초까지는 점검표를 보여 주고 끝이었습니다. 보강점을 알려 줘도 기획자가 답할 자리가 없으니, 결국 다음 단계에서 에이전트가 빈칸을 추측하게 됐습니다. 그래서 지금은 점검표를 보여 준 직후, PRD·스토리·인수조건 중 어느 것도 만들기 전에 세 가지 중 하나를 고르게 합니다.
- 하나씩 답하기 — 미충족 항목을 한 개씩 묻습니다. 질문마다 '건너뛰기'와 '전부 건너뛰기'를 줍니다.
- 보완 없이 진행 — 미충족 항목을 모두 건너뛴 것으로 기록하고 PRD로 갑니다.
- 나중에 보완 — 문서를 먼저 만들고, 나중에 재갱신 경로로 반영합니다.
이 질문은 원래 있던 단계 종료 승인을 대체하므로 승인 횟수는 늘지 않습니다.
답변은 정해진 다섯 가지로만 처리합니다. 내용을 답하면 '응답'으로 원문 그대로 보관하고 곧바로 다음 항목으로 갑니다. 중간 요약이나 "계속할까요?"는 끼워 넣지 않습니다. '건너뛰기'나 "모름", "나중에"는 되묻지 않고 '건너뜀'으로 기록합니다. '전부 건너뛰기'는 남은 항목을 한꺼번에 건너뜀으로 처리합니다. "알아서", "예시대로"처럼 채울 값이 특정되지 않는 모호한 답에는 확인 질문을 딱 한 번만 하고, 그래도 모호하면 건너뜀으로 넘깁니다. 끝없이 되묻지 않습니다.
중요한 규칙은 건너뜀을 '보완됨'으로 올리지 않는다는 것입니다. 건너뛴 항목은 PRD와 인수조건에 '확인 필요'로 그대로 실려 나갑니다. 진척도 '응답 몇 건, 건너뜀 몇 건'처럼 건수로만 보여 줍니다.
건너뛴 항목이 하나라도 있으면 점검 결과를 파일로 저장할지 이 자리에서 묻습니다. 건너뜀 기록은 그 파일에만 남기 때문에, 마지막까지 미뤘다가 저장을 거절하면 기록이 사라집니다. 건너뜀이 없으면 원래대로 마무리에서 묻습니다.
PRD: 계획 → 설계 → 비평 루프
PRD를 한 번에 쓰지 않고, 세 에이전트가 섹션을 나눠 소유합니다.
계획: 무엇을, 왜, 어디까지
계획 에이전트는 PRD의 앞 세 섹션, 즉 배경·문제, 목표·성공지표, 범위(In/Out)를 씁니다. 두 가지는 필수입니다. 첫째, 범위 Out을 반드시 적습니다. Out이 비어 있으면 모든 것을 In으로 오해하게 되므로, 이번 범위와 헷갈릴 만한 인접 기능을 Out에 박아 둡니다. 둘째, 성공지표는 관찰 가능해야 합니다. 서로 다른 두 사람이 같은 데이터를 보고 같은 참/거짓 결론을 내릴 수 있어야 하고, 기준선·목표값·측정 시점이 필요합니다. 그 값을 모르면 지어내지 않고 질문 후보로 돌려보냅니다.
설계: 기획 설계이지 기술 설계가 아니다
설계 에이전트는 나머지 세 섹션, 즉 핵심 요구사항, 가정·리스크, 마일스톤을 씁니다. 여기서 '설계'는 기술 설계가 아니라 기획 설계입니다. 열두 가지 점검 항목마다 '적을 것'과 '적지 않을 것'을 짝으로 둡니다.
- 요구사항은 한 문장에 하나씩 쪼개고 FR·NFR 번호를 붙입니다. 이 번호는 뒤 단계가 참조하는 주소가 됩니다.
- 비기능 요구는 "얼마나 잘"의 관찰 가능한 임계값을 적고, 그걸 어떻게 달성할지(캐시, 인덱스, 비동기 처리)는 적지 않습니다.
- 상태와 전이는 "각 상태에서 사용자에게 무엇이 참인가"를 적고, 상태관리 라이브러리나 구현 방식은 적지 않습니다.
- 필요한 정보 항목은 "무엇을 받고 무엇을 보여 주는가"를 적고, 테이블·컬럼·타입은 적지 않습니다.
- 권한은 역할 × 허용 행위 표로 적고, 인증 방식이나 토큰은 적지 않습니다.
- 예외는 최소 다섯 종류(중복 입력, 자격 미달, 권한 없음, 데이터 없음, 외부 지연·실패)를 봅니다. 예외 흐름은 원본에 거의 없어서 발명이 가장 쉽게 일어나는 자리이므로, 규칙이 없으면 '해당 없음 — 기획 확인 필요'로 남깁니다.
각 가정에는 그 가정이 깨졌을 때 흔들리는 요구 번호를 연결하고, 각 마일스톤에는 포함 요구 번호와 관찰 가능한 완료 기준을 붙입니다.
비평: 고칠 권한도, 막을 권한도 없다
비평 에이전트는 이번 회차 초안을 읽기 전용으로 받아 일곱 개의 렌즈로 훑습니다. 문제와 목표가 이어지는가, 범위 경계가 분명한가, 지표를 관찰할 수 있는가, 요구가 빠짐없이 쪼개졌는가, 예외 공백이 있는가, 모든 수치와 정책에 출처가 있는가, 그리고 완성도 점검의 보강점과 보완 문답 답변이 실제로 반영됐는가입니다. 렌즈 밖의 지적은 하지 않고, 원문 인용이 없는 지적은 버리며, 회차당 지적은 최대 12건입니다. 버리거나 자른 건수는 반드시 보고합니다. 조용히 지우면 "전부 봤다"로 읽히기 때문입니다.
지적마다 어떻게 해소되는 종류인지를 분류합니다.
- A — 문서 안에서 해소 가능. 구조, 중복, 번호, 문장 문제입니다. 다음 회차에 그 섹션 담당이 고칩니다.
- B — 사용자만 아는 사실이 필요. 수치, 정책, 기한입니다. 고치지 않고 '확인 필요'로 남겨 질문으로 보냅니다.
- C — 이번 범위 밖. 가정·리스크로 옮기자고 제안하고 끝냅니다.
B를 A로 처리하는 것이 곧 발명입니다. 이 분류가 없으면 다음 회차에 누군가 빈칸을 그럴듯한 숫자로 메웁니다.
'차단' 등급은 네 가지 경우에만 줄 수 있습니다. 범위 Out이 비었을 때, 판정할 수 없는 성공지표가 남았을 때, 요구 번호가 빠지거나 겹치거나 범위 In 항목이 요구로 전개되지 않았을 때, 출처 없는 수치·사실이 남았을 때입니다. 모두 문서만 보고 예/아니오로 판정할 수 있는 성질입니다. 비평은 이 밖의 새 차단 사유를 만들 수 없습니다.
이 목록을 닫아 둔 데는 대가가 있습니다. 비평 역할은 구조상 "결함 0건"을 내기 어려워서, 회차마다 새 차단이 생기면 루프가 끝나지 않습니다. 목록을 닫아 종료를 보장한 대신, 목표와 요구가 정면으로 어긋나는 것처럼 주관적 판단이 필요한 중대 결함은 많아야 '수정 권고'에 머뭅니다. 결함을 잡는 힘과 루프가 끝난다는 보장을 맞바꾼 설계이고, 그런 항목은 '최우선 권고 3가지'에 올려 눈에 띄게 합니다.
그리고 비평에는 거부권이 없습니다. 문서를 직접 고치지 못하고, 차단 지적이 남아 있어도 사용자가 확정을 고르면 즉시 확정합니다. 남은 지적은 PRD 부록의 '알려진 제한사항'에 기록할 뿐, 그걸 이유로 진행을 막거나 재확인을 반복하지 않습니다. 위험은 알리되 감수할지는 사용자가 정합니다.
회차가 끝날 때마다 사용자는 셋 중에서 고릅니다. 이대로 확정, 한 번 더 다듬기, 특정 항목만 지정해 수정. 하네스는 권장안과 각 선택의 비용(몇 개 에이전트를 다시 부르는지)을 함께 보여 줍니다. 남은 차단이 전부 B 분류라면, 회차를 더 돌아도 해소되지 않으니 질문으로 풀거나 모르는 채로 확정하라고 권합니다. 같은 지적이 같은 자리에서 반복되면 회차를 더 권하지 않습니다. 그래도 사용자가 한 번 더를 고르면 경고 한 줄만 붙이고 따릅니다.
이 루프가 "PRD 품질을 높인다"고는 주장하지 않습니다. 초안을 쓴 쪽과 비평하는 쪽이 같은 맥락을 읽기 때문입니다. 정직하게 주장할 수 있는 것은 하나입니다. 지적과 그 처리 결과(반영, 질문, 수용)가 문서에 남는다. 회차 이력은 변화의 기록이지 개선의 증거가 아닙니다.
스토리와 인수조건: 문장은 한 곳에만
스토리에는 인수조건 문장을 쓰지 않는다
사용자 스토리는 "…로서 …하고 싶다, 왜냐하면 …" 형식으로 쓰고, 각 스토리에 좋은 스토리 6가지 기준 자가점검과 어떤 요구를 충족하는지 표시를 붙입니다. 여기서 중요한 변화가 있습니다. 예전에는 스토리 문서 안에 수용기준(Given-When-Then)을 같이 적었는데, 지금은 스토리 문서에 조건·행동·결과 문장을 쓰지 않습니다. 대신 "이 스토리는 중복 이메일, 형식 오류, 네트워크 실패 흐름을 덮어야 한다"는 인계 메모만 남깁니다.
이유는 단순합니다. 같은 문장이 두 문서에 있으면 '완료 기준'이 두 개가 되고, 한쪽만 고쳐지는 순간 어느 쪽이 맞는지 알 수 없게 됩니다. 그래서 인수조건 문장은 인수조건 문서 한 곳에만 둡니다.
인수조건이 최종 산출물이다
인수조건 에이전트는 스토리마다 시나리오를 씁니다. 인수조건 하나에는 관심사 하나만 담고, Then은 제3자가 관찰로 통과/실패를 판정할 수 있어야 합니다. "잘 된다", "적절히 안내한다" 같은 문장은 금지입니다.
정상 흐름만 있는 인수조건은 미완성으로 봅니다. 스토리마다 여섯 가지 흐름을 확인합니다. 정상, 경계(최소·최대, 동시 요청, 중복 제출), 에러(외부 실패, 검증 실패), 빈 상태(데이터 0건), 권한(비로그인, 권한 없음, 세션 만료), 상태 전이(완료된 것 다시 처리, 중복 클릭)입니다. 해당하지 않는 흐름은 '해당 없음 — 사유'로 적어 누락이 아니라 의도된 제외임을 드러냅니다. 여기서도 흐름을 채우려고 정책을 지어내지 않습니다. 버그는 대부분 예외 흐름에서 새지만, 그 흐름의 정답을 정하는 건 기획입니다.
네 번의 점검은 서로 다른 질문을 한다
점검하는 단계가 넷이나 되면 같은 지적이 반복될 것 같지만, 넷이 같은 일을 하면 실패한 설계라고 보고 대상과 질문을 분리했습니다.
| 단계 | 읽는 것 | 묻는 질문 |
|---|---|---|
| Phase 1 완성도 점검 | 사용자가 준 원본 기획안 | 받은 것이 착수 가능한가 |
| Phase 2 비평 | 이번 회차 PRD 초안 | 쓴 계획이 스스로 옳은가 |
| Phase 4 1차 검증 | 확정된 PRD와 스토리 사이 | 요구와 스토리가 맞는가 |
| Phase 6 2차 검증 | 스토리와 인수조건 사이 | 스토리를 다 됐다고 판정할 수 있는가 |
1차 검증은 요구 ↔ 스토리 연결 표로 스토리가 없는 요구를 찾고, 6가지 기준 위반과 목표·요구·스토리 사이의 어긋남, 판정할 수 없는 문장을 찾습니다. 인수조건의 관찰성은 보지 않습니다. 그 시점에는 인수조건이 아직 없기 때문입니다. 2차 검증은 스토리 ↔ 인수조건 연결에서 빠진 것과 출처 없는 고아를 찾고, 관찰성·단일 관심사·흐름 커버리지를 보며, 빠진 시나리오를 캐냅니다.
두 검증 모두 칭찬형 코멘트는 하지 않고, 보완을 권할 때는 기존 항목을 뒤엎기 전에 추가를 먼저 제안합니다. 이미 합의된 것을 지키면서 빈 곳을 채우는 쪽이 비용이 싸기 때문입니다. 앞 단계가 이미 제시한 지적은 새 증거 없이 다시 꺼내지 않습니다.
문서를 만든 뒤: 닿는 범위만 다시 갱신하기
보완 문답에서 건너뛰었거나 '나중에 보완'을 골랐다면, 언젠가 기획안이 채워집니다. 그때 처음부터 다시 돌리면 이미 합의한 문장까지 바뀝니다. 그래서 재갱신 경로를 만들었습니다. 새 단계를 만드는 게 아니라 기존 단계를 지정한 범위로만 다시 부르는 방식입니다.
어디까지 다시 부를지 먼저 정한다
보완 내용마다 네 가지 라벨 중 하나를 붙이고, 사용자에게 재호출 범위를 먼저 승인받습니다.
- R-A — 요구가 늘거나 줄거나 의미가 바뀜, 범위 In/Out이 바뀜, 목표·지표가 바뀜, 스토리를 추가·분할·삭제해야 함. PRD → 스토리 → 인수조건을 모두 다시 봅니다.
- R-B — 예외 흐름의 정책·수치가 새로 정해지거나 바뀜. PRD의 예외 규칙 행과 인수조건만 고칩니다.
- R-C — 배경, 가정·리스크, 마일스톤 문구만 바뀜. PRD만 고칩니다.
- R-0 — 담당자나 일정 메모처럼 문서에 들어갈 자리가 없음. 기록만 합니다.
경계가 애매하면 위쪽 라벨로 올립니다. 낮게 잘못 판단하면 누락이 조용히 남고, 높게 잘못 판단하면 비용만 듭니다.
바뀐 블록만 돌려받는다
다시 부를 때 스토리·인수조건 에이전트는 '델타 모드'로 동작합니다. 기존 문서 전문과 고칠 범위, 보완 원문을 받고 바뀐 블록만 돌려줍니다. 전체를 다시 쓰게 하면 지정 범위 밖의 문장이 조용히 바뀌기 때문입니다. 돌려받은 블록을 기존 문서의 해당 위치에 끼워 넣는 일은 오케스트레이터가 하고, 파일을 쓰기 전에는 변경 요약과 함께 전체 미리보기를 다시 보여 줍니다. 스토리를 재조립해야 한다고 판단되면 바로 하지 않고 제안으로 돌려 승인을 받습니다.
번호는 주소다
요구·스토리·인수조건 번호(FR, US, AC)는 다른 문서와 티켓이 가리키는 주소이므로 재갱신해도 다시 매기지 않습니다. 새 항목은 지금까지 쓴 가장 큰 번호(삭제분 포함) 뒤에 붙이고, 삭제한 번호는 비워 둔 채 재사용하지 않습니다. 대가도 있습니다. 스토리가 쪼개지거나 지워지면 인수조건 번호의 앞자리가 현재 출처 스토리와 달라질 수 있습니다. 그래서 현재 출처는 번호가 아니라 각 인수조건에 적힌 출처 표시와 연결 표를 기준으로 봅니다. 주소가 흔들리지 않는 대신 번호만 보고 출처를 짐작하는 편리함을 포기한 것이고, 재갱신을 마칠 때 이 사실을 보고에 적습니다.
검증은 쌍으로, 반복은 끝이 있게
갱신을 마치면 번호를 기계적으로 대조해 스토리 없는 요구나 출처 없는 인수조건이 생기지 않았는지 봅니다. 다만 이건 오케스트레이터의 자기 보고일 뿐 검증이 아니므로, 1차·2차 검증을 대신하지 않습니다. 대신 한쪽이라도 바뀌면 그 쌍의 검증을 다시 돕니다. PRD나 스토리 중 하나가 바뀌면 1차를, 스토리나 인수조건 중 하나가 바뀌면 2차를 돕니다. 범위는 바뀐 곳과 그로 인해 어긋난 곳으로 좁히되, 요구가 삭제됐거나 범위 In/Out이 바뀌었거나 사용자가 원하면 전체를 봅니다.
끝없이 도는 것도 막습니다. 하네스가 스스로 재갱신을 제안하는 건 세션당 한 번뿐이고, 이번 보완이 직전 재갱신과 같거나 기존 기록과 달라진 문장이 없으면 돌지 않고 "이 입력으로는 더 바뀌지 않습니다"라고만 보고합니다. 반대로 사용자가 요청하는 재갱신에는 횟수 제한이 없습니다. 막는 것은 하네스의 자발적 반복이지 사용자의 요청이 아닙니다.
파일은 네 개뿐
이 하네스가 만드는 파일은 PRD, 사용자 스토리, 인수조건, 그리고 저장을 선택했을 때의 완성도 점검 결과, 이렇게 넷입니다. 재갱신을 여러 번 해도 늘지 않습니다.
예전에는 적대적 검증 리포트도 파일로 남길 수 있었습니다. 그런데 리포트가 파일로 쌓이니 어느 것이 합의된 산출물인지 흐려졌습니다. 검증은 산출물을 다듬기 위한 피드백이지 그 자체가 산출물이 아니므로, 지금은 검증 리포트를 채팅으로만 보여 주고 지적은 해당 문서에 흡수합니다. 비평 이력과 재갱신 이력은 PRD 부록에 남깁니다.
정직성 원칙
- 점수·백분율·성숙도 등급을 만들지 않습니다. 유일한 예외는 원본 기획안에 대한 6가지 기준 점수표와 세 단계 착수 판정이고, 그것도 보완 후 다시 매기지 않습니다. 커버율 대신 "요구 몇 건 중 미커버 몇 건"처럼 건수로 씁니다.
- 효과를 약속하지 않습니다. "비평 루프로 재작업 N% 감소" 같은 주장을 하지 않습니다. 측정하지 않았기 때문입니다.
- 수치와 사례를 지어내지 않습니다. 근거를 인용할 때는 출처 등급과 반대 증거를 함께 적습니다.
- 반영을 과장하지 않습니다. 사용자가 보완을 거절한 세션에서 "피드백이 문서에 흡수됐다"고 쓰지 않습니다.
- 알려진 한계를 숨기지 않습니다. 점검 결과 파일은 선택 저장이라 저장을 거절하면 항목 단위의 건너뜀 이력이 사라지고, 번호 고정의 대가로 인수조건 번호가 현재 출처와 달라질 수 있다는 점을 문서에 적어 둡니다.
사용 방법
설치
# 한 번에 설치 (Claude Code 2.1.275+)
/plugin install product-spec-harness --marketplace seungahhong/seungah-claude-plugins
# 또는 마켓플레이스 등록 후 설치
/plugin marketplace add seungahhong/seungah-claude-plugins
/plugin install product-spec-harness@seungah-claude-plugins부르기
슬래시 명령으로 부르거나 자연어로 요청합니다.
/product-spec-harness:product-spec신규 사용자가 이메일로 가입하게 해줘. 가입이 빠르고 쉬웠으면 좋겠고,
가입 후 바로 서비스를 둘러볼 수 있게. 이걸로 PRD랑 사용자 스토리 만들어줘."PRD 만들어줘", "사용자 스토리 도출해줘", "인수조건을 Given/When/Then으로 정리해줘", "기획안 보완했어 문서 갱신해줘" 같은 요청에도 발동합니다. 화면 구현이나 기술 설계, 코드 작성, 이미 완성된 문서를 검수만 하는 요청에는 발동하지 않습니다.
1. 문제 정의 카드 확인
기획안에서 다섯 칸을 뽑아 보여 주고, 비어 있는 칸만 묻습니다.
## 문제 정의 카드
- problem: 가입 절차가 번거로워 신규 사용자가 첫 경험 전에 이탈
- target_users: 결제 전 제품을 둘러보려는 신규 방문자
- goals: (비즈니스) 가입 전환율 향상 / (사용자) 부담 없는 빠른 가입
- constraints: (미정 — 확인 필요)
- success_metrics: (미정 — 관찰형으로 확인 필요)2. 완성도 점검과 보완 문답
점검표를 보여 준 뒤, 문서를 만들기 전에 보완 방식을 고르게 합니다.
PRD·사용자 스토리·인수조건은 아직 만들지 않았습니다. 만들기 전에 원본 기획안을 보완하시겠어요?
(1) 하나씩 답할게요 (권장)
(2) 보완 없이 이대로 진행
(3) 나중에 보완(1)을 고르면 이런 질문이 항목 수만큼 이어집니다.
[보완 1/3] 점검표 항목: "정상 흐름 외 경계·에러·빈 화면·권한 흐름이 기술됐다"
현재: 해당 서술 없음
↳ 보강 예시: "이미 가입된 이메일 / 형식 오류 / 네트워크 실패" 시 각각 무엇을 보여줄지 1줄씩
정해 두신 내용이 있으면 적어 주세요. ('건너뛰기' / '전부 건너뛰기')3. PRD 회차마다 고르기
비평 결과와 함께 선택지가 나옵니다.
[Phase 2 · 1회차] 지적 {차단 1건 / 수정권고 1건 / 참고 0건}
권장: (1) — 남은 차단이 전부 사용자만 아는 값이라 회차를 더 돌려도 해소되지 않음
(1) 이대로 확정 (2) 한 번 더 다듬기 (3) 특정 항목만 지정해 수정확정하면 전체 미리보기를 보여 준 뒤 PRD 파일을 씁니다. 이후 스토리 → 1차 검증 → 인수조건 → 2차 검증도 같은 방식으로 승인하며 진행합니다.
4. 결과물
.claude/_docs/<기획서 슬러그>/
PRD.md
user-stories.md
acceptance-criteria.md # 최종 산출물
product-spec-review.md # 저장을 선택한 경우에만5. 나중에 보완했다면
같은 세션이든 다음 세션이든 이렇게 말하면 재갱신 경로로 들어갑니다.
기획안 보완했어, 문서 갱신해줘. 중복 이메일이면 로그인 화면으로 보내고, 네트워크 실패는 재시도 버튼.하네스는 보완 내용마다 라벨과 다시 부를 범위를 표로 보여 주고 승인을 받은 뒤, 닿는 문서만 고칩니다.
날짜로 본 변화
| 날짜 | 바뀐 것 |
|---|---|
| 2026-06-13 | 신설 — PRD·사용자 스토리를 만드는 4단계 인터랙티브 하네스 |
| 2026-06-17 | 기획안 입력, 생성 전 기획 완성도 점검 내재화, 점검을 건너뛰던 결함 수정 |
| 2026-06-21 | 기획자용 용어 순화, 점검표 형식 변경, 산출물 위치를 기획서별 폴더로 |
| 2026-09-02 | PRD를 계획 → 설계 → 비평 루프로, 요구·스토리 번호 체계 통일 |
| 2026-09-02, 09-03 | 인수조건 단계와 2차 검증 추가(7단계), 인수조건 문장 단일화, 산출 파일 4개로 고정 |
| 2026-09-04 | 생성 전 보완 문답, 생성 후 재갱신 경로, 번호 고정 |
| 2026-10-18 | 스킬 설명 축약, 재갱신 경로를 별도 참고 문서로 분리 |
돌아보면 변화의 대부분은 두 방향이었습니다. 하나는 빈칸이 발명으로 채워지는 경로를 막는 것(처리 분류, 건너뜀 유지, 출처 감사, 델타 모드)이고, 다른 하나는 루프가 반드시 끝나게 하는 것(닫힌 차단 목록, 거부권 없음, 정체 가드, 재갱신 종료 조건)입니다. 둘은 자주 부딪혔고, 그때마다 무엇을 포기했는지를 문서에 적는 쪽을 택했습니다.
마무리
기획 문서를 에이전트가 쓰게 하면 빠르고 매끄럽습니다. 문제는 그 매끄러움이 빈칸을 가린다는 점입니다. 이 하네스는 오히려 문서를 덜 매끄럽게 만듭니다. '확인 필요'가 곳곳에 남고, 비평 지적이 부록에 남고, 건너뛴 항목이 기록에 남습니다. 하지만 개발이 시작된 뒤 "이 정책 누가 정했어요?"라는 질문을 받는 것보다는, 기획 단계에서 빈칸을 마주하는 쪽이 훨씬 싸다고 생각합니다.
여기서 나온 인수조건은 test-layering-harness가 받아 계층별 테스트로 바꿉니다. 인수조건 번호가 그대로 테스트 제목에 붙기 때문에, 번호를 주소로 고정한 결정이 테스트까지 이어집니다.