자동 코드 리뷰 (Code Review)

읽는 시간: 12분 | 난이도: 중급자

Claude Code가 GitHub PR을 자동으로 분석하고 인라인 코멘트로 문제를 알려주는 기능을 알아봅니다.

Teams / Enterprise 전용 기능

Code Review는 Anthropic이 관리하는 매니지드 서비스로, Claude Code Teams 또는 Enterprise 플랜에서만 사용할 수 있습니다. 현재 Research Preview(베타) 단계로 제공됩니다.

(출처: 공식 문서)

Code Review란?

Code Review는 GitHub Pull Request를 열거나 코드를 푸시할 때 Claude가 자동으로 코드를 분석하고, 문제를 인라인 코멘트로 남겨주는 기능입니다.

단순히 diff만 보는 것이 아니라 전체 코드베이스 맥락에서 변경사항을 분석합니다. 여러 전문화된 에이전트가 병렬로 동작하며 다음을 검토합니다:

로직 오류 및 버그
보안 취약점
엣지 케이스 누락
미묘한 회귀(regression) 가능성

리뷰 결과는 심각도(severity)별로 태그가 붙어 인라인 코멘트로 달립니다. Claude의 리뷰는 PR을 승인하거나 차단하지 않습니다. 참고용 피드백으로 활용하세요.

리뷰 동작 방식

관리자가 조직(Organization)에서 Code Review를 활성화하면, 다음 시점에 리뷰가 실행됩니다:

PR을 열 때 (자동)
코드를 푸시할 때마다 (자동)
수동으로 요청할 때

어떤 모드에서도 PR에 @claude review라고 코멘트를 남기면 즉시 리뷰를 시작합니다.

리뷰 처리 과정

병렬 분석: 여러 에이전트가 diff와 주변 코드를 동시에 분석
역할 분리: 각 에이전트는 서로 다른 유형의 문제를 담당
검증 단계: 실제 코드 동작과 대조하여 오탐(false positive) 필터링
중복 제거 및 우선순위 정렬: 심각도 순으로 정리
인라인 코멘트 게시: 해당 코드 라인에 직접 코멘트 첨부
문제 없을 시: Claude가 짧은 확인 코멘트를 남김

리뷰는 평균 20분 내에 완료되며, PR 크기와 코드베이스 복잡도에 따라 비용이 달라집니다.

심각도(Severity) 등급

각 리뷰 결과에는 심각도 레이블이 붙습니다:

레이블	의미
Normal	머지 전에 수정해야 할 버그
Nit	사소한 문제, 수정을 권장하지만 블로킹 아님
Pre-existing	이번 PR이 도입한 것이 아닌 기존 코드베이스의 버그

각 결과에는 접을 수 있는 상세 추론(extended reasoning) 섹션이 포함되어, Claude가 해당 문제를 판단한 근거를 확인할 수 있습니다.

Code Review의 검토 범위

기본적으로 Code Review는 정확성(correctness) 에 집중합니다.

프로덕션을 망가뜨릴 수 있는 버그
포맷팅이나 누락된 테스트는 기본 포함 대상이 아님

검토 범위는 CLAUDE.md 또는 REVIEW.md 파일로 확장하거나 제한할 수 있습니다.

설정 방법

1. 관리자 활성화

조직(Organization) 관리자가 한 번 Code Review를 활성화하면 됩니다:

Code Review 설정 화면으로 이동
포함할 저장소(repository) 선택
저장소 목록에서 리뷰당 평균 비용 확인 가능
행(row) 우측 메뉴에서 저장소별로 켜기/끄기 가능

2. 설정 확인

설정이 올바른지 확인하려면 테스트 PR을 열어보세요:

자동 트리거 모드: "Claude Code Review" 체크 런(check run)이 나타나야 합니다.
수동 모드: PR에 @claude review를 코멘트로 남기면 리뷰가 시작됩니다.

수동으로 리뷰 요청하기

PR에 아래처럼 코멘트를 남기면 언제든 리뷰를 요청할 수 있습니다:

@claude review

수동 요청 조건

인라인 코멘트가 아닌 최상위(top-level) PR 코멘트로 작성
코멘트 맨 앞에 @claude review가 위치해야 함
요청자는 저장소의 owner, member, 또는 collaborator 권한 필요
PR이 오픈 상태이고 draft가 아닌 경우에만 동작

수동으로 @claude review를 요청하면, 이후 해당 PR에 코드를 푸시할 때도 자동으로 리뷰가 실행됩니다.

이미 리뷰가 실행 중이라면, 새 요청은 큐(queue) 에 쌓입니다.

리뷰 커스터마이즈

CLAUDE.md

프로젝트 전반에 적용되는 지침 파일입니다. Code Review뿐만 아니라 모든 Claude Code 작업에 적용됩니다.

새로 도입된 위반 사항은 nit 수준 결과로 표시됩니다.
역방향으로도 작동합니다: PR이 CLAUDE.md를 구식으로 만드는 경우도 감지합니다.
디렉토리 계층 모든 수준에서 읽힙니다.

REVIEW.md

코드 리뷰 전용 지침 파일입니다. CLAUDE.md와 달리 코드 리뷰 시에만 읽힙니다.

저장소 루트에 REVIEW.md를 두면 Claude가 자동으로 인식합니다. 별도 설정은 필요 없습니다.

REVIEW.md 예시:

# Code Review Guidelines

## Always check
- New API endpoints have corresponding integration tests
- Database migrations are backward-compatible
- Error messages don't leak internal details to users

## Style
- Prefer match statements over chained isinstance checks
- Use structured logging, not f-string interpolation in log calls

## Skip
- Generated files under src/gen/
- Formatting-only changes in *.lock files

사용량 및 비용

대시보드 확인

claude.ai/analytics/code-review에서 다음을 확인할 수 있습니다:

리뷰된 PR 수
주간 비용
피드백 현황
저장소별 세부 내역

비용 구조

토큰 사용량 기반으로 청구
리뷰 1건당 평균 $15~$25 (PR 크기 및 코드베이스 복잡도에 따라 변동)
플랜의 기본 포함 사용량과 별도로 추가 사용량으로 청구

트리거 방식에 따른 비용 차이

트리거 방식	리뷰 실행 시점	비용 영향
PR 생성 후 1회	PR당 1회	낮음
푸시할 때마다	푸시 횟수 × 비용	푸시 횟수에 비례
수동	`@claude review` 요청 시에만	요청한 만큼만

비용에 민감하다면 수동 트리거 또는 PR 생성 후 1회 모드를 권장합니다.

ZDR(Zero Data Retention) 조직은 Code Review를 사용할 수 없습니다.

상황	권장 도구
셀프 호스팅 환경에서 CI에 통합	GitHub Actions 또는 GitLab CI/CD
푸시 전 로컬에서 리뷰	Marketplace의 `code-review` 플러그인
Managed Service (이 문서)	Teams/Enterprise Code Review

요약

항목	내용
대상 플랜	Teams / Enterprise
현재 상태	Research Preview (베타)
리뷰 평균 소요 시간	약 20분
리뷰 1건 평균 비용	$15~$25
수동 트리거	`@claude review` 코멘트
커스터마이즈 파일	`CLAUDE.md`, `REVIEW.md`
ZDR 조직	사용 불가

Code Review는 팀의 코드 품질을 높이는 강력한 도구입니다. REVIEW.md를 잘 활용하면 팀의 코딩 컨벤션과 검토 기준을 Claude에게 학습시켜 더욱 정확하고 유용한 리뷰를 받을 수 있습니다.