@simplysm/sd-claude 14.0.56 → 14.0.57

package/claude/skills/sd-debug/references/verification-tools.md

@@ -0,0 +1,204 @@
+# 검증 도구 4종 — Phase 4 적용 가이드
+
+Phase 4에서 ACH 매트릭스 갱신을 위한 판별 실험을 선택할 때 사용한다. 각 도구는 가설을 *반증* 하기 위한 실험을 설계하는 방법론이다.
+
+## 도구 선택 결정 트리
+
+```
+스택 트레이스가 있는가?
+├ Yes → 역추적 (Backward Reasoning)
+└ No  → 잘못된 값이 출력되는가?
+        ├ Yes → 데이터 흐름 추적 (Data Flow Tracing)
+        └ No  → "이전엔 됐는데 안 됨"인가?
+                ├ Yes → 변경 이력 분석 (Change History Analysis)
+                └ No  → 제약 조건 추론 (Constraint-based Reasoning)
+```
+
+여러 도구를 조합 가능 (예: 변경 이력 분석으로 회귀 커밋 좁힘 → 역추적으로 발현 지점 분석).
+
+## 1. 역추적 (Backward Reasoning)
+
+문제 발현 지점에서 출발하여 원인 방향으로 거슬러 올라간다.
+
+### 적용 조건
+
+- 스택 트레이스가 있을 때
+- 문제 발현 지점이 명확할 때 (특정 함수 / 특정 라인)
+- TypeError, NullPointerException 같은 *지점이 명확한* 에러
+
+### 절차
+
+1. 문제 발생 지점의 변수 상태 확인 (스택 트레이스 또는 디버거)
+2. 해당 변수의 마지막 할당(definition) 위치 추적
+3. 잘못된 값이 최초로 유입된 지점까지 반복
+
+### 적용 예시
+
+```
+TypeError: Cannot read properties of undefined (reading 'map')
+  at getUserRoleNames (src/utils.ts:7)
+
+→ Step 1: src/utils.ts:7 → u.roles가 undefined
+→ Step 2: u는 어디서? → users 배열의 element
+→ Step 3: users는 어디서? → src/app.ts에서 정의
+→ Step 4: src/app.ts → { name: "Bob" } 항목에 roles 누락
+→ ROOT: User 인터페이스가 roles?: string[]로 옵셔널이라 누락 허용
+```
+
+### ACH 등록
+
+각 단계의 관찰을 증거로 등록. 가설(예: "u.roles가 undefined인 항목이 있다")의 C(code)로 표시.
+
+## 2. 데이터 흐름 추적 (Data Flow Tracing)
+
+데이터의 생명주기를 따라가며 불일치 지점을 찾는다.
+
+### 적용 조건
+
+- 잘못된 값이 출력되거나 기대와 다른 결과가 나올 때
+- 입력은 정상이지만 중간 처리에서 깨지는 경우
+- 스택 트레이스 없이 동작 이상만 있는 경우
+
+### 절차
+
+1. Input 지점 식별 (API 요청, DB 읽기, 사용자 입력 등)
+2. Transform 체인을 순서대로 나열 (함수 호출, 매핑, 직렬화 등)
+3. 각 단계의 기대값 vs 실제값 비교
+4. 최초 불일치 지점 = 버그 위치
+
+### 적용 예시
+
+```
+Input: ages = [2, 10, 1]
+Transform 1: items.sort((a, b) => String(a.age).localeCompare(String(b.age)))
+  기대: [1, 2, 10]
+  실제: [1, 10, 2]  ← 첫 불일치
+ROOT: localeCompare가 문자열 사전식 비교 ("10" < "2")
+```
+
+### 도구
+
+- `console.log` (LLM은 실행 환경 없으면 코드 트레이스로 시뮬레이션)
+- 디버거 step-through (사용자 환경)
+- assertion 삽입 (각 단계의 기대값 명시)
+
+## 3. 변경 이력 분석 (Change History Analysis)
+
+최근 변경과 버그의 상관관계를 분석한다. 회귀 의심 시 가장 효과적.
+
+### 적용 조건
+
+- "이전엔 됐는데 안 됨"
+- 회귀가 의심될 때
+- 의존성 업데이트 후 발생
+
+### 절차
+
+1. 버그 발생 시점 전후의 코드 변경 조회
+   - `git log --since="<발생 직전>" --until="<발생 직후>"`
+   - `git log -p <관련 파일>`
+2. 에러 관련 파일과 변경된 파일의 교집합 분석
+3. 변경 내용의 의미적 분석 (리팩토링 vs 로직 변경 vs API 계약 변경)
+4. 회귀 도입 커밋 의심 시 `git bisect`로 자동 좁히기
+
+### 적용 예시
+
+```bash
+# 1. 최근 변경 확인
+git log --oneline -20 src/utils.ts
+
+# 2. 의심 커밋 시점 비교
+git diff <suspected-commit>^ <suspected-commit> -- src/utils.ts
+
+# 3. 자동 좁힘
+git bisect start
+git bisect bad HEAD
+git bisect good <known-good>
+git bisect run pnpm test
+```
+
+### ACH 등록
+
+회귀 도입 커밋이 식별되면 해당 커밋이 도입한 변경을 가설의 C(code)로 등록.
+
+## 4. 제약 조건 추론 (Constraint-based Reasoning)
+
+발생/비발생 조건을 체계적으로 좁혀간다. 간헐 발생(L4) 또는 특정 환경 의존(L2/L3) 케이스에 효과적.
+
+### 적용 조건
+
+- 간헐적 발생
+- 특정 환경/입력에서만 발생
+- 명확한 트리거가 보이지 않을 때
+
+### 절차
+
+1. 발생 조건 수집: 어떤 입력/환경/순서에서 발생하는가?
+2. 비발생 조건 수집: 어떤 경우 발생하지 않는가?
+3. 차이 분석: 발생/비발생 조건의 차이가 원인을 가리킴
+4. 차이 항목을 단일화하여 검증 (one-variable-at-a-time)
+
+### 적용 예시
+
+```
+발생 조건:
+- Chrome 90 + Windows
+- 사용자 > 100명 동시 접속
+- 트랜잭션 내 5회 이상 쿼리
+
+비발생 조건:
+- Chrome 90 + macOS
+- 사용자 < 50명
+- 트랜잭션 내 1~3회 쿼리
+
+차이: OS, 사용자 수, 쿼리 수
+→ 단일 변경: macOS에서 동시 100명 + 5쿼리 → 발생 → OS 영향 배제
+→ 단일 변경: Windows에서 동시 50명 + 5쿼리 → 비발생 → 사용자 수 영향
+ROOT: 동시 접속 수 + 쿼리 수의 곱이 임계 초과 시 발생 → 커넥션 풀 고갈
+```
+
+### ACH 등록
+
+각 검증 결과를 증거로 등록. 가설(예: "커넥션 풀 고갈")의 C(code) 또는 I로 표시.
+
+## 도구 결합 패턴
+
+### 패턴 A: 회귀 + 발현 지점
+
+1. 변경 이력 분석으로 회귀 커밋 좁힘
+2. 역추적으로 발현 지점에서 회귀 커밋의 변경 확인
+3. ACH에 두 단계 모두 증거 등록
+
+### 패턴 B: 간헐 발생
+
+1. 제약 조건 추론으로 발생 조건 좁힘
+2. 데이터 흐름 추적으로 발생 조건에서 데이터 흐름 분석
+3. ACH에 두 단계 모두 증거 등록
+
+### 패턴 C: 외부 의존 의심
+
+1. 변경 이력 분석으로 의존성 버전 변경 확인
+2. 외부 라이브러리 changelog/이슈 검색 (`gh search issues`, `WebSearch`)
+3. C(doc) 등급으로 ACH 등록 (C(infer) 단독 금지)
+
+## Falsification First
+
+각 도구를 적용하기 전에 다음을 명시한다.
+
+> "이 실험으로 어떤 가설이 *반증* 될 수 있는가?"
+
+가설을 입증하려는 실험은 confirmation bias에 빠지기 쉽다. 반증 가능한 실험을 우선 선택.
+
+## minimally-invasive probe
+
+검증 시 사용자 코드를 수정하지 않는다. 다음 도구만 사용:
+
+- 코드 *읽기* (Read, Grep)
+- 실행 *결과* 관찰 (Bash로 테스트 실행)
+- assertion / print 삽입은 *지시* 로만 (실제 코드 수정 금지, 사용자가 수행)
+
+## one-variable-at-a-time
+
+여러 변수를 동시에 변경하면 인과 식별이 깨진다. 항상 한 번에 한 변수만 변경.
+
+위반 예: "버전 업그레이드 + 설정 변경 + 코드 리팩토링을 동시에 적용 → 어느 것이 원인인지 식별 불가"

package/claude/skills/sd-deliverable/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: sd-deliverable
 description: 코드 분석 기반으로 사용자 매뉴얼(md)과 SIT 문서(md)를 생성·업데이트하는 스킬. "매뉴얼 만들어줘", "SIT 문서 만들어줘", "산출물 생성", "매뉴얼 업데이트" 등을 요청할 때 사용한다.
-effort: low
+model: haiku
 ---
 
 # sd-deliverable: 매뉴얼 & SIT 생성

package/claude/skills/sd-dev/SKILL.md

@@ -8,39 +8,18 @@ description: 요구명세 → 구현계획 → TDD 개발 → 체크 → 리뷰
 sd-wbs → sd-plan → sd-tdd → sd-check → sd-review를 순차 진행하는 오케스트레이터.
 **CRITICAL**: Step간 진행은 사용자 확인없이 즉시 다음 Step으로 진행한다.
 
-## 공통 규칙
-
-### subagent 실행 프로토콜
-
-Step 4~6은 Agent 도구로 subagent를 생성하여 수행한다. 각 단계가 fresh context를 확보하여 컨텍스트 소진을 방지한다.
-
-#### prompt 구성
-
-1. `.claude/skills/sd-dev/subagent-preamble.md`를 Read한다
-2. 그 내용 + Step별 작업 지시를 합쳐 Agent prompt를 구성한다
-
-#### NEED_INPUT 처리 루프
-
-subagent 반환값에 `---NEED_INPUT---`이 포함되면:
-
-1. 상황과 선택지를 파악한다
-2. AskUserQuestion으로 사용자에게 질문한다 (sd-options 규칙 준수)
-3. SendMessage로 사용자 결정을 subagent에 전달한다
-4. subagent 반환값을 다시 확인한다 (NEED_INPUT 반복 가능)
-
-포함되지 않으면 해당 Step 완료.
-
 ## Step 1: 입력 분기
 
 인자에 따라 시작 Step을 결정한다. (인자가 없는경우 대화에서 유추)
 
-| 입력                             | 시작 Step                                                                      |
-| -------------------------------- | ------------------------------------------------------------------------------ |
-| wbs 경로만 (추가 요청 없음)      | → `/sd-dev {wbs경로} {Feature번호}` 안내 후 **종료**                           |
-| wbs 경로만 (추가 요청 있음)      | → Step 2 (sd-wbs 업데이트)                                                     |
-| wbs + Feature 번호               | → Step 3 (sd-plan)                                                             |
-| Feature 문서 경로                | → Step 4 (sd-tdd). Slice 체크박스(`[x]`/`[ ]`)를 확인하여 진행 상태를 복원한다 |
-| 그 외 (자연어 요청, 참고자료 등) | → Step 2 (sd-wbs)                                                              |
+| 입력                                 | 시작 Step                                                                      |
+| ------------------------------------ | ------------------------------------------------------------------------------ |
+| wbs 경로만 (추가 요청 없음)          | → `/sd-dev {wbs경로} {Feature번호}` 안내 후 **종료**                           |
+| wbs 경로만 (추가 요청 있음)          | → Step 2 (sd-wbs 업데이트)                                                     |
+| wbs + Feature 번호                   | → Step 3 (sd-plan)                                                             |
+| Feature 문서 경로                    | → Step 4 (sd-tdd). Slice 체크박스(`[x]`/`[ ]`)를 확인하여 진행 상태를 복원한다 |
+| `/sd-review`가 전달한 확정 이슈 목록 | → Step 3 (sd-plan: 리뷰 수정 Feature 문서 생성)                                |
+| 그 외 (자연어 요청, 참고자료 등)     | → Step 2 (sd-wbs)                                                              |
 
 ## Step 2: sd-wbs
 
@@ -53,58 +32,29 @@ subagent 반환값에 `---NEED_INPUT---`이 포함되면:
 
 `/sd-plan` 스킬을 즉시 수행한다. 완료 후 사용자 확인 없이 즉시 Step 4로 진행한다.
 
-## Step 4: sd-tdd (subagent)
-
-Agent 도구로 subagent를 생성하여 sd-tdd를 수행한다. (subagent 실행 프로토콜 참조)
-
-### prompt 구성
+`/sd-review`가 전달한 확정 이슈 목록으로 시작한 경우:
 
-preamble + 아래 작업 지시:
+- `/sd-wbs`를 수행하지 않는다.
+- 확정 이슈 목록 전체를 하나의 리뷰 수정 Feature로 보고 `/sd-plan`을 즉시 수행한다.
+- 이슈별 또는 근본 원인별 작업 단위는 WBS Feature가 아니라 Feature 문서의 Slice로 나눈다.
 
-    ## 작업
-    `.claude/skills/sd-tdd/SKILL.md`를 Read하고 지침에 따라 TDD 개발을 수행하세요.
-    - Feature 문서: {feature_doc_path}
-    - WBS 문서: {wbs_path}
+## Step 4: sd-tdd
 
-NEED_INPUT 처리 루프에 따라 사용자 입력을 중계한다.
+`/sd-tdd` 스킬을 즉시 수행한다. 완료 후 사용자 확인 없이 즉시 Step 5로 진행한다.
 
-## Step 5: sd-check (subagent)
+## Step 5: sd-check
 
 수정된 소스코드(`src/`, `tests/`)가 하나도 없으면(예: 문서만 수정) 이 단계를 스킵한다.
 
-Agent 도구로 subagent를 생성하여 변경 패키지에 대한 sd-check를 수행한다. (subagent 실행 프로토콜 참조)
+변경 패키지에 대해 `/sd-check` 스킬을 즉시 수행한다. 완료 후 사용자 확인 없이 즉시 Step 6로 진행한다.
 
-### prompt 구성
+## Step 6: sd-review
 
-preamble + 아래 작업 지시:
+`/sd-review` 스킬을 즉시 호출한다.
 
-    ## 작업
-    `.claude/skills/sd-check/SKILL.md`를 Read하고 지침에 따라 체크를 수행하세요.
-    - 대상 패키지: {변경된 패키지 목록}
+- 호출 시 이번 `/sd-dev` 실행의 WBS/Feature 문서, 참조 자료, 변경 파일, 검증 결과, 사용자 결정사항, 리뷰 수정 이력 맥락을 전달한다.
 
-NEED_INPUT 처리 루프에 따라 사용자 입력을 중계한다.
-
-## Step 6: sd-review (subagent)
-
-Agent 도구로 subagent를 생성하여 코드 리뷰 + 수정을 수행한다. (subagent 실행 프로토콜 참조)
-
-### prompt 구성
-
-preamble + 아래 작업 지시:
-
-    ## 작업
-    1. `.claude/skills/sd-inner-review/SKILL.md`를 Read하고 지침에 따라 코드 리뷰를 수행하세요.
-       - 요구사항 원천: {wbs_path}, {feature_doc_path}
-    2. 발견된 **모든** 이슈를 직접 수정하세요.
-    3. 수정 내역을 요약하여 보고하세요 (파일경로, 수정 내용).
-
-NEED_INPUT 처리 루프에 따라 사용자 입력을 중계한다.
-
-### 수정 후 재검증
-
-subagent가 코드 수정을 보고하면, Step 5(sd-check)를 subagent로 재수행한다.
-
-## Step 7: 완료 보고
+## Step 7: 완료 보고 양식
 
 모든 단계 완료 후, 아래 양식으로 실행 결과를 대화에 출력한다.
 
@@ -136,6 +86,7 @@ subagent가 코드 수정을 보고하면, Step 5(sd-check)를 subagent로 재
 ```
 
 완료 보고 출력 직전에 **반드시(MUST) wbs.md의 현재 상태를 다시 읽어** Feature 체크박스(`[x]`/`[ ]`)를 확인한 뒤, 위 두 섹션 중 조건에 맞는 정확히 하나만 출력한다.
-- 다시 읽지 않으면 병렬 로 수행한 모든것이 적용되지 않은 상태로 표기되기 때문에 중복 수행 문제가 발생할 수 있다.
+
+- 다시 읽지 않으면 이전 단계에서 변경된 상태가 반영되지 않아 중복 수행 문제가 발생할 수 있다.
 
 **NEVER:** 미완료(`[ ]`) Feature가 1개라도 남아 있으면 `/sd-review`를 어떤 형태로도(조건부·제안·예시 포함) 언급하지 않는다. "모든 Feature가 끝난 뒤 /sd-review를 권장" 같은 조건부 안내도 금지한다.

package/claude/skills/sd-inner-clarify/SKILL.md

@@ -23,9 +23,9 @@ description: (내부 전용) 명확성 분류·근거 탐색·재분류·명확
 
 **CRITICAL: Medium/Low/ASSUMED로 분류된 모든 항목은 사용자에게 질문하기 전에 반드시 근거를 탐색한다.**
 
-근거는 **현재 컨텍스트 안에 이미 존재할 가능성이 가장 높다**. 질문하기 전에 두 단계로 확인한다.
+근거 출처는 항목의 성격에 따라 결정한다. 컨텍스트 회수와 타겟 탐색 중 어느 한쪽으로 미리 편향시키지 않는다.
 
-### 2-1. 컨텍스트 회수 (먼저 시도)
+### 2-1. 컨텍스트 회수
 
 지금까지 누적된 맥락 전체에서 근거를 찾는다. 새 tool 호출 전에 수행한다.
 
@@ -34,11 +34,11 @@ description: (내부 전용) 명확성 분류·근거 탐색·재분류·명확
 - **이미 읽은 tool 결과** — 직전 Read/Grep/Glob/WebFetch 출력, 첨부된 문서 내용
 - **세션 내 이미 생성된 산출물** — spec, plan, 직전 단계 보고 등
 
-### 2-2. 타겟 탐색 (회수로 부족할 때)
+### 2-2. 타겟 탐색
 
-컨텍스트에 없으면 탐색한다. 항목의 성격에 맞는 소스를 고른다(순서 고정 아님).
+항목의 성격에 맞는 소스를 확인한다. 컨텍스트 회수에서 결론이 보여도, 아래 강제 항목에 해당하면 반드시 탐색한다.
 
-- **타겟 코드베이스** — Grep/Read/Glob으로 동일/유사 패턴
+- **타겟 코드베이스** — Grep/Read/Glob으로 동일/유사 패턴. **다음 항목은 코드베이스 탐색 필수(컨텍스트 회수로 종결 금지):** UI 컴포넌트 구조·레이아웃·생김새, 메뉴/네비게이션 분할, 라우팅 구조, 도메인 엔터티 구조, 네이밍 컨벤션, 디렉토리 구조
 - **참조 문서** — `.claude/references/**`, CLAUDE.md 등 프로젝트 문서
 - **사용자가 제공한 원본 자료** — 첨부 문서·파일·경로를 끝까지 확인 (키워드 검색만으로 종결 금지)
 - **공식 문서** — 외부 라이브러리/프레임워크 (필요 시)
@@ -63,12 +63,27 @@ description: (내부 전용) 명확성 분류·근거 탐색·재분류·명확
 
 재분류 결과를 **표 형태로 사용자에게 출력**한다. Step 5 질문 전에 반드시 수행한다.
 
-| 항목 | 1차 분류 | 탐색 위치 | 근거(인용/요약) | 재분류 |
-|------|---------|----------|----------------|--------|
+### 인용 형식
+
+표의 "인용/요약" 칼럼에 사용한다.
+
+- **정형 문서**: `파일경로:라인` 또는 `문서명 p.N` / `섹션명`
+- **비정형 자료**:
+  - 메일: `메일 [제목] / 발신자 / 일시 — "..."`
+  - 회의 대본: `회의록 [회의명] / 발화자 / 시점 또는 라인 — "..."`
+  - 메시지 본문: `사용자 메시지 ({n}번째 턴) — "..."`
+- 인용은 1~2문장으로 의미가 드러나야 한다. 좌표만 적고 인용을 생략하는 것은 **금지**.
+
+### 표 출력
+
+| 항목 | 1차 분류 | 탐색 위치 | 인용/요약 | 재분류 |
+|------|---------|----------|----------|--------|
 | (정보 항목) | ASSUMED | 원본.docx p.3 / foo.ts:42 | "..." 또는 요약 | VERIFIED |
 
-- **탐색 위치**는 파일경로:라인번호, 문서명:페이지/섹션 등 구체적으로 명시한다.
-- **근거 없음**으로 남은 항목은 "탐색했으나 근거 없음"을 명시한다.
+- **탐색 위치**는 파일경로:라인번호, 문서명:페이지/섹션, 메일 식별자, 회의록 발화자:시점 등 **구체 좌표**로 명시한다. "전체 검토", "문서 봄", "전반적으로 확인" 같은 추상 보고는 **금지(NEVER)**.
+- **인용/요약**은 위 "인용 형식" 규칙을 따른다. 인용이 비어 있으면 해당 항목은 ASSUMED 유지(승격 금지).
+- **근거 없음**으로 남기려면 (a) 어떤 키워드/구간을 봤는지, (b) 어떤 자료의 어떤 부분에서 부재를 확인했는지를 두 줄 이상 구체 명시한다. "탐색했으나 근거 없음" 한 줄로 종결하면 위반.
+- 비정형 자료(메일, 회의 대본, 메시지 본문)가 호출자(sd-wbs 등)에서 보고되었는데 표에 해당 자료 인용이 1건도 없으면, 끝까지 읽지 않은 신호로 간주하여 Step 2로 되돌아간다.
 - 보고 직후, 질문 대상이 남아 있으면 Step 5로 진행한다.
 
 ## Step 5: 명확화 질문

package/claude/skills/sd-plan/SKILL.md

@@ -5,10 +5,30 @@ description: Feature의 요구명세와 구현계획을 작성하는 스킬. "
 
 # sd-plan: Feature 설계
 
-Feature 하나를 대상으로, 요구명세(What)와 구현계획(How)을 수립한다.
+Feature 하나를 대상으로, WBS에서 확정된 고객 중심 What을 개발자 중심의 구현 가능한 명세와 구현계획(How)으로 변환한다.
 
 ## 공통 규칙
 
+### WBS와 sd-plan의 역할 경계
+
+WBS는 고객 중심으로 **무엇을 만들어야 하는지(What)** 를 확정한 source of truth이다.
+sd-plan은 개발자 중심으로 **어떻게 만들지(How)** 를 결정한다.
+
+- sd-plan은 WBS에 없는 고객 동작, 업무 규칙, 정책, 예외 흐름을 새로 추가하지 않는다.
+- sd-plan에서 고객 중심 미확정 사항을 발견하면 기술 질문으로 처리하지 않는다.
+- 고객 중심 미확정 사항은 WBS 수정 대상으로 되돌리고, Feature 문서 생성과 구현계획 작성을 중단한다.
+- sd-plan에서 사용자에게 질문할 수 있는 항목은 기술 설계, 기존 코드 패턴 적용, 구현 구조, 테스트 분해처럼 How에 속하는 결정이다.
+
+### 정확성 우선 원칙
+
+부정확한 진행보다 과한 검증, 질문, 중단을 우선한다.
+
+- **NEVER: 근거 없는 설계 결정 금지.** 모든 설계 결정은 `WBS`, `사용자 답변`, `기준 코드`, `프로젝트 문서` 중 하나 이상의 근거를 가져야 한다.
+- **NEVER: 임시 가정 진행 금지.** 고객 동작, 업무 규칙, 정책, 예외 흐름, 수치, 권한, 상태, 기간, 열거값은 추정해서 확정 사항처럼 기록하지 않는다.
+- **MUST: 확정/미확정/설계 결정을 분리한다.** Feature 문서에는 확정 사항, 미확정/WBS 되돌림 사항, 기술 설계 결정을 서로 다른 섹션으로 기록한다.
+- **MUST: 추정은 최종 결정으로 남기지 않는다.** 추정이 필요한 항목은 미확정으로 분류하고, 고객 중심 항목이면 WBS 되돌림 절차로, How 항목이면 명확화 질문으로 처리한다.
+- **MUST: 사용자 답변의 구체 정보 보존.** 사용자가 답한 수치, 열거 항목, 정책, 예외 조건, 상태, 권한, 기간은 원문 의미를 유지해 Feature 문서에 근거와 함께 기록한다.
+
 ### 범위 겹침
 
 어느 단계에서든 현재 Feature 범위가 다른 Feature 영역과 겹치는 것을 발견하면, 사용자에게 확인 후 조정한다.
@@ -17,18 +37,32 @@ Feature 하나를 대상으로, 요구명세(What)와 구현계획(How)을 수
 
 ## Step 1: 입력 확인
 
-wbs 문서 경로와 Feature 번호가 필수이다. 없으면 `/sd-wbs`를 안내하고 종료한다.
+다음 입력 중 하나가 필수이다.
+
+- wbs 문서 경로 + Feature 번호
+- `/sd-review`가 전달한 확정 이슈 목록
+
+wbs 문서 경로와 Feature 번호가 없더라도 `/sd-review` 전달 입력이면 종료하지 않고 Feature 문서 생성을 진행한다.
+그 외 입력이면 `/sd-wbs`를 안내하고 종료한다.
 
 ## Step 2: Feature 분석
 
 ### 2-1. 범위 설정
 
-wbs의 범위/경계를 기반으로 세분화하여 재분석한다. wbs는 큰 그림이므로 세부 동작이 빠져 있을 수 있다.
+wbs의 범위/경계를 기반으로 세분화하여 재분석한다. WBS의 고객 동작과 업무 규칙은 확정된 입력으로 취급한다.
 
-- **범위**: wbs의 세부 기능을 **구체적 동작 수준**으로 **MUST** 빠짐없이 재나열. wbs에 없는 동작도 추가.
+- **범위**: wbs의 세부 기능을 **구체적 동작 수준**으로 **MUST** 빠짐없이 재나열. WBS에 없는 고객 동작은 추가하지 않는다.
 - **경계**: wbs의 경계를 확인하고, 모호한 부분을 구체화.
 - **근거**: 범위의 출처. 참조 파일/자료 경로가 있으면 기록.
 
+WBS에 없는 고객 동작, 업무 규칙, 정책, 예외 흐름이 필요하다고 판단되면 다음 절차를 따른다.
+
+1. 해당 항목을 "WBS 미확정/누락"으로 분류한다.
+2. `/sd-inner-clarify`로 확정 질문을 수행한다. 확정될 때까지 반복한다.
+3. 확정되면 WBS 문서를 먼저 수정하고 즉시 종료한다. 사용자가 다시 `/sd-dev {wbs경로} {Feature번호}`를 실행해야 한다.
+
+**CRITICAL: WBS 미확정/누락을 발견한 상태에서 임시 가정으로 Feature 문서 생성이나 구현계획 작성을 계속하지 않는다.**
+
 ### 세부 기능 5개 초과 시
 
 세부 기능 **5개 초과** 시 SPIDR(Spike / Path / Interface / Data / Rule) 축으로 분리안 제시 ("그대로 진행" 포함).
@@ -38,19 +72,22 @@ wbs의 범위/경계를 기반으로 세분화하여 재분석한다. wbs는 큰
 
 범위의 각 세부 기능에 대해 Rule, Example, Question을 도출한다.
 
-- **Rule**: 비즈니스 규칙 (검증 조건, 제약, 정책)
+- **Rule**: WBS에서 확정된 업무 규칙 (검증 조건, 제약, 정책)
 - **Example**: Rule의 구체 사례 (입력 → 기대 결과)
-- **Question**: 불확실한 사항
+- **Question**: 구현계획 수립에 필요한 기술적 불확실성. 고객 동작/업무 규칙/정책/예외 흐름의 불확실성은 Question으로 남기지 않고 2-1의 WBS 되돌림 절차로 처리한다.
+
+Rule과 Example은 반드시 확정 근거를 가져야 한다. 근거가 없는 Rule/Example은 작성하지 않고 WBS 미확정/누락 또는 기술적 Question으로 분류한다.
 
-Question 도출 기법 — Feature 성격에 맞게 **하나 이상** 선택하고, 적용 기법명을 표기한다:
+Question 도출 기법 — Feature 성격에 맞게 **하나 이상** 선택하고, 적용 기법명을 표기한다.
+도출된 빈칸이 고객 동작/업무 규칙/정책/예외 흐름이면 2-1의 WBS 되돌림 절차로 처리하고, 구현 방식에 관한 빈칸만 기술적 Question으로 남긴다.
 
 | 기법                            | 적용 시점          | 방법                                      |
 |-------------------------------|----------------|-----------------------------------------|
-| **Decision Table**            | 조건 조합이 있을 때    | 조건 조합 나열 → 빈 칸 = Question              |
-| **Boundary Value Analysis**   | 숫자/범위가 있을 때    | 경계값 강제 → 미정의 경계 = Question              |
-| **Equivalence Partitioning**  | 입력 분류가 있을 때    | 입력 분류 나열 → 미정의 분류 = Question            |
-| **State Transition**          | 상태가 있는 Feature | 상태 x 이벤트 나열 → 미정의 전이 = Question        |
-| **Perspective-Based Reading** | 최종 검토 시        | 테스터/개발자/사용자 관점 검토 → 빠진 것 = Question    |
+| **Decision Table**            | 조건 조합이 있을 때    | 조건 조합 나열 → 빈 칸을 WBS 되돌림 대상 또는 기술적 Question으로 분류 |
+| **Boundary Value Analysis**   | 숫자/범위가 있을 때    | 경계값 강제 → 미정의 경계를 WBS 되돌림 대상 또는 기술적 Question으로 분류 |
+| **Equivalence Partitioning**  | 입력 분류가 있을 때    | 입력 분류 나열 → 미정의 분류를 WBS 되돌림 대상 또는 기술적 Question으로 분류 |
+| **State Transition**          | 상태가 있는 Feature | 상태 x 이벤트 나열 → 미정의 전이를 WBS 되돌림 대상 또는 기술적 Question으로 분류 |
+| **Perspective-Based Reading** | 최종 검토 시        | 테스터/개발자/사용자 관점 검토 → 빠진 것을 WBS 되돌림 대상 또는 기술적 Question으로 분류 |
 
 형식 — Rule별 그룹화, `[근거: ...]` 태그:
 
@@ -58,16 +95,18 @@ Question 도출 기법 — Feature 성격에 맞게 **하나 이상** 선택하
 ### Rule: 제목은 필수 [근거: wbs "태스크 생성 시 제목 필수"]
 - Example: 제목 입력 → 저장 성공
 - Example: 제목 비움 → 에러
-- Question: 제목 최대 길이 제한?
+- Question: 기존 입력 컴포넌트의 maxLength 처리 패턴?
 ```
 
 ### 2-3. 명확화
 
-`/sd-inner-clarify` 스킬을 호출하여 범위, Question, 기타 불명확한 부분을 명확화한다.
+`/sd-inner-clarify` 스킬을 호출하여 기술적 Question과 기타 How 불명확성을 명확화한다.
 답변에 따라 Rule/Example/Question을 갱신하며, 모든 Question이 해소될 때까지 **MUST** 반복한다. (추가 Question 발생 가능)
 - **나쁜 예:** "예약 기능 포함이 결정됨 → 예약 세부규칙(대기열 정책, 미대출 시 자동취소 기간)도 확정" — 기능 포함 여부와 세부 수치/규칙은 별개다. 세부사항은 별도로 분류·질문한다.
+- **나쁜 예:** "WBS에 제목 최대 길이가 없으니 sd-plan에서 100자로 결정" — 고객/업무 규칙이므로 WBS 되돌림 절차로 처리한다.
 
-해소된 결정사항은 `### 설계 결정` 테이블에 기록 (D1, D2, ... 순번 부여)
+해소된 기술 결정사항은 `### 설계 결정` 테이블에 기록 (D1, D2, ... 순번 부여)
+각 설계 결정은 `결정사항`, `선택`, `근거 유형`, `근거`를 기록한다. 근거 유형은 `WBS`, `사용자 답변`, `기준 코드`, `프로젝트 문서` 중 하나 이상이어야 한다.
 
 ## Step 3: Gherkin 생성
 
@@ -87,7 +126,7 @@ Feature: {번호} {이름}
 
 ## Step 4: 기준 코드 탐색
 
-**CRITICAL: 코드가 source of truth이다.** 구현계획 작성 전에 반드시 이 단계를 완료한다.
+**CRITICAL: 구현 패턴은 코드가 source of truth이다.** 구현계획 작성 전에 반드시 이 단계를 완료한다. 기준 코드 탐색을 완료하지 못했으면 Step 5로 진행하지 않는다.
 
 ### 4-1. 유사 기능 탐색
 
@@ -125,15 +164,25 @@ Feature: {번호} {이름}
 - UI 구조·레이아웃·컴포넌트 생김새 (HTML 골격, CSS 클래스 네이밍, 컨트롤 배치, 스타일 토큰): {관찰된 패턴} [근거: `파일경로:라인번호`]
 ```
 
-유사 기능을 찾을 수 없으면, 그 사실을 명시하고 프로젝트의 일반적 컨벤션(네이밍, 디렉토리 구조 등)만 기록한다.
+유사 기능을 찾을 수 없으면, 그 사실을 명시하고 탐색한 경로/검색어/확인한 파일을 기록한 뒤 프로젝트의 일반적 컨벤션(네이밍, 디렉토리 구조 등)만 기록한다. "유사 기능 없음"도 근거 없는 결론으로 쓰지 않는다.
 
 ## Step 5: 구현계획
 
+### 시작 조건
+
+다음 조건을 모두 만족해야 구현계획을 작성한다.
+
+- WBS 미확정/누락 항목이 없다.
+- 모든 기술적 Question이 해소되어 `### 설계 결정`에 근거와 함께 기록되었다.
+- Step 4 기준 코드 탐색이 완료되었고, 필요한 패턴에 `파일경로:라인번호` 근거가 있다.
+
+조건을 만족하지 못하면 구현계획을 작성하지 않고 해당 Step으로 되돌아간다.
+
 ### Tech Design Doc
 
 **CRITICAL: 기준 코드(Step 4)의 패턴을 따른다.** 기준 코드와 다른 패턴을 사용하려면 반드시 대안 검토에서 기존 패턴과 비교하고 사용자 확인을 받는다.
 
-각 항목에 `[근거: ...]` 태그로 출처를 명시한다. 코드 인용 시 `파일경로:라인번호`를 포함한다.
+각 항목에 `[근거: ...]` 태그로 출처를 명시한다. 코드 인용 시 `파일경로:라인번호`를 포함한다. 근거 없는 설계 항목은 작성하지 않는다.
 
 ```markdown
 ### 배경
@@ -178,11 +227,19 @@ Gherkin Scenarios를 구현 단위(Slice)로 분할한다.
 - WBS: @{wbs 문서 상대경로}
 {수집한 구체적 정보 — 참조 파일 경로는 `@path` 형태로 기록}
 
+## 확정/미확정 구분
+
+### 확정 사항
+- {WBS 또는 사용자 답변으로 확정된 고객 동작/업무 규칙/정책/수치/예외} [근거: ...]
+
+### 미확정/WBS 되돌림
+- 없음
+
 ## 기준 코드
 {Step 4에서 작성한 기준 코드 섹션}
 
 ### 설계 결정
-| # | 결정사항 | 선택 | 근거 |
+| # | 결정사항 | 선택 | 근거 유형 | 근거 |
 
 ## 요구명세
 {Gherkin}
@@ -195,14 +252,18 @@ Gherkin Scenarios를 구현 단위(Slice)로 분할한다.
 
 문서 작성 후, 대화에서 수집한 모든 구체적 정보가 문서에 기록되었는지 검증한다.
 
-- 사용자의 답변에 포함된 구체적 수치, 열거 항목, 업무 규칙, 제약 조건이 누락 없이 Feature 문서에 기록되었는가?
+- 사용자의 답변에 포함된 구체적 수치, 열거 항목, 업무 규칙, 제약 조건, 정책, 예외 조건, 상태 전이, 권한, 기간, 시간대, 검증 경계값, 오류 동작이 누락 없이 Feature 문서에 기록되었는가?
 - 언급된 참조 파일/문서 경로가 확인 목적과 함께 기록되었는가?
+- `확정 사항`, `미확정/WBS 되돌림`, `설계 결정`이 서로 섞이지 않고 분리되었는가?
+- 모든 Rule, Example, Scenario, 설계 결정, 구현계획 항목이 근거를 가지는가?
+- 근거 없는 "일반적으로", "기본값", "통상", "아마", "추정" 표현이 확정처럼 남아 있지 않은가?
 - 누락 발견 시 문서에 반영한 뒤 저장한다.
 
 ## Step 8: 역방향 피드백
 
 wbs 문서에 변경/발견 사항을 반드시 반영한다. 누락/불일치 수정을 생략하지 않는다.
-- 범위 축소/확대, 경계 재조정, 설계 결정 요약, Feature 간 범위 이관 등
+- 범위 축소/확대, 경계 재조정, Feature 간 범위 이관 등 고객 중심 What에 해당하는 변경만 반영한다.
+- API 형태, DB 구조, UI 컴포넌트 구조, 테스트 Slice 같은 How 결정은 WBS에 기록하지 않고 Feature 문서의 `### 설계 결정`과 `## 구현계획`에만 기록한다.
 문서 간 정합성을 유지하고 변경 사유를 명확히 작성한다.
 역방향 피드백의 목적은, 새로운 세션에서 다른 작업을 수행할때 이 세션의 결정사항을 잊지 않고 이어서 하기 위함이다.