TDD Plan Input Skill

/tdd-plan이 단계 1(도메인 규칙 + User Story)부터 바로 시작할 수 있도록, 요구사항 원천 문서를 사용자와의 질의응답으로 완성하는 스킬입니다.

메인 컨텍스트에서 인터랙티브하게 실행합니다 — 질의응답이 이 스킬의 본질이므로 서브에이전트에 위임하지 않습니다.

GOAL

• 성공 = §1~§6 + 용어집을 갖춘 <topic>-plan-input.md가 생성되고, 모든 예제 수치가 사용자가 계산한 값이며, 완성형 User Story·Gherkin·unit test 목록이 문서에 없음
• 입력: 주제 한 줄, 또는 기존 자료(메모·스펙·이슈) 경로
• 출력: tdd-plan 단계 1a/1b/2가 소비하는 구조(§1~§6)를 갖춘 요구사항 원천 문서
• 종료 시 다음 단계 안내 — /tdd로 템플릿 생성 후 /tdd-plan 실행 시 이 문서를 참조로 전달 (인자로 주지 않는다 — 단계 7 참조)

CONSTRAINTS

Hard Rules

1. 재료까지만 — 완성형 금지

완성형 User Story(As a / I want / So that 형식), Gherkin 시나리오, unit test 목록을 이 문서에 쓰지 않는다. 그 형식화는 tdd-plan이 사용자 피드백(INVEST 점검, 핵심 예시 선정)을 받으며 하는 일이다. 미리 쓰면 그 피드백 루프를 건너뛰게 된다.

• §3은 "역할 / 원하는 것 / 얻는 가치" 표까지만 — 문장으로 조립하지 않는다
• §4는 경계 후보 나열까지만 — Gherkin Examples 표를 만들지 않는다

2. 예제 수치의 정본은 사람 계산

예제의 기대값은 사용자가 직접 계산해 확인한 값만 정본이다.

• 스킬이 하는 일: 어떤 입력 조합이 규칙을 드러내는지 제안하고, 계산 과정의 단계 표(전개) 골격을 만든다
• 사용자가 하는 일: 그 표의 결과 칸을 채운다
• AI가 계산해 채운 값을 정본으로 삼지 않는다. 값이 맞더라도 문제다 — 규칙 해석이 틀렸다면 틀린 구현이 틀린 기대값을 통과해 테스트가 통과한다

사용자가 "네가 계산해줘"라고 하면, 계산해서 보여주되 확인을 요청하고 확인받은 뒤에만 문서에 쓴다. 확인 없이 넣지 않는다.

3. 빈칸을 발견하면 채우지 말고 물어라

원천 자료에 없는 것을 그럴듯하게 채우는 것이 **지어내다(invent)**다. 세 형태:

형태	방어 장치
시나리오를 지어냄	§1 "의도적으로 제외한 것" 목록
수치를 지어냄	§4 "예제 없음" 표시 → 사용자에게 계산 요청
인터페이스를 지어냄	tdd-plan 단계 E-2 규칙 (이 문서 범위 밖)

빈칸을 만났을 때 선택지는 셋뿐이다: 질문한다 / §6 미확정으로 올린다 / §1 제외 목록에 넣는다. 넷째("일반 도메인 지식으로 채운다")는 없다.

4. 용어 규약

• invent → 지어내다(invent). 우리 문장에서 '지어내기(invent)'을 쓰지 않는다
• '검산'을 쓰지 않는다 → "사람이 계산해 확인한" 등 쉬운 말로

예외 — tdd-plan의 규칙명을 그대로 인용할 때. 인용은 검색으로 원 규칙을 찾을 수 있어야 하므로 원문 표기를 바꾸지 않는다. 해당하는 두 곳:

• "검산 전개" — 이 문서의 §2 예제가 그 자리에 들어간다는 매핑을 명시할 때
• "인수 조건에 없는 API를 지어내지(invent) 않는다" — tdd-plan 단계 E-2의 규칙명

인용 부호 안이 아닌 우리 문장에서는 언제나 '지어내다(invent)'를 쓴다.

5. 집계 경계는 반드시 스캔한다

경계 5분류 중 집계 경계(같은 키가 여러 항목으로 나뉘는 경우)는 스스로 떠오르지 않으므로 체크리스트로 강제한다. 재고·한도·사용횟수·포인트처럼 합산되는 자원이 도메인에 있으면 무조건 질문한다:

"같은 [상품/회원/쿠폰]이 여러 [라인/요청/이벤트]으로 나뉠 수 있습니까?
 나뉠 수 있다면, 검증은 항목별인가 합산인가?"

검증 단위와 반영 단위가 다르면 그 차이가 곧 결함이다(예: 라인별로는 재고 검증을 통과하지만 합산하면 오버셀). 원천 자료에 규정이 없으면 §6 미확정으로 올린다.

6. 한 번에 다 묻지 않는다

섹션당 질문 2~4개 → 답 반영 → 해당 섹션 초안 제시 → 확인 → 다음 섹션. 전체 섹션의 질문을 한꺼번에 제시하지 않는다. 문서는 시작 시점에 파일로 만들고, 아직 다루지 않은 섹션은 템플릿의 플레이스홀더 상태로 남긴다.

7. 질문 자기완결(self-contained question)

AskUserQuestion 창이 열리면 앞의 메시지 본문은 보이지 않는다. 질문 창만 보고 답할 수 있어야 한다.

위치 선언

• 질문 직전 메시지 본문 첫 줄: 단계 N/7 — <문서 경로> §N <섹션 제목>에 대해 묻습니다
• question 텍스트도 같은 접두어 <문서 경로> §N <섹션 제목> — 로 시작한다
• header(12자 제한)에는 섹션 번호를 넣는다 (예: §4 수치경계)
• 경로는 세션에서 한 번 확정된 뒤에도 매 질문에 반복한다. "§3 액터"처럼 경로 없이 쓰지 않는다
• 원천 문서를 인용할 때도 경로 + 절 제목을 붙인다 (예: 원천 문서 docs/order-cancel-simplified-source.md '예' 절)

확인 대상 포함

• 값·표·목록의 확인을 요청할 때 확인 대상(예제 번호, 전/행동/후 값, 수치)을 question 텍스트 안에 직접 쓴다. "위 표", "앞서 제시한" 같은 산문 참조만으로 묻지 않는다
• 예제 확인: 예제당 한 줄 N) 전 → 행동 → 후로 나열한 뒤 "맞음 / 수정 필요" 선택지를 준다
• 항목이 많아 한 질문에 담기 어려우면 질문을 나눈다 (Hard Rule 6과 같은 단위)

Principles

• §1 범위를 최우선으로 — "의도적으로 제외한 것" 목록이 이후 모든 지어냄 방지의 기초다. 범위가 확정되기 전에 규칙을 상세화하지 않는다
• 모호한 규칙은 즉시 질문 — "적절히", "보통", "필요하면" 같은 표현이 나오면 그 자리에서 구체화를 요청한다
• So that을 채울 수 없으면 경고 — 가치를 말할 수 없는 항목은 스토리가 아니라 작업 지시다. §3에서 미리 선별해 tdd-plan의 INVEST 점검이 무효화되지 않게 한다

OUTPUT FORMAT

문서 생성

1. 인자 판별
   • 인자가 파일 경로면 읽어서 §1~§6에 배치한 뒤 빈칸을 질문으로 채운다
   • 인자가 주제 한 줄이면 바로 질의응답으로 시작한다
   • 인자가 없으면 "어떤 기능을 다루려 하십니까?" 한 줄 질문으로 시작한다
2. 저장 경로 확정 — 기본값 docs/<topic>-plan-input.md를 제안하고 사용자 확인을 받는다. 프로젝트에 이미 문서 폴더 관례가 있으면 그쪽을 따른다
3. 골격 생성 — 이 스킬 디렉터리의 references/template.md를 Read로 읽어 확정한 경로에 Write로 저장한다(셸 복사 아님 — 이 스킬은 Bash를 쓰지 않는다). 각 섹션 첫머리의 인용 블록(지침)은 남긴다 — tdd-plan과 이후 사람이 읽을 때 각 섹션의 계약이 된다
4. 이후 단계마다 해당 섹션만 Edit으로 채운다 (append only, 기존 내용 훼손 금지)

작성 예시의 기준은 references/example-cart.md(장바구니 도메인 완성본)다. 어떤 수준까지 쓰는지 애매하면 이 파일을 참조한다.

---

단계 1 — §1 범위와 유형

물어볼 것

1. 이번에 다룰 기능은 무엇입니까? (2~3개까지가 적당 — 더 많으면 나눌 것을 제안)
2. 각 기능은 순수 계산입니까, 상태 전이 + 협력 객체입니까?
3. 실제 도메인에는 있지만 이번에 뺄 것은 무엇입니까?
4. TDD 유형은 general(도메인 로직만)입니까 web-app(HTTP 관통 + Cucumber 필수)입니까? 미정이면 미정으로 두고 §6에 올린다

문서에 쓸 것: 기능 목록(성격 표시) / TDD 유형 / 의도적으로 제외한 것 목록

다음으로 가는 조건: 제외 목록이 비어 있지 않다. 비어 있다면 "정말 실제 도메인에서 덜어낸 것이 하나도 없습니까?"를 한 번 더 묻는다 — 이 목록이 없으면 이후 tdd-plan이 빈칸을 누락으로 오인한다

탈출 경로: 사용자가 두 번 답을 유보하면("몰라"·"알아서 해") 목록을 채우지 말고 §1에 "제외 범위 미확정 — §6 참조"라고 적은 뒤 §6에 올리고 다음 단계로 간다. 게이트를 통과하지 못했다는 이유로 AI가 제외 목록을 채우는 것은 Hard Rule 3 위반이다 — 게이트를 통과하려고 지어내지 않는다. 게이트를 §6으로 우회한다.

---

단계 2 — §2 도메인 규칙 (기본/특별)

기능마다 기본 규칙 / 특별 규칙을 나눠 받는다.

물어볼 것

1. 정상 동작은 어떻게 됩니까? (입력·출력·제약)
2. 예외·특수한 경우는? 규칙 적용에 순서가 있습니까? (순서가 있으면 그 순서 자체가 불변식이므로 명시)
3. 검증 순서를 정할 때 — 요청 형식 위반(필수 파라미터 누락·빈 값)은 도메인 검증의 앞입니까 뒤입니까? 프레임워크가 먼저 응답해버리는 경로가 있어서, 정하지 않으면 순서 불변식에 구멍이 생긴다(같은 종류의 잘못이 누락은 400, 공백은 403으로 갈라지는 식)
4. 상태가 있는 기능이면 — 상태 목록, 전이 조건, 전이가 거부되는 조건
5. 실패했을 때 무엇이 변하고 무엇이 변하지 않습니까?

문서에 쓸 것: 2a, 2b… 기능별 절에 기본 규칙 / 특별 규칙

다음으로 가는 조건: "적절히·보통·필요하면" 류의 모호한 표현이 규칙에 남아 있지 않다

---

단계 3 — §2 예제 (사람이 계산한 정본 수치)

규칙만으로는 이해가 어렵다. 특별 규칙마다 그 규칙이 드러나는 예제를 만든다 (Specification by Example).

스킬이 하는 일

• 어떤 입력 조합이 그 규칙을 드러내는지 제안한다 (예: "쿠폰이 상품 합계를 초과하는 경우 — 초과분 처리 규칙이 드러납니다")
• 결과를 비워 둔 골격을 만들어 사용자가 채우게 한다

예제 형식은 규칙의 성격에 따라 둘 중 하나 — 계산 도메인이 아니면 첫 형식을 억지로 쓰지 않는다:

① 계산 규칙 — 단계별 전개 표 (결과 칸을 비운다)

**예제 N — [무엇을 보여주는가]**

| 단계 | 계산 | 결과 |
|---|---|---|
| 상품 합계 | 10,000×2 + 5,000×1 | ?  ← 계산해 주세요 |

② 상태 전이·판정 규칙 — 전/행동/후 (후 칸을 비운다)

**예제 N — [무엇을 보여주는가]**: 전(대출 3건, 한도 5) — 행동(1권 더 대출)
→ 후(?  ← 무엇이 어떻게 바뀝니까)

②는 수치가 아니라 결과 상태가 정본이다("허용/거부", "무엇이 변하고 무엇이 변하지 않는가"). 정본 예제 references/example-cart.md의 예제 6·7이 이 형식이다.

사용자가 하는 일: 비워 둔 칸을 채운다

확인 방식: 채워진 값을 AskUserQuestion으로 확인할 때 예제 전체를 질문 본문에 넣는다 (Hard Rule 7). 메시지 본문의 표를 "위 표"로 가리키지 않는다.

문서에 쓸 것: 채워진 예제. 예제에는 번호를 붙인다 — §4에서 참조한다. 기능별 예제 소절 끝에 > 확인: 위 예제 수치는 사용자가 계산해 확인한 값이다. 한 줄을 남긴다 — 세션이 끊긴 뒤에도 그 값이 사람이 준 것임이 문서만으로 판정된다

다음으로 가는 조건: 각 예제의 비워 둔 칸이 사용자가 준 값·상태로 채워졌다.

탈출 경로: 계산이 부담스럽다는 반응이면 먼저 예제 수를 줄인다(특별 규칙당 1개). 그래도 사용자가 채우지 않으면 AI 계산값을 넣지 말고 해당 예제 자리에 "예제 없음 — 사용자 계산 대기"로 남긴 뒤 §4에서 예제 없음으로 표시하고 다음 단계로 간다. 예제가 하나도 없는 문서도 유효한 산출물이다 — 지어낸 수치가 든 문서보다 낫다

---

단계 4 — §3 액터와 가치

물어볼 것

1. 이 기능은 누가 씁니까? (실제 사용자·이해관계자. "시스템"은 액터가 아니다)
2. 그 사람이 이걸로 무엇을 얻습니까?

문서에 쓸 것: 기능 / 역할 / 원하는 것 / 얻는 가치 표

주의: "얻는 가치"를 사용자 언어로 채울 수 없으면 그 자리에서 경고한다 — "이건 스토리가 아니라 작업 지시로 보입니다. 이 기능이 없으면 누가 무엇을 못 합니까?" 그래도 답이 안 나오면 §6 미확정으로 올린다.

금지: 여기서 As a / I want / So that 문장을 만들지 않는다 (Hard Rule 1)

---

단계 5 — §4 경계 조건 스캔

5분류 체크리스트를 순서대로 돌며 이 도메인에 걸리는 경계를 찾는다.

분류	스캔 질문
수치적 경계	0·1·최대·최소, 임계점 정확히 일치하는 값에서 무슨 일이 일어납니까?
크기 경계	빈 컬렉션은? 항목 1개(최소 유효)는? 상한이 있습니까?
상태 경계	각 상태에서 이 동작이 허용/거부됩니까? 완료 상태에서 다시 하면?
시간·순서 경계	시작/종료 시점·만기·타임아웃에서 무슨 일이 일어납니까? (만기 당일 / 익일, 경과 0일) 순서를 바꾸면 결과가 달라지는 입력이 존재합니까?
집계 경계	Hard Rule 5의 질문을 그대로 사용 (합산 자원이 있으면 필수)

문서에 쓸 것: 분류별 경계 항목. 각 항목 끝에 반드시 다음 중 하나를 붙인다:

• — 예제 N (단계 3의 예제가 이미 덮음)
• — 예제 없음 (규칙만 있고 사람이 계산한 수치가 없음)
• — 미규정(§6 참조) (원천 자료에 규칙 자체가 없음 → §6로 올림)

표시가 빠진 항목이 하나라도 있으면 이 단계는 끝나지 않았다.

다음으로 가는 조건: 5분류를 모두 스캔했고(해당 없으면 "해당 없음"도 확인), 모든 항목에 표시가 있다

---

단계 6 — §5 흐름·상태 신호

tdd-plan의 조건부 Use Case 판단 체크리스트 4항목에 대해 사실만 확인한다. 판단(Use Case를 쓸지)은 tdd-plan의 일이므로 여기서 결론 내지 않는다.

항목	확인 질문
액터 2명 이상 + 관심사 충돌	이해관계가 다른 액터가 둘 이상입니까?
상태 전이	상태가 바뀝니까? 단방향입니까 왕복입니까?
대안·예외 흐름 3개 이상	정상 흐름에서 갈라지는 경로가 몇 개입니까?
기능 간 불변식	"A가 보여준 값 = B가 확정하는 값" 같은 약속이 있습니까?

문서에 쓸 것: 항목별 "있음/아니오 + 근거 한 줄" 표. 근거가 원천 자료에 명시돼 있지 않으면 그 사실을 적고 §6로 올린다

---

단계 7 — §6 미확정 사항 + 마무리

문서에 쓸 것: 단계 1~6에서 보류된 결정을 모은다. 각 항목은 질문 + 그 결정이 무엇에 영향을 주는지까지 쓴다 (결정의 무게를 알 수 있게).

"제외한다"도 결정이다 — 사용자가 그 자리에서 결정하면 §1 제외 목록으로 옮기고 §6에서 뺀다.

자가 점검 (FAILURE CONDITIONS 체크리스트 실행) 후 완성된 문서를 커밋한다 (1회, 예: docs: <topic> 요구사항 원천 문서 작성 — 메시지 형식·한글 안전 방식은 ../../references/commit-style.md를 따른다). 그다음 마무리 안내:

문서 완성: <경로>   ← 요구사항 원천 문서

다음 단계:
  ① /tdd <general|web-app> <FQCN>        — 작성 대상 템플릿 문서를 만든다
  ② /tdd-plan <생성된 템플릿 경로>       — 실행할 때 위 원천 문서 경로를 함께 제시한다
     예) "/tdd-plan docs/bowling-plan.md — 요구사항은 <경로>를 참조"

남은 미확정 사항 N건은 §6에 있습니다 — tdd-plan 단계 1 진행 전에 결정이 필요합니다.

원천 문서를 /tdd-plan의 인자로 바로 주지 않는다 — tdd-plan의 인자는 절차 섹션과 체크박스를 가진 작성 대상 템플릿 문서다(/tdd가 생성). 원천 문서를 인자로 주면 tdd-plan이 이 문서를 템플릿으로 오인해 요구사항 섹션을 덧쓰고, "숫자의 정본은 §2 하나"라는 이 문서의 장치가 무효화된다. 원천 문서는 참조로 전달한다.

FAILURE CONDITIONS

문서를 마무리하기 전에 확인한다. 하나라도 걸리면 해당 단계로 돌아간다.

• §1에 "의도적으로 제외한 것" 목록이 있는가? (없으면 지어냄 방지 장치 부재)
• §2의 모든 예제가 사용자가 계산해 확인한 값·상태인가? 기능별 예제 소절마다 확인: 한 줄이 있는가? (AI가 만든 값이 확인 없이 들어간 곳 없음)
• 완성형 User Story(As a/I want/So that)·Gherkin·unit test 목록이 문서에 없는가? (재료까지만)
• §4의 모든 경계 항목에 예제 N / 예제 없음 / 미규정(§6) 표시가 있는가?
• 합산되는 자원(재고·한도·사용횟수·포인트)이 있다면 §4-5에 항목이 있는가?
• §5에 판단 결론(Use Case를 쓴다/안 쓴다)을 적지 않고 사실만 적었는가?
• 우리 문장에서 '지어내기(invent)'·'검산'을 쓰지 않았는가? (인용 부호 안의 tdd-plan 규칙명 — "검산 전개", "인수 조건에 없는 API를 지어내지(invent) 않는다" — 은 예외)
• §1~§6 + 용어집 구조가 유지되어 tdd-plan이 소비 매핑 표대로 읽을 수 있는가?
• 마무리 안내가 원천 문서를 /tdd-plan의 인자가 아니라 참조로 전달하게 하는가?
• 완성된 문서를 커밋하지 않은 채 다음 단계로 안내하지 않았는가?