# 문서 정합성 리뷰

## 한 줄 판단

`docs/architecture`와 `docs/architecture-refactor-final`은 배경 설명과 리팩토링 기록으로는 가치가 있지만, 현재 저장소의 실행 계약과 품질 상태를 그대로 믿으면 잘못된 결론에 도달한다.

## 1. 코드와 문서가 맞는 부분

- 프로젝트 목표
  - `README.md:1-6`과 `docs/architecture/00-overview.md:3-4`의 "시나리오 PDF → 웹북용 이미지" 방향은 현재 코드와 맞다.
- 프런트 상위 페이지 정리
  - `docs/architecture/00-overview.md:10`의 React Query 전환과 `EpisodeDetail` 축소는 실제 구현과 부합한다.
  - `frontend/src/pages/EpisodeDetail.tsx:19-148`은 query hook 조합 + local state 1개 구조다.
- deprecated 분석 경로의 내부 수렴
  - `backend/app/api/v1/episodes.py:135-260`는 `/analyze`, `/reanalyze-scenes`가 살아 있지만 내부적으로 dispatch 서비스로 위임됨을 명시한다.
- silent failure 제거
  - `backend/app`, `backend/scripts` 기준 `except: pass` 검색 결과는 없다.

## 2. 틀리거나 낡은 부분

### 2.1 Step 수와 applicability 수치가 현재 코드와 다르다

문서 주장:

- `docs/architecture/00-overview.md:165-166`은 총 48단계, active 40, `on_demand` 5, `disabled` 3이라고 적는다.
- `docs/architecture/06-data-contracts.md:9`도 active 40 / 총 48 전제를 둔다.
- `docs/architecture-refactor-final/README.md:76-77`도 "48단계"를 완료 기준처럼 서술한다.

실제 코드:

- `backend/tests/test_step_manifest_v3.py:13-30`은 총 49 / analysis 42 / image 5 / auxiliary 2를 고정한다.
- 실제 `STEP_MANIFEST` 실측도 동일했다.
- applicability 분포는 `always 38 / on_demand 4 / disabled 4 / if_planning_doc 1 / if_set_design_enabled 1 / if_has_outlooks 1`이다.

해석:

- "active 40"은 기본 경로만 보면 맞지만, 문서는 전체 분포와 총량을 틀리게 적고 있다.
- 특히 `if_set_design_enabled`를 별도 축으로 빼지 않아 "40인가 41인가" 해석 혼선이 생긴다.

### 2.2 `architecture-refactor-final`의 완료/green 서술은 저장소 전체 상태를 대표하지 못한다

문서 주장:

- `docs/architecture-refactor-final/README.md:4-24`는 Phase 0~5 전체 완료, backend 256 tests passed를 강조한다.
- `docs/architecture-refactor-final/test-plan.md:4`도 현재 상태를 `256 passed`로 적는다.
- 같은 문서 `docs/architecture-refactor-final/test-plan.md:41`은 `375 tests / 8 collection errors`를 기준으로 설명한다.

실제 실행:

- `backend/.venv/bin/python -m pytest backend/tests -q`
- 결과: `637 passed, 56 failed, 2 errors, 1 skipped`

해석:

- refactor 문서가 말하는 수치는 "이번 리팩토링에서 추가한 subset" 또는 특정 시점의 내부 baseline일 수 있다.
- 하지만 README급 문서에는 repo 전체 품질 상태처럼 읽힌다.
- 현재는 "subset green"과 "repo green"이 문서에서 분리되어 있지 않다.

### 2.3 "프런트는 StepRunner만 쓴다"는 서술은 더 이상 맞지 않는다

문서 주장:

- `docs/architecture-refactor-final/README.md:81-83`
- `docs/architecture-refactor-final/01-principles-revised.md:321-339`

실제 코드:

- `frontend/src/pages/EpisodeDetail.tsx:81-97`는 `/steps/run-all`과 개별 step API를 호출한다.
- `frontend/src/pages/Episodes.tsx:46-59`는 `useAnalyzeEpisode`를 통해 분석 시작 mutation을 사용한다.
- `frontend/src/hooks/api/mutations/useAnalyzeEpisode.ts:11-16`는 여전히 `/api/v1/projects/{projectId}/episodes/{episodeId}/analyze`를 호출한다.

해석:

- 내부 엔진은 StepRunner dispatch에 수렴했지만, 프런트 공개 계약은 아직 두 갈래다.
- 문서는 "내부 수렴"과 "제품 계약 수렴"을 구분하지 않는다.

### 2.4 `docs/architecture/06-data-contracts.md`는 현행 구현보다 뒤쳐져 있다

문서 주장:

- `docs/architecture/06-data-contracts.md:13-24`는 `step_type`을 "Phase 1 도입 예정"으로 설명한다.
- `docs/architecture/06-data-contracts.md:28-32`는 `AnalysisService.run_analysis()`를 deprecated 경로의 원형처럼 적는다.
- `docs/architecture/06-data-contracts.md:36`는 mutation 파일 수를 `9개`로 적는다.

실제 코드:

- `backend/app/core/step_manifest.py`에는 이미 `step_type`, `lifecycle`, `resume_sensitive`가 들어 있다.
- `backend/app/services/analysis_service.py`는 존재하지 않는다.
- `frontend/src/hooks/api/mutations/` 아래 실제 mutation 파일은 7개다.

해석:

- 이 문서는 "리팩토링 이전 설명 + 일부 완료 후 설명"이 섞여 있다.
- 개발자가 계약 문서로 사용하기에는 시점이 맞지 않는다.

### 2.5 line-level 증거가 낡았다

대표 사례:

- `docs/architecture-refactor-final/README.md:81`는 `EpisodeDetail.tsx:821`를 증거로 쓴다.
- 실제 파일은 `frontend/src/pages/EpisodeDetail.tsx:19-148`이다.

해석:

- 줄 번호까지 들어간 문서가 최신 코드 기준으로 재검증되지 않았다는 뜻이다.
- 이 레벨의 낡은 증거는 문서 신뢰도를 크게 떨어뜨린다.

### 2.6 제품 논의 문서도 운영 기준치로는 부정확하다

문서 주장:

- `docs/product-roadmap-discussion.md:11`은 이 시스템을 "36단계 자동화"로 소개한다.
- 같은 문서 `docs/product-roadmap-discussion.md:37`도 36단계를 반복 언급한다.

실제 코드:

- 현재 `STEP_MANIFEST`는 총 49 step이다.

해석:

- 이 문서는 토론용 자료이지 실행 계약 문서가 아니다.
- 비개발자용 설명으로는 괜찮지만, 현재 파이프라인 구조를 대표하는 숫자로 쓰면 오해를 만든다.

### 2.7 이미지 도메인 "완료" 서술도 읽는 방식에 따라 과장될 수 있다

문서 주장:

- `docs/architecture-refactor-final/README.md:14`는 `ImageService 5,281→1,224`와 3개 서비스 분리를 완료로 적는다.

실제 코드:

- `backend/app/services/image_service.py:1-83`은 "shim"이라고 선언하지만 파일 자체는 여전히 1,228줄이다.
- `backend/app/api/v1/images.py:22-24`는 `ImageService`, `ReferenceImageService`, `SceneImageService`를 동시에 import한다.

해석:

- "완전히 제거"가 아니라 "호환 shim을 남긴 채 분해"가 실제 상태다.
- 방향은 맞지만 문장만 보면 더 정리된 것처럼 읽힌다.

## 3. 현재 문서를 어떻게 읽어야 하는가

| 문서 세트 | 현재 위치 |
|---|---|
| `docs/architecture/` | 구조 설명용. 다만 수치와 일부 계약은 재측정 필요 |
| `docs/architecture-refactor-final/` | 리팩토링 기록/아카이브. subset 성과와 역사적 맥락은 유용 |
| `docs/product-roadmap-discussion.md` | 제품 방향 토론 자료. 실행 계약 문서로 쓰면 안 됨 |
| `docs/review-codex-1/` | 현재 저장소 상태를 재측정한 보정 문서 |

## 4. 권고

1. 릴리스 문서에는 반드시 두 숫자를 분리해 적는다.
   - refactor subset 결과
   - repo 전체 결과
2. step 수와 applicability 분포는 수동 서술보다 테스트/스크립트 기반 표를 쓰는 편이 낫다.
3. `architecture-refactor-final`은 "최종 확정안"보다 "리팩토링 기록" 성격으로 낮춰 읽게 만들어야 한다.
4. line reference를 유지할 거라면 릴리스 직전 자동 검증이 필요하다.