code-review-protocol

name	code-review-protocol
description	코드 리뷰 프로토콜. 심각도 기반 리뷰 형식, 머지 판단 기준, 필수 점검 항목, 리뷰 로그 누적, 셀프 리뷰 체크리스트를 적용. 코드 리뷰 또는 PR 검토 시 사용.

Code Review Protocol (코드 리뷰 프로토콜)

AI 또는 인간 리뷰어가 코드 변경사항을 검증할 때 사용하는 표준 프로토콜. 기술 스택과 무관하게 모든 프로젝트에 적용한다.

---

1. 검토 우선순위

리뷰 시 아래 순서로 점검한다. 상위 항목일수록 치명적이다.

1. 동작 오류        → 런타임 에러, 크래시, 무한루프
2. 데이터 정합성    → 상태 불일치, 타입 미스매치, DB 정합성
3. UX 회귀         → 기존 사용자 플로우 깨짐, 접근성 저하
4. 구조 일관성      → 레이어 규칙 위반, 패턴 불일치, 순환 의존
5. 테스트 누락      → 새 기능에 테스트 미추가, 기존 테스트 미통과
6. 코드 스타일      → 네이밍, 포매팅, 주석 누락

---

2. 리뷰 기록 형식

모든 리뷰 이슈는 아래 형식으로 기록한다.

[심각도] 파일:라인 — 문제 — 영향 — 수정 제안

심각도 등급

등급	의미	예시
[FATAL]	서비스 불가, 데이터 손실	인증 우회, DB 쿼리 무한 루프, 미처리 예외로 크래시
[HIGH]	주요 기능 장애, 사용자 플로우 차단	API 응답 타입 불일치, 상태 꼬임, 결제 로직 오류
[NORMAL]	부분 기능 이상, 우회 가능	특정 조건에서 UI 깨짐, 비효율적 쿼리, 에러 메시지 미흡
[LOW]	코드 품질, 가독성, 컨벤션	네이밍 규칙 위반, 불필요 console.log, 주석 누락

기록 예시

[HIGH] lib/api/session.ts:42 — authFetch 에러 미처리 — 네트워크 오류 시 빈 화면 — try/catch + 에러 토스트 추가
[NORMAL] components/Dashboard.tsx:108 — 하드코딩 문자열 "Loading..." — i18n 미적용 — t('common.loading') 사용
[LOW] types/session.ts:3 — 파일 헤더 주석 누락 — 컨벤션 미준수 — /** 세션 타입 정의. */ 추가

---

3. 머지 판단 기준

판정	조건	후속 조치
머지 가능	FATAL/HIGH 이슈 없음	바로 머지
조건부 머지	NORMAL 이슈만 존재	후속 작업을 이슈/티켓으로 생성 후 머지
머지 불가	FATAL 또는 HIGH 존재	수정 후 재리뷰 필요

판정 기록 형식

### 판정: [머지 가능 / 조건부 / 머지 불가]

**근거:**
- FATAL: 0건
- HIGH: 0건
- NORMAL: 2건
- LOW: 3건

**조건 (조건부인 경우):**
- [ ] NORMAL #1 후속 이슈 생성
- [ ] NORMAL #2 다음 스프린트에 수정

---

4. 필수 점검 항목

A. 기능 검증

• 신규/변경 기능이 명세대로 동작하는가
• 기존 기능에 회귀(regression)가 없는가
• 에러 경로(네트워크 오류, 타임아웃, 잘못된 입력)가 정상 처리되는가
• 경계값(빈 배열, null, 최대값)이 처리되는가

B. 데이터 정합성

• BE↔FE 타입이 동기화되었는가
• 상태 변경이 일관성 있게 전파되는가
• DB 쿼리 결과가 올바르게 매핑되는가
• 동시성/경쟁 조건(race condition) 위험이 없는가

C. 구조 준수

• 레이어 의존 규칙 위반이 없는가 (types ← lib ← components ← app)
• barrel re-export가 갱신되었는가
• 파일 헤더 주석이 있는가
• CLAUDE.md가 필요한 폴더에 추가되었는가
• 순환 의존이 없는가

D. 보안

• 사용자 입력이 적절히 검증/이스케이프되는가
• 인증/인가 체크가 누락되지 않았는가
• 시크릿/API 키가 코드에 하드코딩되지 않았는가
• SQL 인젝션, XSS, CSRF 등 OWASP 위험이 없는가

E. 테스트 & 빌드

• 기존 테스트가 모두 통과하는가
• 새 기능에 대한 테스트가 추가되었는가
• 빌드가 성공하는가
• 타입 체크가 통과하는가 (TypeScript, mypy 등)

---

5. 리뷰 로그 관리

누적 기록 규칙

• 리뷰 완료 즉시 review-log.md에 누적 기록
• 동일 이슈 재발 시 "재발" 표기 + 원인 추적 메모 추가
• 날짜별로 구분하여 이력 추적 가능하게 유지

리뷰 로그 템플릿

## Review: YYYY-MM-DD — Sprint X.Y

### 대상
- 커밋: `abc1234`..`def5678`
- 변경 파일: N개

### 판정: [머지 가능 / 조건부 / 머지 불가]

### 이슈 목록
1. [FATAL] 파일:라인 — 문제 — 영향 — 수정 제안
2. [HIGH] 파일:라인 — 문제 — 영향 — 수정 제안
3. [NORMAL] 파일:라인 — 문제 — 영향 — 수정 제안

### 코멘트
- 전체 소감
- 구조적 제안
- 기술 부채 메모

### 재발 이슈 추적
| 이슈 | 최초 발견 | 재발 횟수 | 원인 추적 |
|------|-----------|-----------|-----------|
| 에러 미처리 | 02-11 | 2회 | authFetch 래퍼 미사용 |

---

6. 셀프 리뷰 체크리스트

구현자가 리뷰 요청 전 직접 확인할 항목.

• git diff 확인 — 변경 범위가 의도한 것과 일치하는가
• 불필요한 디버그 코드 제거 — console.log, print, debugger, // TODO: remove
• TODO/FIXME에 적절한 컨텍스트 기록 — 무엇을, 왜, 언제까지
• 커밋 전 체크리스트 통과 — build, test, encoding, mirror sync
• 변경 파일 수가 합리적인가 — 너무 많으면 분할 고려
• 관련 없는 변경이 섞여있지 않은가 — 한 PR = 한 관심사
• 새 의존성이 추가되었다면 이유가 명확한가
• 환경변수/설정 변경 시 문서(README, .env.example)가 갱신되었는가