Claude Code 상세 사용법 08: Code Review 자동화와 REVIEW.md 운영법 | DAKER 커뮤니티
Claude Code 상세 사용법 08: Code Review 자동화와 REVIEW.md 운영법
Claude Code의 Code Review는 공식 문서 기준으로 research preview이며 Team/Enterprise 조직에서 쓰는 관리형 PR 리뷰 기능이다. 핵심은 "AI가 approve한다"가 아니다. 여러 agent가 diff와 주변 코드를 읽고, 로직 오류, 보안 취약점, edge case, 회귀 위험을 inline comment와 check run으로 남기게 하는 보조 리뷰 레이어다.
1. 트리거는 저장소별로 다르게 둔다
리뷰 동작은 보통 세 가지다. PR 생성 시 한 번, push마다, 수동이다. 제품 핵심 repo는 push마다가 유용하지만 비용과 noise가 늘어난다. 문서, 실험, 대형 draft PR은 manual이 낫다.
수동 호출은 PR의 top-level comment에서 시작한다.
@claude review이 명령은 PR을 이후 push 리뷰에 구독시킨다. 한 번만 보고 싶으면 다음처럼 쓴다.
@claude review once초안 PR, 자주 force push하는 PR, 비용을 아끼고 싶은 장기 PR에는 review once가 더 맞다.
2. CLAUDE.md와 REVIEW.md를 분리한다
CLAUDE.md는 Claude Code 전체가 읽는 프로젝트 규칙이다. "테스트 없이 public API 변경 금지", "DB migration은 rollback 계획 포함" 같은 공통 규칙을 둔다. REVIEW.md는 리뷰 전용 기준이다. Code Review pipeline의 모든 agent에 강하게 들어가므로, 여기에는 무엇을 Important로 볼지, nit를 얼마나 제한할지, 어떤 경로를 건너뛸지 쓴다.
예시는 짧게 시작한다.
# REVIEW.md
- 결제, 인증, 권한, 데이터 삭제 경로의 회귀 가능성은 Important로 보고한다.
- generated, lockfile, snapshot 변경은 보안 또는 빌드 위험이 없으면 skip한다.
- 스타일 nit는 최대 3개만 남기고 나머지는 summary에 묶는다.
- finding마다 어떤 코드 경로로 문제가 재현되는지 근거를 적는다.3. 리뷰 결과를 테스트 루프로 닫는다
Claude가 남긴 comment를 바로 반영하기 전에 세 가지를 본다. 첫째, 현재 diff에서 새로 생긴 문제인가. 둘째, 테스트나 타입체크로 검증 가능한가. 셋째, 사람이 보기에 제품 요구사항과 충돌하지 않는가. AI 코딩 리뷰도 결국 merge gate가 아니라 evidence generator다.
로컬에서 먼저 훑고 싶다면 Claude Code 세션 안에서 /code-review를 실행해 현재 diff를 점검한다. PR에 올릴 필요가 없는 작은 변경은 로컬 리뷰와 테스트 자동화만으로도 충분하다.
claude
/code-review4. 운영 실패 모드
리뷰가 안 뜨면 repository가 Code Review 설정에 포함됐는지, Claude GitHub App 접근 권한이 있는지, PR이 열려 있는지, top-level comment로 호출했는지 확인한다. inline comment가 기대보다 적으면 좋은 신호일 수도 있다. 공식 문서상 결과는 check run summary에도 모이므로, comment만 보지 말고 check run까지 확인한다.
Senior takeaway: 좋은 코드 리뷰 자동화는 "더 많은 comment"가 아니라 "merge 전에 고쳐야 할 결함을 적게 놓치는 시스템"이다. REVIEW.md를 팀의 품질 계약으로 관리하면 클로드 코드, agentic coding, LLM 개발 워크플로우가 실제 개발 생산성으로 연결된다.