188 lines
7.1 KiB
Markdown
188 lines
7.1 KiB
Markdown
# 코드 리뷰 보고서 샘플
|
|
|
|
> 이 문서는 완료된 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>`
|
|
|
|
### 실행 환경
|
|
|
|
```text
|
|
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 초안
|
|
|
|
```markdown
|
|
### 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 초안
|
|
|
|
```text
|
|
[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>`
|