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

docs/agent-guide/documentation.md

@@ -7,6 +7,10 @@
 - PRD를 작성·변경할 때는 [PRD 작성 및 유지보수 규칙](./prd.md)과 [PRD 샘플](../sample/sample-prd.md)을 따른다.
 - 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다.
 - 구현 완료 시마다 체크박스를 `- [x]`로 갱신하고, 각 항목이 정상 구현되었는지 확인한다.
+- `plan-task.md`의 각 Task는 TDD 적용 여부를 명시한다. 테스트 가능한 구현 Task에는 `TDD 절차`를 두고 `RED: 실패 테스트 작성/실패 확인`, `GREEN: 최소 구현/통과 확인`, `REFACTOR: 정리/회귀 확인` 순서를 적는다.
+- 실패 테스트 작성이 현실적으로 불가능한 Task는 TDD 절차를 아무 표시 없이 생략하지 말고 같은 Task에 `TDD 예외 사유`와 `대체 검증 방법`을 구체적으로 기록한다.
+- 각 Task에는 `실행 명령`, `기대 결과`, `수동 확인`을 포함한 검증 기준을 작성한다. 수동 확인이 불필요하면 `없음`과 그 사유를 적는다.
+- 각 Phase의 Gate에도 통합 검증을 위한 실행 명령, 기대 결과, 수동 확인 항목을 작성한다.
 - 작업 도중 범위가 변경되면 계획 문서의 체크박스 항목을 먼저 업데이트한 뒤 구현을 진행한다.
 - 모든 구현이 끝난 후 결과 보고 시 계획 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 기록한다.
 - 후속 수정이 발생해도 기존 검증 기록은 삭제/덮어쓰지 않고 누적한다(예: `1차 구현`, `2차 수정`).
@@ -14,4 +18,5 @@
 - 단계별 `어떻게`에는 실제 실행한 검증 명령과 결과(성공/실패/불가 사유)를 함께 기록한다.
 - 기존 기록 정정이 필요하면 원문을 지우지 말고 `정정` 항목을 추가해 사유와 변경 내용을 남긴다.
 - goal 기능으로 실행할 구현 계획은 [Goal 실행형 구현 계획 규칙](./goal-plan.md)과 [Goal 실행형 계획 샘플](../sample/sample-plan-task.md)을 따른다.
-- 완료된 Phase 또는 Task의 코드 리뷰·QA 결과 문서는 해당 `prd.md`와 같은 디렉터리에 두고, 상세 형식과 후속 처리에는 [코드 리뷰 및 QA 기록 규칙](./review.md)을 따른다.
+- 완료된 Phase 또는 Task의 코드 리뷰·QA 결과 문서는 해당 `prd.md`·`plan-task.md` 디렉터리 아래 `reviews/`에 모아 둔다. 기능 문서 디렉터리 바로 아래나 단수형 `review/`에는 두지 않는다.
+- 리뷰 문서의 상세 형식, 파일명과 참조 방법은 [코드 리뷰 및 QA 기록 규칙](./review.md)을 따른다.

docs/agent-guide/environment.md

@@ -2,4 +2,9 @@
 
 - 개발 서버 API: `VITE_API_BASE_URL=https://test-character-admin.sodalive.net`
 - 프로덕션 서버 API: `VITE_API_BASE_URL=https://character-admin.sodalive.net`
+- API mode: `VITE_API_MODE=server | mock`. 누락 시 `server`이며, `mock`은 개발 환경에서만 허용한다.
 - Vite mode별 파일은 `.env.development`, `.env.production`을 사용한다.
+- 기본 `npm run dev`는 `server` mode로 실제 개발 API를 사용하고, `npm run dev:mock`만 browser MSW를 시작한다.
+- production build에서 `VITE_API_MODE=mock`은 시작 전에 오류로 거부한다.
+- mock data reset: mock data는 browser storage에 영구 저장하지 않고 새 mock store/session이 시작될 때 seed 기준으로 초기화한다.
+- no-auto-fallback: server mode의 404 또는 network error를 mock mode로 자동 전환하지 않는다.

docs/agent-guide/goal-plan.md

@@ -36,6 +36,8 @@
 - 하나 이상의 Task
 - Task 전체 완료 조건
 - 자동·수동 검증 방법과 Phase Gate
+- 각 Task의 TDD 절차 또는 TDD 예외 사유와 대체 검증 방법
+- 각 Task와 Phase Gate의 실행 명령, 기대 결과, 수동 확인 항목
 
 ## 4. Task와 goal 작성 규칙
 
@@ -43,8 +45,17 @@
 - 모든 Task에는 고유 Goal ID, 한 문장 objective, 시작 조건, 완료 증거와 범위 밖을 둔다.
 - Goal ID는 `P<Phase>-T<Task>`를 사용한다. Phase Gate는 `P<Phase>-GATE`, 완료 범위의 회귀 수정은 `P<Phase>-R<번호>`를 사용한다.
 - Task는 독립 reviewer가 이웃 Task와 별도로 승인·거절할 수 있고, 자체 test cycle로 검증할 수 있는 최소 결과 단위로 나눈다.
-- Task마다 생성·수정·test 파일의 정확한 경로를 기록한다. 선행 Task contract를 소비하거나 후속 Task에 제공하면 `Interfaces`에 정확한 type·function·component를 기록한다.
-- 구현 체크박스는 실패 test 작성 → 의도한 실패 확인 → 최소 구현 → focused test 성공 → 관련 품질 검증 → Progress 기록 순서를 포함한다.
+- Task마다 생성·수정·test 파일의 정확한 경로를 기록한다. TDD 예외 Task에 test 파일이 없으면 `Test: 없음`과 사유를 적는다. 선행 Task contract를 소비하거나 후속 Task에 제공하면 `Interfaces`에 정확한 type·function·component를 기록한다.
+- 모든 구현 Task의 `TDD 절차`에는 다음 순서와 확인 내용을 명시한다.
+  - `RED: 실패 테스트 작성/실패 확인` — 검증할 동작과 실패 테스트 파일, 실행 명령, 의도한 실패 결과를 적는다.
+  - `GREEN: 최소 구현/통과 확인` — 최소 구현 범위와 동일한 테스트 명령의 통과 결과를 적는다.
+  - `REFACTOR: 정리/회귀 확인` — 동작을 바꾸지 않는 정리 범위와 focused·관련 회귀 테스트 결과를 적는다.
+- 실패 테스트 작성이 현실적으로 불가능한 문서화, 조사, 외부 의존 작업 등은 같은 Task에 `TDD 예외 사유`와 `대체 검증 방법`을 명시한다. 단순히 `해당 없음`만 적거나 산출물과 무관한 테스트를 만드는 것으로 대체하지 않는다.
+- 각 Task의 `검증 기준`에는 다음을 포함한다.
+  - `실행 명령`: focused test, 관련 회귀 test, typecheck·lint 또는 TDD 예외의 대체 검증 등 실제 실행할 명령
+  - `기대 결과`: 종료 코드, 통과할 test 수, 예상 출력 또는 상태 변화
+  - `수동 확인`: 사용자가 확인할 화면·동작·문서 항목. 불필요하면 `없음`과 사유를 기록한다.
+- 구현 체크박스 마지막에는 검증 결과와 `Progress` 기록을 포함한다.
 - “적절히 처리”, “나중에 구현”, “위와 동일”처럼 실행자가 다시 추측해야 하는 표현을 사용하지 않는다.
 
 ## 5. 완료와 차단 판정
@@ -52,6 +63,8 @@
 - 동시에 하나의 미완료 goal만 운용한다. 활성 goal이 있으면 새 goal을 만들지 않고 같은 Task를 이어서 수행한다.
 - 사용자가 명시적으로 요청하지 않으면 token budget을 설정하지 않는다.
 - 코드 작성이나 일부 test만 끝난 상태는 완료가 아니다. 체크박스, 완료 증거, 실제 검증과 Progress 기록까지 충족한 뒤에만 goal을 `complete`로 갱신한다.
+- 구현 Task는 RED/GREEN/REFACTOR 각 단계의 결과가 없으면 완료할 수 없다.
+- TDD 예외 Task는 예외 사유와 대체 검증 결과가 없으면 완료할 수 없다.
 - Phase의 모든 활성 Task goal을 완료한 뒤 Phase Gate를 별도 goal로 실행한다.
 - 외부 계약이나 권한 같은 동일 차단 사유가 최초 시도와 자동 후속을 포함해 3회 연속 반복되고, 문서화·독립 작업 등 의미 있는 진전도 불가능할 때만 goal을 `blocked`로 갱신한다.
 - 계약이 없어 안전하게 구현할 수 없으면 추정하지 않는다. 담당 주체·영향·재개 조건을 기록하고 PRD 결정 기록 → API Contract → `plan-task.md` 순서로 제외 또는 후속 결정을 반영한다.
@@ -62,6 +75,7 @@
 - 범위나 구현 방식이 바뀌면 코드를 수정하기 전에 관련 체크박스, Files, Interfaces, 완료 증거와 Decision Log를 갱신한다.
 - Progress와 Decision Log의 기존 기록은 삭제하거나 덮어쓰지 않는다. 정정은 날짜·사유와 함께 새 기록으로 추가한다.
 - 실행한 명령만 기록하고 성공/실패, exit code, test 수 또는 불가 사유를 남긴다.
+- 구현 Task의 Progress에는 RED의 의도한 실패, GREEN의 통과, REFACTOR의 회귀 확인 결과를 구분해 기록한다. TDD 예외 Task는 대체 검증의 실제 결과를 기록한다.
 - 구현 중 발견한 범위 내 문제는 `발견된 문제`에 기록한다. 완료 범위의 상세 리뷰·QA는 [코드 리뷰 및 QA 기록 규칙](./review.md)에 따라 별도 review 문서로 관리한다.
 - Phase 완료 후 현재 상태 표와 체크박스를 갱신하고 Phase Gate의 최신 증거를 Progress에 누적한다.
 
@@ -75,6 +89,7 @@ goal을 만들기 전에 다음을 확인한다.
 - Files와 Interfaces의 이름이 앞뒤 Task에서 일치한다.
 - 외부 의존과 안전한 기본값이 구분돼 있다.
 - backend 구현 전 UI preview가 필요하면 제공 계약 기반 explicit mock mode와 실제 server integration을 별도 Task·Gate·Progress로 구분하고 404 자동 fallback을 금지한다.
-- 실제 검증 명령과 Expected가 구체적이다.
+- 각 구현 Task에 RED/GREEN/REFACTOR 절차가 있고, 예외 Task에는 예외 사유와 대체 검증 방법이 있다.
+- 각 Task와 Phase Gate의 실행 명령, 기대 결과, 수동 확인 항목이 구체적이다.
 - placeholder, 미정 값, 추정 계약이 없다.
 - 변경 금지 항목과 중단 규칙이 명시돼 있다.

docs/agent-guide/review.md

@@ -9,9 +9,11 @@
 ## 2. 기준 문서와 템플릿
 
 - 리뷰 전에 대상 기능 디렉터리의 `prd.md`, `api-contract.md`, `plan-task.md`와 관련 구현·test를 읽는다.
-- 리뷰 문서는 대상 `prd.md`와 같은 디렉터리에 만든다.
+- 대상 `prd.md`와 `plan-task.md`가 있는 기능 문서 디렉터리 아래 `reviews/`를 만들고 모든 리뷰 문서를 그 안에 둔다.
+- 리뷰 문서를 기능 문서 디렉터리 바로 아래나 단수형 `review/`에 두지 않는다. 여러 Phase·Task 리뷰가 생겨도 같은 `reviews/`에 누적한다.
 - [코드 리뷰 보고서 샘플](../sample/sample-review.md)을 원본 템플릿으로 사용하고, section·필드·상태 의미를 임의로 축소하지 않는다.
 - 실제 리뷰 문서 파일명은 범위가 드러나게 작성한다. 예: `review-phase-0-1.md`, `review-auth.md`.
+- `prd.md`나 `plan-task.md`에서 리뷰 문서를 참조할 때는 `./reviews/<리뷰 파일명>.md` 상대 링크를 사용한다.
 
 ## 3. 리뷰 수행 원칙
 

docs/agent-guide/scripts.md

@@ -1,6 +1,7 @@
 # 실행 스크립트
 
 - 개발 서버: `npm run dev` (`http://127.0.0.1:8888`)
+- Mock preview 개발 서버: `npm run dev:mock` (`http://127.0.0.1:8889`)
 - 개발 서버용 빌드: `npm run build:dev`
 - 프로덕션 서버용 빌드: `npm run build:prod`
 - 기본 프로덕션 빌드: `npm run build`
@@ -8,5 +9,7 @@
 - 린트: `npm run lint`
 - Vitest watch: `npm run test`
 - Vitest 단발 실행: `npm run test:run`
-- Playwright E2E: `npm run e2e`
+- Playwright E2E(server mode): `npm run e2e`는 `playwright.config.ts`의 server mode `testMatch`에 있는 spec만 실행하며, 추가 file filter를 넘기면 교집합만 실행한다.
+- Playwright E2E(mock mode): `npm run e2e:mock`은 `playwright.config.ts`의 mock mode `testMatch`에 있는 spec만 실행하며, 추가 file filter를 넘기면 교집합만 실행한다.
+- Mock preview domain rule: 후속 도메인 Phase는 자기 handler, fixture, mock E2E를 같은 Phase에서 소유하고 추가한다.
 - Phase 0 Gate 기준: `npm ci`, `npx playwright install chromium webkit`, `npm run typecheck`, `npm run lint`, `npm run test:run -- src/app/App.test.tsx src/shared/config/env.test.ts`, `npm run e2e -- tests/e2e/smoke.spec.ts`, `npm run build:dev`, `npm run build:prod`