Code Review
멀티 에이전트 기반 GitHub PR 자동 코드 리뷰 설정 및 커스터마이징
Code Review
멀티 에이전트 분석을 통해 전체 코드베이스를 대상으로 로직 오류, 보안 취약점, 리그레션을 잡아내는 자동 PR 리뷰를 설정합니다.
참고: Code Review는 리서치 프리뷰 단계이며, Teams 및 Enterprise 구독에서 사용 가능합니다. Zero Data Retention이 활성화된 조직에서는 사용할 수 없습니다.
Code Review는 GitHub Pull Request를 분석하고, 이슈가 발견된 코드 줄에 인라인 댓글로 결과를 게시합니다. 전문 에이전트 플릿이 전체 코드베이스의 컨텍스트에서 코드 변경 사항을 검사하여 로직 오류, 보안 취약점, 깨진 엣지 케이스, 미묘한 리그레션을 찾습니다.
결과는 심각도별로 태그되며 PR을 승인하거나 차단하지 않으므로, 기존 리뷰 워크플로는 그대로 유지됩니다. CLAUDE.md 또는 REVIEW.md 파일을 저장소에 추가하여 Claude가 플래그하는 내용을 조정할 수 있습니다.
자체 CI 인프라에서 Claude를 실행하려면, 이 관리형 서비스 대신 GitHub Actions 또는 GitLab CI/CD를 참고하세요.
이 페이지에서 다루는 내용:
리뷰 작동 방식
관리자가 조직에서 Code Review를 활성화하면, 저장소의 구성된 동작에 따라 PR이 열릴 때, 매 push마다, 또는 수동 요청 시 리뷰가 트리거됩니다. 어떤 모드에서든 @claude review를 댓글로 작성하면 해당 PR에서 리뷰가 시작됩니다.
리뷰가 실행되면, 여러 에이전트가 Anthropic 인프라에서 diff와 주변 코드를 병렬로 분석합니다. 각 에이전트는 다른 유형의 이슈를 찾고, 검증 단계에서 실제 코드 동작과 대조하여 오탐을 필터링합니다. 결과는 중복 제거되고, 심각도별로 순위가 매겨지며, 이슈가 발견된 특정 줄에 인라인 댓글로 게시됩니다. 이슈가 발견되지 않으면 Claude가 PR에 짧은 확인 댓글을 게시합니다.
리뷰는 PR 크기와 복잡도에 비례하여 비용이 증가하며, 평균 20분 내에 완료됩니다. 관리자는 분석 대시보드를 통해 리뷰 활동과 비용을 모니터링할 수 있습니다.
심각도 수준
각 결과에는 심각도 수준이 태그됩니다:
| 표시 | 심각도 | 의미 |
|---|---|---|
| 🔴 | Normal | 머지 전에 수정해야 하는 버그 |
| 🟡 | Nit | 사소한 이슈, 수정할 가치는 있지만 차단하지 않음 |
| 🟣 | Pre-existing | 코드베이스에 존재하지만 이 PR에서 도입되지 않은 버그 |
결과에는 접을 수 있는 확장 추론 섹션이 포함되어 있어, Claude가 이슈를 플래그한 이유와 문제를 어떻게 검증했는지 확인할 수 있습니다.
Code Review가 확인하는 것
기본적으로 Code Review는 정확성에 초점을 맞춥니다: 프로덕션을 중단시킬 버그를 찾으며, 포매팅 선호도나 누락된 테스트 커버리지는 대상이 아닙니다. 저장소에 가이드 파일을 추가하여 확인 대상을 확장할 수 있습니다.
Code Review 설정
관리자가 조직에 대해 한 번 Code Review를 활성화하고 포함할 저장소를 선택합니다.
1단계: Claude Code 관리자 설정 열기
claude.ai/admin-settings/claude-code로 이동하여 Code Review 섹션을 찾습니다. Claude 조직에 대한 관리자 접근 권한과 GitHub 조직에 GitHub App을 설치할 권한이 필요합니다.
2단계: 설정 시작
Setup을 클릭합니다. GitHub App 설치 흐름이 시작됩니다.
3단계: Claude GitHub App 설치
프롬프트에 따라 GitHub 조직에 Claude GitHub App을 설치합니다. 앱은 다음 저장소 권한을 요청합니다:
- Contents: 읽기 및 쓰기
- Issues: 읽기 및 쓰기
- Pull requests: 읽기 및 쓰기
Code Review는 contents에 대한 읽기 접근과 pull request에 대한 쓰기 접근을 사용합니다. 더 넓은 권한 세트는 나중에 활성화하는 경우 GitHub Actions도 지원합니다.
4단계: 저장소 선택
Code Review를 활성화할 저장소를 선택합니다. 저장소가 보이지 않으면 설치 중에 Claude GitHub App에 접근 권한을 부여했는지 확인하세요. 나중에 더 많은 저장소를 추가할 수 있습니다.
5단계: 저장소별 리뷰 트리거 설정
설정이 완료되면 Code Review 섹션에 저장소가 테이블로 표시됩니다. 각 저장소에 대해 Review Behavior 드롭다운을 사용하여 리뷰 실행 시점을 선택합니다:
- Once after PR creation: PR이 열리거나 리뷰 준비 완료로 표시될 때 한 번 실행
- After every push: PR 브랜치에 매 push마다 실행, PR이 발전하면서 새 이슈를 잡고 플래그된 이슈를 수정하면 스레드를 자동 해결
- Manual: 누군가 PR에
@claude review를 댓글로 작성할 때만 리뷰 시작; 이후 해당 PR에 대한 push는 자동으로 리뷰됨
매 push마다 리뷰하면 가장 많은 리뷰가 실행되고 비용이 가장 많이 듭니다. Manual 모드는 특정 PR만 리뷰에 옵트인하려는 트래픽이 많은 저장소나, PR이 준비될 때까지 리뷰를 시작하지 않으려는 경우에 유용합니다.
저장소 테이블에는 최근 활동을 기반으로 한 리뷰당 평균 비용도 표시됩니다. 행 작업 메뉴를 사용하여 저장소별로 Code Review를 켜거나 끄거나, 저장소를 완전히 제거할 수 있습니다.
설정을 확인하려면 테스트 PR을 여세요. 자동 트리거를 선택한 경우, 몇 분 내에 Claude Code Review라는 체크 런이 나타납니다. Manual을 선택한 경우, PR에 @claude review를 댓글로 작성하여 첫 번째 리뷰를 시작하세요. 체크 런이 나타나지 않으면, 관리자 설정에 저장소가 나열되어 있고 Claude GitHub App이 접근 권한을 가지고 있는지 확인하세요.
수동으로 리뷰 트리거
Pull Request에 @claude review를 댓글로 작성하면 리뷰가 시작되고 해당 PR이 이후 push 트리거 리뷰에 옵트인됩니다. 이것은 저장소의 구성된 트리거에 관계없이 작동합니다: Manual 모드에서 특정 PR을 리뷰에 옵트인하거나, 다른 모드에서 즉시 재리뷰를 받는 데 사용합니다. 어느 경우든, 이후 해당 PR에 대한 push는 리뷰를 트리거합니다.
댓글이 리뷰를 트리거하려면:
- diff 줄의 인라인 댓글이 아닌 최상위 PR 댓글로 게시
- 댓글 시작 부분에
@claude review를 배치 - 저장소에 대한 owner, member, 또는 collaborator 접근 권한이 있어야 함
- PR이 열려 있고 draft가 아니어야 함
해당 PR에서 리뷰가 이미 실행 중이면, 진행 중인 리뷰가 완료될 때까지 요청이 큐에 대기합니다. PR의 체크 런을 통해 진행 상황을 모니터링할 수 있습니다.
리뷰 커스터마이징
Code Review는 저장소에서 두 개의 파일을 읽어 플래그할 내용을 안내합니다. 둘 다 기본 정확성 검사에 추가적으로 적용됩니다:
CLAUDE.md: Claude Code가 리뷰뿐만 아니라 모든 작업에 사용하는 공유 프로젝트 지침. 대화형 Claude Code 세션에도 적용되는 가이드에 사용합니다.REVIEW.md: 코드 리뷰 중에만 읽히는 리뷰 전용 가이드. 리뷰 중에 무엇을 플래그하거나 건너뛸지에 대한 규칙으로, 일반CLAUDE.md를 어지럽힐 내용에 사용합니다.
CLAUDE.md
Code Review는 저장소의 CLAUDE.md 파일을 읽고 새로 도입된 위반 사항을 nit 수준의 결과로 처리합니다. 이것은 양방향으로 작동합니다: PR이 CLAUDE.md 문장을 구식으로 만드는 방식으로 코드를 변경하면, Claude가 문서도 업데이트해야 한다고 플래그합니다.
Claude는 디렉토리 계층의 모든 수준에서 CLAUDE.md 파일을 읽으므로, 하위 디렉토리의 CLAUDE.md 규칙은 해당 경로 아래의 파일에만 적용됩니다. CLAUDE.md의 작동 방식에 대한 자세한 내용은 메모리 문서를 참고하세요.
일반 Claude Code 세션에 적용하지 않으려는 리뷰 전용 가이드에는 REVIEW.md를 대신 사용하세요.
REVIEW.md
저장소 루트에 REVIEW.md 파일을 추가하여 리뷰 전용 규칙을 설정합니다. 다음을 인코딩하는 데 사용합니다:
- 회사 또는 팀 스타일 가이드라인: "중첩 조건문보다 조기 반환 선호"
- 린터가 다루지 않는 언어 또는 프레임워크별 규칙
- Claude가 항상 플래그해야 하는 것: "새 API 라우트에는 통합 테스트가 있어야 함"
- Claude가 건너뛰어야 하는 것:
/gen/아래의 생성된 코드에서 포매팅에 대한 코멘트 금지"
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는 저장소 루트에서 REVIEW.md를 자동으로 검색합니다. 구성이 필요 없습니다.
사용량 확인
claude.ai/analytics/code-review로 이동하여 조직 전체의 Code Review 활동을 확인합니다. 대시보드에 표시되는 내용:
| 섹션 | 표시 내용 |
|---|---|
| PRs reviewed | 선택한 기간 동안 리뷰된 Pull Request의 일별 수 |
| Cost weekly | Code Review에 대한 주간 지출 |
| Feedback | 개발자가 이슈를 해결하여 자동 해결된 리뷰 댓글 수 |
| Repository breakdown | 저장소별 리뷰된 PR 수와 해결된 댓글 수 |
관리자 설정의 저장소 테이블에는 각 저장소의 리뷰당 평균 비용도 표시됩니다.
가격
Code Review는 토큰 사용량에 따라 과금됩니다. 각 리뷰의 평균 비용은 $15-25이며, PR 크기, 코드베이스 복잡도, 검증이 필요한 이슈 수에 따라 달라집니다. Code Review 사용량은 추가 사용량을 통해 별도로 과금되며 플랜의 포함 사용량에 포함되지 않습니다.
선택한 리뷰 트리거가 총 비용에 영향을 미칩니다:
- Once after PR creation: PR당 한 번 실행
- After every push: 매 push마다 실행, push 횟수만큼 비용이 증가
- Manual: 누군가 PR에
@claude review를 댓글로 작성할 때까지 리뷰 없음
어떤 모드에서든 @claude review를 댓글로 작성하면 해당 PR이 push 트리거 리뷰에 옵트인되므로, 해당 댓글 이후 push마다 추가 비용이 발생합니다.
비용은 조직이 다른 Claude Code 기능에 AWS Bedrock 또는 Google Vertex AI를 사용하는지 여부에 관계없이 Anthropic 청구서에 나타납니다. Code Review에 대한 월간 지출 한도를 설정하려면 claude.ai/admin-settings/usage로 이동하여 Claude Code Review 서비스에 대한 한도를 구성하세요.
분석의 주간 비용 차트 또는 관리자 설정의 저장소별 평균 비용 열을 통해 지출을 모니터링하세요.
관련 리소스
Code Review는 Claude Code의 나머지 기능과 함께 작동하도록 설계되었습니다. PR을 열기 전에 로컬에서 리뷰를 실행하거나, 자체 호스팅 설정이 필요하거나, CLAUDE.md가 도구 전반에서 Claude의 동작을 어떻게 형성하는지 더 깊이 알아보려면 다음 페이지를 참고하세요:
- 플러그인: PR을 푸시하기 전에 로컬에서 온디맨드 리뷰를 실행하는
code-review플러그인을 포함하여 플러그인 마켓플레이스 탐색 - GitHub Actions: 코드 리뷰를 넘어선 커스텀 자동화를 위해 자체 GitHub Actions 워크플로에서 Claude 실행
- GitLab CI/CD: GitLab 파이프라인을 위한 자체 호스팅 Claude 통합
- 메모리: Claude Code 전반에서
CLAUDE.md파일이 작동하는 방식 - 분석: 코드 리뷰를 넘어선 Claude Code 사용량 추적