docs(docs): 문서 샘플과 리뷰 규칙을 갱신한다

docs/agent-guides/work-plan-docs.md

@@ -13,25 +13,57 @@
 - PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰한다.
 - 인터뷰로 확정한 내용을 PRD 문서에 보강한 뒤, 해당 PRD를 기준으로 구현 계획/TASK 문서를 작성한다.
 - 구현은 계획/TASK 문서를 기준으로 필요한 내용만 최소 범위로 진행한다.
+
+### 기준 샘플
+- 문서 샘플의 기준 위치는 `docs/sample/`이다.
+- PRD는 `docs/sample/sample-prd.md`를 참조해 작업에 필요한 항목만 사용한다.
+- 구현 계획/TASK 문서는 `docs/sample/sample-plan-task.md`를 참조해 작업에 필요한 구조와 실행 규칙을 구체화한다.
+- 리뷰 보고서는 `docs/sample/sample-review.md`를 참조한다.
+- 실제 문서를 만들 때 샘플의 `<...>` placeholder와 예시 ID·경로·명령·기대 결과를 해당 작업의 구체적인 값으로 교체한다.
+- 필요한 샘플이 없거나 경로가 불명확하면 다른 위치를 추정하거나 임의 형식을 만들지 말고 사용자에게 확인한다.
+
+### 문서 배치
 - 문서는 `docs/[날짜]_구현할내용한글/` 아래에 `prd.md`, `plan-task.md`로 만든다.
   - `docs/[날짜]_구현할내용한글/prd.md`
   - `docs/[날짜]_구현할내용한글/plan-task.md`
 - 문서 폴더명에서 원래 띄어쓰기가 들어갈 위치는 공백 대신 `_`를 사용한다.
   - 예: `docs/20260601_메인_홈_추천_UI와_API_연동/`
 - 기존에 생성된 `docs/prd/`, `docs/plan-task/` 문서는 유지하고, 신규 생성 문서부터 위 구조를 적용한다.
-- PRD 문서는 `sample-prd.md` 파일에서 작업에 필요한 부분만 발췌해 작성한다. `sample-prd.md`가 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다.
 - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
 - 연속된 하나의 작업이라면 별도 새 문서를 만들지 말고 기존 PRD와 계획/TASK 문서에 추가 작업으로 이어서 기록한다.
-- 계획/TASK 문서는 의미 단위 phase로 나누고 `### Phase 1: ...`, `### Phase 2: ...` 형식의 heading을 사용한다.
-- 각 phase 아래에는 단계별 task를 체크박스(`- [ ] **Task N.N: ...**`) 형태로 작성하고 완료 즉시 `- [x]`로 갱신한다.
-- 각 task에는 구현 시 생성/수정/확인할 파일 경로를 명시한다.
-- 각 phase 또는 task에는 실행 명령, 기대 결과, 수동 확인 항목 등 검증 기준을 함께 작성한다.
+
+### 계획/TASK 문서 작성과 유지
+- 계획/TASK 문서는 `docs/sample/sample-plan-task.md`의 상태·목표·범위·기술적 제약·Phase·Task·Gate·Progress·Decision Log 구조 중 작업에 필요한 항목을 사용한다.
+- 의미 단위 Phase는 `## Phase N`, 구현 항목의 Task는 `#### Task N.N` 형식으로 작성한다.
+- 각 Task 또는 Phase Gate에는 독립적으로 실행·판정할 수 있는 목표, 시작 조건, 완료 증거, 범위 밖 항목을 명시한다.
+- 각 Task에는 구현 시 생성·수정·확인할 파일 경로와 필요한 인터페이스를 명시한다.
+- 구현 Task의 실행 단계는 `RED → RED 확인 → GREEN → GREEN 확인 → REFACTOR` 순서의 체크박스로 작성하고 완료 즉시 `- [x]`로 갱신한다.
+- 테스트 작성이 현실적으로 불가능한 read-only 리뷰·문서·외부 확인 Task에는 `TDD 예외 사유`와 실행 명령·대조표·수동 확인을 포함한 `대체 검증 방법`을 명시한다.
+- 각 Phase 또는 Task에는 실행 명령, 기대 결과, 수동 확인 항목 등 검증 기준을 함께 작성한다.
 - 작업 도중 범위가 변경되면 계획 문서 체크리스트를 먼저 업데이트한 뒤 구현한다.
+- 실제 실행 결과는 샘플의 `Progress` 형식에 맞춰 무엇을/왜/어떻게 수행했는지와 남은 항목을 한국어로 누적한다.
 - 특정 phase 또는 task에 직접 대응되는 검증 기록(무엇/왜/어떻게, 실행 명령, 결과)은 해당 phase 또는 task 아래에 `검증 기록`으로 한국어로 남긴다.
 - 여러 phase에 걸치거나 문서 전체에 해당하는 통합 검증, 회귀 검증, 최종 수동 확인 기록은 문서 최하단 `Verification Log`에 한국어로 남긴다.
 - 후속 수정이 발생해도 기존 검증 기록은 삭제/덮어쓰기 없이 위치별로 누적한다.
 
+### 코드 리뷰 보고서와 후속 수정
+- 코드 리뷰, 코드 품질 점검, 완료 Phase 재검토를 수행하면 결과를 별도 리뷰 보고서로 작성한다.
+- 리뷰 보고서는 `docs/sample/sample-review.md`를 참조해 대상 PRD·`plan-task.md`와 같은 작업 디렉터리의 `reviews/[리뷰범위]-review.md`에 저장한다.
+- `[리뷰범위]`는 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>` 형식으로 작성한다.
+  - `phase`와 번호 사이에는 하이픈을 넣지 않는다.
+  - 구현 내용은 소문자 영문 단어를 하이픈으로 연결한다.
+  - 예: `docs/20260601_메인_홈_추천_UI와_API_연동/reviews/phase2-main-home-recommendation-review.md`
+- `reviews/`는 실제 리뷰 보고서가 생길 때 만들며, 리뷰가 없는 작업에는 빈 폴더를 만들지 않는다.
+- 확정 발견 사항이 없더라도 리뷰 범위, 검토 근거, 실행한 검증, “확정 발견 사항 없음” 판정을 보고서에 남긴다.
+- 일반 빌드, 테스트, 린트 실행은 리뷰 보고서 생성 대상이 아니며 해당 결과는 Task별 검증 기록 또는 `Verification Log`에 남긴다.
+- 리뷰에서 발견한 후보는 재현·근거 확인 후 `확정`, `오탐`, `보류`로 판정하고, 확정된 수정 항목만 계획/TASK 문서로 전환한다.
+- 수정 항목이 확정되면 코드를 변경하기 전에 `plan-task.md`의 해당 Phase에 review ID, 대상 파일, 수정 범위, 회귀 테스트, 완료 증거를 포함한 신규 회귀 수정 Task를 추가한다.
+- 계획/TASK 문서 갱신이 끝나면 신규 회귀 수정 Task의 체크리스트에 따라 바로 수정하며, 기존 완료 Task나 Phase의 체크박스를 미완료로 되돌리지 않는다.
+- 수정 후 실행한 검증과 판정은 리뷰 보고서와 계획/TASK 문서의 검증 기록에 삭제·덮어쓰기 없이 누적한다.
+
 ## 문서 유지보수 규칙
+- `docs/sample/` 샘플의 위치, 문서 구조, 작성·운용 규칙이 변경되면 같은 작업에서 `AGENTS.md`와 관련 `docs/agent-guides/` 문서를 함께 갱신한다.
+- 샘플과 안내 문서가 서로 다른 경로 또는 작성 규칙을 안내하지 않는지 문서 변경 후 검색해 확인한다.
 - `build.gradle`/`app/build.gradle`/`settings.gradle` 변경 시 실행 명령 섹션을 함께 갱신한다.
 - 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다.
 - `.editorconfig` 변경 시 `docs/agent-guides/code-style.md`의 포맷 규칙 섹션을 동기화한다.