feat(ai-character): Mock Preview 모드 구현

docs/sample/sample-plan-task.md

@@ -1,6 +1,6 @@
 # Goal 실행형 구현 계획 샘플
 
-> 이 문서는 goal 기능으로 구현 계획을 실행하기 위한 템플릿이다. 실제 `plan-task.md`를 만들 때 `<...>` placeholder를 모두 구체적인 값으로 교체한다. Phase는 결과와 의존성을 묶고, `create_goal`에는 Task 또는 Phase Gate 하나만 등록한다.
+> 이 문서는 goal 기능으로 구현 계획을 실행하기 위한 템플릿이다. 실제 `plan-task.md`를 만들 때 `<...>` placeholder를 모두 구체적인 값으로 교체한다. Phase는 결과와 의존성을 묶고, `create_goal`에는 Task 또는 Phase Gate 하나만 등록한다. 각 구현 Task에는 RED/GREEN/REFACTOR 절차를, 테스트가 현실적으로 불가능한 Task에는 TDD 예외 사유와 대체 검증 방법을 적고, 모든 Task와 Phase Gate에 실행 명령·기대 결과·수동 확인을 둔다.
 
 | 문서 항목 | 내용 |
 |---|---|
@@ -49,7 +49,7 @@
 - 의존성: 실제 소비 Task에서 필요한 최소 dependency만 추가한다.
 - 계약: 제공되지 않은 endpoint, DTO, enum, 오류 status/key와 validation 상한을 추정하지 않는다.
 - backend 구현 전 UI 확인이 필요하면 제공 계약 기반 explicit mock mode를 사용하고 실제 404 자동 fallback·production mock을 금지하며 mock/server 완료 증거를 분리한다.
-- 구현: 모든 기능은 가장 작은 실패 test를 먼저 만들고 최소 구현으로 통과시킨다.
+- 구현: 모든 기능은 `RED: 실패 테스트 작성/실패 확인` → `GREEN: 최소 구현/통과 확인` → `REFACTOR: 정리/회귀 확인` 순서로 진행한다. 실패 테스트가 현실적으로 불가능하면 Task에 TDD 예외 사유와 대체 검증 방법을 먼저 확정한다.
 
 ## Phase 1
 
@@ -80,11 +80,19 @@
 - Consumes: `<선행 Task가 제공하는 type/function/component contract>`
 - Produces: `<후속 Task가 사용할 정확한 type/function/component contract>`
 
-- [ ] 가장 작은 실패 test를 작성한다.
-- [ ] `<focused test 명령>`을 실행해 의도한 assertion 실패를 확인한다.
-- [ ] test를 통과시키는 최소 구현을 작성한다.
-- [ ] `<focused test 명령>`을 다시 실행해 성공을 확인한다.
-- [ ] 관련 typecheck·lint를 실행하고 실제 결과를 Progress에 기록한다.
+**TDD 절차:**
+
+- [ ] **RED: 실패 테스트 작성/실패 확인** — `<정확한 test 파일 경로>`에 `<검증할 동작>`의 가장 작은 실패 test를 작성하고 `<focused test 명령>` 실행 시 `<의도한 assertion 메시지>`로 실패하는지 확인한다.
+- [ ] **GREEN: 최소 구현/통과 확인** — `<정확한 구현 파일 경로>`에 test를 통과시키는 최소 구현만 작성하고 같은 명령이 `exit 0`, `<N개 test 통과>`인지 확인한다.
+- [ ] **REFACTOR: 정리/회귀 확인** — 중복·이름·구조만 정리한 뒤 `<focused test 명령>`과 `<관련 회귀 test 명령>`이 모두 `exit 0`인지 확인한다.
+
+**검증 기준:**
+
+- **실행 명령:** `<focused test 명령>`, `<관련 회귀 test 명령>`, `<typecheck 명령>`, `<lint 명령>`
+- **기대 결과:** 모든 명령 `exit 0`, `<focused N개·회귀 N개 test>` 통과, type·lint 오류 0건.
+- **수동 확인:** `<viewport>`에서 `<사용자 동작>` 시 `<관찰 가능한 상태 변화>`가 발생하고 금지 동작은 발생하지 않는다.
+
+- [ ] TDD 단계와 검증 기준의 실제 결과를 Progress에 기록한다.
 
 #### Task 1.2 `<두 번째 독립 결과>`
 
@@ -105,10 +113,19 @@
 - Consumes: `<P1-T1이 제공한 정확한 contract>`
 - Produces: `<Phase 2 또는 Gate가 사용할 정확한 contract>`
 
-- [ ] 가장 작은 실패 test를 작성하고 의도한 실패를 확인한다.
-- [ ] 최소 구현으로 focused test를 통과시킨다.
-- [ ] 오류·loading·empty·success와 접근성 상태를 검증한다.
-- [ ] 관련 test·typecheck·lint 결과를 Progress에 기록한다.
+**TDD 절차:**
+
+- [ ] **RED: 실패 테스트 작성/실패 확인** — `<정확한 test 파일 경로>`에 `<오류·loading·empty·success 중 이 Task가 소유한 상태>`와 `<사용자 action>`의 실패 test를 작성하고 `<focused test 명령>`이 의도한 이유로 실패하는지 확인한다.
+- [ ] **GREEN: 최소 구현/통과 확인** — 필요한 상태와 action만 최소 구현하고 같은 명령이 `exit 0`, `<N개 test 통과>`인지 확인한다.
+- [ ] **REFACTOR: 정리/회귀 확인** — 상태 분기와 접근성 이름을 정리한 뒤 `<focused test 명령>`과 `<P1-T1 관련 회귀 test 명령>`이 모두 통과하는지 확인한다.
+
+**검증 기준:**
+
+- **실행 명령:** `<focused UI test 명령>`, `<P1-T1 관련 회귀 test 명령>`, `<typecheck 명령>`, `<lint 명령>`
+- **기대 결과:** 모든 명령 `exit 0`, `<상태·action별 N개 test>` 통과, type·lint 오류 0건.
+- **수동 확인:** `<지원 viewport>`에서 오류·loading·empty·success 상태, keyboard focus 순서와 accessible name을 확인한다.
+
+- [ ] TDD 단계와 검증 기준의 실제 결과를 Progress에 기록한다.
 
 ### 완료 조건
 
@@ -126,6 +143,8 @@
 - **완료 증거:** 아래 자동·수동 검증 통과와 Progress 기록.
 - **범위 밖:** Gate 통과를 위한 test 삭제·완화와 관련 없는 기능 수정.
 
+**실행 명령:**
+
 ```bash
 <focused unit/integration test 명령>
 <Phase 전용 E2E 명령>
@@ -134,9 +153,9 @@
 <build 명령>
 ```
 
-**Expected:** `<0 exit code, test 수, 사용자가 완료할 흐름, 금지 요청 0회 등 관찰 가능한 결과>`
+**기대 결과:** `<모든 명령 exit 0, test 수, 사용자가 완료할 흐름, 금지 요청 0회 등 관찰 가능한 결과>`
 
-수동 검증:
+**수동 확인:**
 
 - [ ] `<viewport와 사용자 흐름>`
 - [ ] `<keyboard·focus·zoom·접근성 검사>`
@@ -160,11 +179,41 @@
 - **완료 증거:** 계약 제공 또는 제외 결정이 기준 문서에 일치하고 구현 map이 기록됨.
 - **범위 밖:** 계약을 추정한 production adapter와 실제 기능 구현.
 
+**Files:**
+
+- Modify: `<대상 prd.md 경로>`
+- Modify: `<대상 api-contract.md 경로>`
+- Modify: `<대상 plan-task.md 경로>`
+- Test: 없음 — 이 Task의 산출물은 실행 코드가 아니라 확정된 계약과 구현 map이다.
+
+**Interfaces:**
+
+- Consumes: `<PRD 요구사항 ID와 외부에서 제공한 API 계약>`
+- Produces: `<P2-T2가 사용할 endpoint·DTO·상태/action·component/file map>`
+
+**TDD 예외 사유:** 이 Task는 실행 가능한 동작을 구현하지 않고 외부 근거로 계약과 책임 경계를 확정한다. 계약 확정 전에 실패 테스트를 만들면 제공되지 않은 endpoint·DTO를 추정하게 되므로 산출물을 올바르게 검증할 수 없다.
+
+**대체 검증 방법:** PRD·API Contract·plan의 요구사항과 이름을 상호 대조하고, 금지된 미정 표현과 Markdown 변경 오류를 명령으로 검사한 뒤 문서의 추적성을 수동 확인한다.
+
 - [ ] 필요한 endpoint·DTO·오류·pagination 계약을 확인한다.
 - [ ] loading·empty·error·success·read-only·viewport 상태와 action을 inventory한다.
 - [ ] 계약이 없으면 담당 주체·영향·재개 조건과 제외/후속 결정을 문서화한다.
 - [ ] Page·feature·shared component와 test file 책임을 확정한다.
 
+**검증 기준:**
+
+- **실행 명령:**
+
+  ```bash
+  ! rg --pcre2 -n '^(?!\s*!?\s*rg\b).*(?:TBD|TODO|적절히 처리|나중에 구현|위와 동일)' <대상 prd.md 경로> <대상 api-contract.md 경로> <대상 plan-task.md 경로>
+  git diff --check -- <대상 prd.md 경로> <대상 api-contract.md 경로> <대상 plan-task.md 경로>
+  ```
+
+- **기대 결과:** 두 명령 모두 출력 없이 `exit 0`; 모든 요구사항 ID와 계약 이름이 세 문서에서 일치한다.
+- **수동 확인:** endpoint·DTO·오류·pagination 및 상태/action 각각에 근거 또는 담당 주체·영향·재개 조건이 있고, P2-T2의 Files와 Interfaces가 구현 결정을 내릴 만큼 구체적이다.
+
+- [ ] 대체 검증의 실제 결과를 Progress에 기록한다.
+
 #### Task 2.2 `<Phase 2의 독립 구현 결과>`
 
 **Goal 실행 `P2-T2`:** `<사용자가 직접 확인할 수 있는 흐름을 한 문장으로 작성한다.>`
@@ -179,11 +228,24 @@
 - Modify: `<정확한 파일 경로>`
 - Test: `<정확한 test 파일 경로>`
 
-- [ ] contract와 serializer의 실패 test를 먼저 작성한다.
-- [ ] UI 상태와 사용자 action의 실패 test를 먼저 작성한다.
-- [ ] 최소 구현으로 focused test를 통과시킨다.
-- [ ] 관련 integration/E2E와 공통 품질 명령을 실행한다.
-- [ ] 실제 결과와 남은 항목을 Progress에 기록한다.
+**Interfaces:**
+
+- Consumes: `<P2-T1에서 확정한 endpoint·DTO·상태/action contract>`
+- Produces: `<P2-GATE가 검증할 adapter·component·사용자 흐름 contract>`
+
+**TDD 절차:**
+
+- [ ] **RED: 실패 테스트 작성/실패 확인** — `<contract test 파일>`과 `<UI test 파일>`에 serializer, 상태와 사용자 action의 가장 작은 실패 test를 작성하고 `<focused test 명령>`이 `<의도한 실패 이유>`로 실패하는지 확인한다.
+- [ ] **GREEN: 최소 구현/통과 확인** — P2-T1의 확정 계약만 사용하는 최소 adapter·UI를 구현하고 같은 명령이 `exit 0`, `<N개 test 통과>`인지 확인한다.
+- [ ] **REFACTOR: 정리/회귀 확인** — contract 변환과 UI 상태 책임을 정리한 뒤 `<focused test 명령>`과 `<관련 integration/E2E 명령>`이 모두 통과하는지 확인한다.
+
+**검증 기준:**
+
+- **실행 명령:** `<focused contract/UI test 명령>`, `<관련 integration/E2E 명령>`, `<typecheck 명령>`, `<lint 명령>`, `<build 명령>`
+- **기대 결과:** 모든 명령 `exit 0`, `<contract/UI/E2E별 N개 test>` 통과, type·lint·build 오류 0건, 금지된 request 0회.
+- **수동 확인:** `<지원 viewport>`에서 success·loading·empty·error·read-only 흐름과 keyboard·focus 동작을 확인하고 실제 request payload가 API Contract와 일치한다.
+
+- [ ] TDD 단계와 검증 기준의 실제 결과 및 남은 항목을 Progress에 기록한다.
 
 ### 완료 조건
 
@@ -198,16 +260,24 @@
 **Goal 실행 `P2-GATE`:** Phase 2의 contract, 사용자 흐름과 회귀 방지를 최종 판정한다.
 
 - **시작 조건:** Phase 2의 모든 활성 Task goal 완료.
-- **완료 증거:** 아래 명령과 Expected 통과, Progress에 실제 결과 누적.
+- **완료 증거:** 아래 실행 명령, 기대 결과와 수동 확인을 모두 통과하고 Progress에 실제 결과 누적.
 - **범위 밖:** 실패와 무관한 다음 Phase 구현.
 
+**실행 명령:**
+
 ```bash
 <Phase 2 focused test 명령>
 <Phase 2 E2E 명령>
 <typecheck·lint·build 명령>
 ```
 
-**Expected:** `<사용자 journey, 오류 처리, request payload와 금지 동작을 포함한 최종 결과>`
+**기대 결과:** `<모든 명령 exit 0, test 수, 사용자 journey, 오류 처리, request payload와 금지 동작을 포함한 최종 결과>`
+
+**수동 확인:**
+
+- [ ] `<지원 viewport에서 success·loading·empty·error·read-only 흐름>`
+- [ ] `<keyboard·focus·zoom·접근성 동작>`
+- [ ] `<API Contract와 실제 request·response 및 production mock 미사용>`
 
 ## 실행 순서와 의존성
 
@@ -252,6 +322,11 @@ P1-T1 → P1-T2 → P1-GATE → P2-T1 → P2-T2 → P2-GATE
 - 상태: 진행 중 / 완료 / 차단 감사 중 / 차단
 - 무엇을: `<이번 실행에서 완료한 체크박스와 산출물>`
 - 왜: `<Task objective와 요구사항 근거>`
+- TDD: `<구현 Task는 RED/GREEN/REFACTOR만, 예외 Task는 예외 항목만 남긴다.>`
+  - RED: `<실패 test 명령>` — `<의도한 실패, exit code와 assertion>`
+  - GREEN: `<같은 focused test 명령>` — `<성공, exit code와 test 수>`
+  - REFACTOR: `<focused·관련 회귀 test 명령>` — `<성공/실패, exit code와 test 수>`
+  - 예외 Task: `<TDD 예외 사유와 대체 검증 결과. 구현 Task에서는 이 행을 삭제한다.>`
 - 어떻게:
   - `<실행 명령>` — `<성공/실패, exit code, test 수와 핵심 결과>`
   - `<수동 검증>` — `<성공/실패/불가 사유>`
@@ -276,7 +351,7 @@ P1-T1 → P1-T2 → P1-GATE → P2-T1 → P2-T2 → P2-GATE
 - 구현 중 발견한 범위 내 문제는 근거와 재현 방법을 기록하고 해당 Task에서 처리한다.
 - 완료된 범위의 회귀는 기존 Task를 다시 열지 않고 별도 회귀 수정 Task와 goal을 만든다.
 - 범위 밖 문제는 임의로 수정하지 않고 사용자에게 보고하거나 후속 Task로 결정한다.
-- 상세 코드 리뷰 결과가 필요하면 `sample-review.md` 형식의 별도 review 문서를 사용한다.
+- 상세 코드 리뷰 결과가 필요하면 기능 문서 디렉터리의 `reviews/` 아래에 `sample-review.md` 형식의 별도 review 문서를 만든다.
 
 ## 최종 보고 형식