voiceon-character-admin/docs/agent-guide/review.md

코드 리뷰 및 QA 기록 규칙

1. 적용 시점

• 사용자가 코드 리뷰, QA, 완료된 Phase 검증 또는 요구사항 충족 감사를 요청하면 이 문서를 따른다.
• 리뷰 요청은 기본적으로 읽기·진단 범위다. 사용자가 수정을 함께 요청하지 않았다면 코드, test, 설정과 구현 계획을 변경하지 않는다.
• 리뷰 결과를 재현하고 판정하는 데 필요한 test·typecheck·lint·build·E2E 같은 비파괴 검증은 실행할 수 있다.

2. 기준 문서와 템플릿

• 리뷰 전에 대상 기능 디렉터리의 prd.md, api-contract.md, plan-task.md와 관련 구현·test를 읽는다.
• 리뷰 문서는 대상 prd.md와 같은 디렉터리에 만든다.
• 코드 리뷰 보고서 샘플을 원본 템플릿으로 사용하고, section·필드·상태 의미를 임의로 축소하지 않는다.
• 실제 리뷰 문서 파일명은 범위가 드러나게 작성한다. 예: review-phase-0-1.md, review-auth.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, 핵심 근거, 영향과 후속 조치를 먼저 전달한다.
• 발견 사항이 없으면 검토 범위, 실행한 검증과 남은 위험 또는 검증하지 못한 범위를 함께 전달한다.
• 확정 문제를 아직 수정하지 않았다면 완료·해결됐다고 표현하지 않는다.