54 lines
4.7 KiB
Markdown
54 lines
4.7 KiB
Markdown
# 코드 리뷰 및 QA 기록 규칙
|
|
|
|
## 1. 적용 시점
|
|
|
|
- 사용자가 코드 리뷰, QA, 완료된 Phase 검증 또는 요구사항 충족 감사를 요청하면 이 문서를 따른다.
|
|
- 리뷰 요청은 기본적으로 읽기·진단 범위다. 사용자가 수정을 함께 요청하지 않았다면 코드, test, 설정과 구현 계획을 변경하지 않는다.
|
|
- 리뷰 결과를 재현하고 판정하는 데 필요한 test·typecheck·lint·build·E2E 같은 비파괴 검증은 실행할 수 있다.
|
|
|
|
## 2. 기준 문서와 템플릿
|
|
|
|
- 리뷰 전에 대상 기능 디렉터리의 `prd.md`, 실제 API Contract 파일, `plan-task.md`와 관련 구현·test를 읽는다.
|
|
- 대상 `prd.md`와 `plan-task.md`가 있는 기능 문서 디렉터리 아래 `reviews/`를 만들고 모든 리뷰 문서를 그 안에 둔다.
|
|
- 리뷰 문서를 기능 문서 디렉터리 바로 아래나 단수형 `review/`에 두지 않는다. 여러 Phase·Task 리뷰가 생겨도 같은 `reviews/`에 누적한다.
|
|
- [코드 리뷰 보고서 샘플](../sample/sample-review.md)을 원본 템플릿으로 사용하고, section·필드·상태 의미를 임의로 축소하지 않는다.
|
|
- 새로 생성하는 리뷰 문서 파일명은 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>.md` 패턴을 사용한다. `phase`와 번호 사이에는 하이픈을 넣지 않는다. 예: `phase1-character-management.md`, `phase2-audio-content.md`.
|
|
- 이 파일명 규칙은 새 리뷰 문서에만 적용한다. 이미 생성된 리뷰 문서는 이름과 기존 참조 링크를 변경하지 않는다.
|
|
- `prd.md`나 `plan-task.md`에서 리뷰 문서를 참조할 때는 `./reviews/<리뷰 파일명>.md` 상대 링크를 사용한다.
|
|
|
|
## 3. 리뷰 수행 원칙
|
|
|
|
- 요구사항과 계약 위반, 버그, 보안·데이터 위험, 회귀, test 누락을 우선 찾는다. 요약이나 칭찬보다 발견 사항을 먼저 보고한다.
|
|
- 모든 발견 후보에는 고유 ID, 심각도, 상태, 관련 요구사항·계약, 소유 Task, 코드/test/문서 근거와 재현 또는 검증 절차를 기록한다.
|
|
- 심각도는 `Blocker`, `High`, `Medium`, `Low`만 사용한다.
|
|
- 상태는 `후보`, `확정`, `오탐`, `보류`, `수정 완료`만 사용한다.
|
|
- 실행하지 않은 명령을 실행한 것처럼 기록하지 않는다. 실제 명령, exit code, test 수, 실패 내용 또는 실행 불가 사유를 남긴다.
|
|
- endpoint, DTO, 오류 status/message key, validation 상한처럼 제공되지 않은 계약을 추정하지 않는다. 외부 계약이 필요한 항목은 `보류`로 판정하고 담당 주체와 재개 조건을 기록한다.
|
|
- 발견 사항이 없더라도 “확정 발견 사항 없음”을 명시하고 검토 범위와 실행 증거를 남긴다.
|
|
|
|
## 4. 판정과 후속 처리
|
|
|
|
- 발견 후보는 재현 또는 문서·코드 근거 확인 후 `확정`, `오탐`, `보류` 중 하나로 판정한다.
|
|
- `오탐`과 `보류` 기록도 삭제하지 않는다. 후속 정정은 기존 내용을 덮어쓰지 않고 판정 기록에 날짜와 사유를 추가한다.
|
|
- 확정 발견 사항만 구현 전에 `plan-task.md`의 신규 회귀 수정 Task로 옮긴다. 기존 완료 체크박스와 검증 기록은 되돌리거나 삭제하지 않는다.
|
|
- 신규 회귀 수정 Task에는 review ID, goal ID, 시작 조건, 완료 증거, 범위 밖, 실패 재현 test, 관련 Phase Gate와 검증 기록 항목을 포함한다.
|
|
- 확정 항목의 수정은 review 작업과 분리된 goal로 수행한다. focused test와 관련 Phase Gate, `plan-task.md` 검증 기록이 끝나기 전에는 goal을 완료 처리하지 않는다.
|
|
- 수정 후 review 문서의 상태를 `수정 완료`로 바꾸고 실제 검증 명령과 결과를 “수정 후 검증 기록”에 누적한다.
|
|
|
|
## 5. 리뷰 종료 조건
|
|
|
|
다음을 모두 만족해야 리뷰를 종료한다.
|
|
|
|
- 검토 범위와 제외 범위가 문서에 명시돼 있다.
|
|
- 모든 후보가 `확정`, `오탐`, `보류`, `수정 완료` 중 하나로 판정돼 있다.
|
|
- 확정 항목은 `plan-task.md` 회귀 수정 Task로 전환됐거나, 사용자가 수정하지 않기로 한 결정이 기록돼 있다.
|
|
- 보류 항목에는 담당 주체와 재개 조건이 있다.
|
|
- 실행한 자동·수동 검증과 결과 또는 불가 사유가 기록돼 있다.
|
|
- 최종 결론과 남은 항목이 명시돼 있다.
|
|
|
|
## 6. 사용자 결과 보고
|
|
|
|
- 발견 사항이 있으면 심각도 순으로 review ID, 핵심 근거, 영향과 후속 조치를 먼저 전달한다.
|
|
- 발견 사항이 없으면 검토 범위, 실행한 검증과 남은 위험 또는 검증하지 못한 범위를 함께 전달한다.
|
|
- 확정 문제를 아직 수정하지 않았다면 완료·해결됐다고 표현하지 않는다.
|