sodalive-android/docs/sample/sample-review.md

코드 리뷰 보고서 샘플

이 문서는 완료된 Phase를 다시 검토할 때 사용하는 템플릿이다. 리뷰에서 발견한 후보를 먼저 검증하고, 확정된 항목만 plan-task.md의 회귀 수정 Task와 goal로 전환한다. 기존 완료 체크박스와 검증 기록은 삭제하거나 되돌리지 않는다. 실제 리뷰 문서는 대상 PRD·plan-task.md와 같은 작업 디렉터리의 reviews/ 아래에 docs/[날짜]_구현할내용한글/reviews/[리뷰범위]-review.md 형식으로 저장한다.

1. 리뷰 정보

항목	내용
리뷰 대상	Phase <번호> / Task <번호 또는 범위>
기준 commit 또는 working tree	<commit SHA 또는 변경 상태>
리뷰 일자	YYYY-MM-DD
리뷰어	<이름 또는 agent>
기준 문서	<대상 prd.md, api-contract.md, plan-task.md 경로>
리뷰 상태	진행 중 / 판정 완료 / 수정 검증 완료

2. 리뷰 목적과 범위

목적

• <예: Phase 0~1 구현이 요구사항과 API Contract를 충족하는지 확인한다.>
• <예: 완료 체크박스와 실제 코드·test·검증 기록이 일치하는지 확인한다.>

포함 범위

• 코드: <검토할 경로>
• 테스트: <검토할 unit/integration/E2E 경로>
• 문서: <검토할 요구사항·계약·Task 범위>
• 수동 검증: <브라우저, viewport, keyboard, 접근성 등>

제외 범위

• <이번 리뷰에서 다루지 않는 Phase, 기능 또는 외부 계약>

3. 판정 기준

심각도

심각도	기준
Blocker	보안·데이터 손실 위험, 핵심 흐름 불능, 완료 판정을 무효화하는 문제
High	확정 요구사항·API Contract 위반 또는 주요 회귀
Medium	제한된 조건에서 발생하는 기능·접근성·복구 문제
Low	유지보수성, 문서 정합성 또는 비핵심 UX 문제

상태

상태	의미	후속 처리
후보	근거를 발견했지만 아직 재현·판정하지 않음	검증 후 상태 변경
확정	코드·test·문서 근거로 문제가 확인됨	plan-task.md 회귀 수정 Task 후보
오탐	요구사항이나 실행 결과상 문제가 아님	근거를 남기고 종료
보류	외부 계약·환경·제품 결정이 필요함	담당 주체와 재개 조건 기록
수정 완료	수정과 관련 검증이 완료됨	실행 명령과 결과 연결

4. 검토한 근거

문서와 코드

• 요구사항: <예: AUTH-001~013>
• API Contract: <예: §3 인증>
• 계획: <예: P1-T2, P1-T3, P1-GATE>
• 코드: <파일 경로와 line>
• 테스트: <테스트 파일과 test name>

실행 환경

OS: <값>
Node: <값>
npm: <값>
Browser/viewport: <값>
환경 변수: 민감정보를 제외한 이름과 사용 mode만 기록

실행한 검증

명령 또는 수동 검증	결과	핵심 증거
<실제 실행 명령>	성공 / 실패 / 불가	<exit code, test 수, 오류 또는 불가 사유>
<수동 검증 절차>	성공 / 실패 / 불가	<관찰 결과>

5. 발견 사항 요약

ID	심각도	상태	제목	소유 Task	후속 goal
REV-P1-001	<심각도>	후보	<한 문장 제목>	<예: P1-T3>	판정 전

발견 사항이 없으면 “확정 발견 사항 없음”이라고 명시하고, 검토 범위와 실행 증거는 그대로 남긴다.

6. 발견 사항 상세

REV-P1-001 — <한 문장 제목>

• 심각도: <Blocker | High | Medium | Low>
• 상태: <후보 | 확정 | 오탐 | 보류 | 수정 완료>
• 관련 요구사항: <요구사항 ID 또는 없음>
• 관련 계약: <api-contract.md section 또는 없음>
• 소유 Task: <기존 Goal ID 또는 신규 회귀 Task>

관찰 내용

<실제로 관찰한 동작을 추정 없이 작성한다.>

근거

• 코드: <파일 경로:line과 관련 동작>
• 테스트: <테스트 파일:test name 또는 누락 사실>
• 문서: <문서 경로와 요구사항/계약/계획 항목>

재현 또는 검증 절차

1. <사전 조건>
2. <실행 명령 또는 사용자 동작>
3. <실제 결과>
4. <요구되는 결과>

영향

<사용자, 데이터, 보안, 접근성, 회귀 범위를 구체적으로 작성한다.>

권장 조치

<최소 수정 방향과 추가해야 할 회귀 test를 작성한다. 구현 전 확정되지 않은 endpoint·DTO·오류 값은 추정하지 않는다.>

판정 기록

• YYYY-MM-DD — <확정/오탐/보류 판정과 근거>
• YYYY-MM-DD — <후속 정정이 있으면 기존 기록을 지우지 않고 추가>

7. 확정 항목의 plan·goal 전환

확정 발견 사항이 없으면 이 절에 “전환 항목 없음”을 기록한다. 확정 항목이 있으면 구현 전에 plan-task.md에 아래 내용을 반영한다.

신규 회귀 수정 Task 초안

### Task R<번호>.<번호> <수정할 결과>

**Goal 실행 `P<Phase>-R<번호>`:** <확정된 문제를 수정하고 회귀를 방지하는 한 문장 objective>

- **시작 조건:** <관련 review ID, 기존 Task/Gate, 필요한 계약>
- **완료 증거:** <실패 재현 test → 수정 후 focused test → Phase Gate → 검증 기록>
- **범위 밖:** <이번 수정에서 건드리지 않을 기능>

- [ ] `<재현 가능한 실패 test를 먼저 추가하고 의도한 assertion 실패를 확인한다.>`
- [ ] `<최소 수정으로 test를 통과시킨다.>`
- [ ] `<관련 focused test와 Phase Gate를 실행한다.>`
- [ ] `<plan-task.md 하단에 무엇을/왜/어떻게를 누적한다.>`

create_goal objective 초안

[P<Phase>-R<번호>]의 확정 review 항목 <REV-ID 목록>을 수정하고 회귀를 방지한다.
plan-task.md에 추가된 회귀 수정 Task만 수행한다.
실패 재현, 최소 수정, focused test, Phase Gate와 검증 기록이 모두 끝나기 전에는 complete로 표시하지 않는다.
관련 없는 리팩터링과 계약 추정은 범위 밖이다.

8. 리뷰 종료 판정

판정 항목	결과	근거
리뷰 범위 전체 확인	충족 / 미충족	<근거>
후보 항목 판정 완료	충족 / 미충족	<근거>
확정 항목 plan 반영	충족 / 해당 없음 / 미충족	<Task 또는 사유>
보류 항목의 담당·재개 조건 기록	충족 / 해당 없음 / 미충족	<근거>
검증 명령과 결과 기록	충족 / 미충족	<근거>

최종 결론: <확정 발견 사항 없음 | 수정 goal 필요 | 외부 조건 대기 | 수정 검증 완료>

남은 항목: <없음 또는 review ID와 다음 행동>

9. 수정 후 검증 기록

기존 기록을 삭제하거나 덮어쓰지 않고 차수별로 누적한다.

N차 수정 검증 — YYYY-MM-DD

• 무엇을: <수정한 review ID와 결과>
• 왜: <요구사항·계약 위반 또는 회귀 위험>
• 어떻게:
  • <실행 명령> — <성공/실패와 핵심 수치>
  • <수동 검증> — <성공/실패/불가 사유>
• 남은 항목: <없음, 보류 또는 후속 review ID>