템플릿 — 리뷰 체크리스트

언제 쓰나

4단계 — 검증에서 에이전트 산출물을 사람 또는 교차 리뷰 에이전트가 검토할 때 쓴다. 코드 리뷰를 "잘 짰는지" 위주로만 보면 에이전트 특유의 실수 — 의도와 어긋난 구현, 실제로는 아무것도 검증하지 않는 테스트, 불필요하게 방어적인 코드 — 를 놓치기 쉽다. 이 체크리스트는 그런 실수를 항목으로 못 박아 리뷰어가 매번 같은 것을 놓치지 않게 한다.

사용법

리뷰할 PR/커밋 단위로 아래 체크리스트를 복사해 리뷰 코멘트나 리뷰 기록 문서에 붙여 넣는다. 체크할 수 없는 항목(근거가 불충분한 항목)은 통과시키지 말고 이유를 옆에 적어 남긴다. 리뷰 중 반복적으로 걸리는 항목이 있으면, 그 항목을 프로젝트 CLAUDE.md나 린트 규칙으로 옮겨 다음 사이클부터 자동으로 걸리게 한다 — 체크리스트에만 남기고 컨텍스트 자산으로 옮기지 않으면 같은 실수가 반복된다.

템플릿

# 리뷰 체크리스트: [PR/커밋 식별자]

- 리스크 등급: <!-- 작성 안내: 리스크 매트릭스 기준 등급을 적는다. 예: High -->
- 리뷰어: <!-- 작성 안내: 구현한 에이전트/세션과 다른 사람 또는 에이전트인지 명시 -->

## 의도 정합성

<!-- 작성 안내: 산출물이 의도 문서에 쓴 목표와 실제로 일치하는지 확인한다. -->

- [ ] 구현이 의도 문서의 목표(성공 기준)를 실제로 만족한다 (예: "온보딩 5단계 축소"가 실제 단계 수로 확인됨)
- [ ] 의도 문서에 없는 범위가 임의로 추가되지 않았다 (예: 요청하지 않은 UI 요소, 스코프 밖 리팩터링)
- [ ] 의도 문서의 비목표(버린 것)가 실수로 다시 구현되지 않았다

## 보안 기본

<!-- 작성 안내: 리스크 등급이 Medium 이상이면 반드시 확인한다. -->

- [ ] 사용자 입력이 검증·이스케이프 없이 그대로 쿼리/명령/템플릿에 들어가지 않는다
- [ ] 인증/인가 체크가 우회 경로 없이 모든 진입점에 걸려 있다 (예: API 라우트 추가 시 미들웨어 누락 여부)
- [ ] 비밀값(API 키, 토큰)이 코드나 로그에 하드코딩되지 않았다

## 테스트 실재성

<!-- 작성 안내: 테스트가 통과한다는 사실이 아니라, 통과하는 이유를 확인한다. -->

- [ ] 테스트를 실패하게 만들어 봤을 때(로직을 일부러 깨뜨려서) 실제로 실패한다 — 항상 통과하는 가짜 테스트가 아니다
- [ ] 경계값과 실패 케이스(빈 입력, 최대값, 네트워크 오류 등)가 테스트에 포함돼 있다
- [ ] 테스트가 구현 세부사항이 아니라 의도한 동작을 검증한다 (예: "함수가 호출됐는가"가 아니라 "결과값이 맞는가")

## 컨텍스트 반영 여부

<!-- 작성 안내: 산출물이 프로젝트의 기존 규칙·컨벤션·용어를 따르는지 확인한다. -->

- [ ] 코딩 컨벤션(네이밍, 폴더 구조)이 `CLAUDE.md`/기존 코드베이스와 일치한다
- [ ] 이미 있는 유틸/헬퍼를 재사용하지 않고 비슷한 기능을 새로 만들지 않았다
- [ ] 도메인 용어집에 고정된 용어를 다른 의미로 쓰지 않았다

## 슬롭 신호

<!-- 작성 안내: 데모에서는 문제없어 보이지만 유지보수 단계에서 부채가 되는 패턴을 찾는다. -->

- [ ] 중복 코드가 없다 (같은 로직이 여러 곳에 복붙되지 않았다)
- [ ] 죽은 코드가 없다 (쓰이지 않는 함수, 도달 불가능한 분기, 주석 처리된 코드 블록)
- [ ] 과도한 방어 코드가 없다 (발생할 수 없는 케이스까지 try-catch/null 체크로 감싸 로직을 읽기 어렵게 만들지 않았다)

## 종합 판정

- [ ] 위 항목을 근거로 이 산출물을 신뢰하고 다음 단계(배포)로 넘길 수 있다
- 통과하지 못한 항목과 후속 조치: <!-- 작성 안내: 코드 수정으로 끝낼지, 의도 문서/컨텍스트 자산까지 고칠지 명시 -->