Claude Code에 대한 코드 리뷰 설정

코드 리뷰는 GitHub 풀 요청을 분석하고 문제를 발견한 코드 라인에 인라인 댓글로 결과를 게시합니다. 특화된 에이전트 팀이 전체 코드베이스의 맥락에서 코드 변경 사항을 검토하여 논리 오류, 보안 취약점, 손상된 엣지 케이스 및 회귀를 찾습니다.

이 문서에서는 코드 리뷰를 활성화하고, 리뷰 트리거를 구성하고, 플래그 처리 대상을 사용자 정의하고, 일반적인 설정 문제를 해결하는 방법을 다룹니다.

참고: 코드 리뷰는 연구 미리보기 상태이며 Team 및 Enterprise 플랜에서 사용 가능합니다. 데이터 보존이 0으로 설정된 조직에서는 사용할 수 없습니다. 코드 리뷰 사용량은 추가 사용량을 통해 별도로 청구되며 플랜의 포함된 사용량에 포함되지 않습니다.

코드 리뷰 작동 방식

조직이 코드 리뷰를 활성화하면 풀 요청이 열릴 때, 모든 푸시 시 또는 누군가 수동으로 리뷰를 요청할 때만 자동으로 트리거될 수 있습니다. 리뷰가 실행되면 여러 에이전트가 diff와 주변 코드를 병렬로 분석합니다. 각 에이전트는 다른 클래스의 문제를 찾고, 검증 단계에서 결과를 실제 코드 동작과 비교하여 거짓 양성을 필터링합니다.

결과는 중복 제거되고 심각도별로 순위가 매겨지며 문제가 발견된 특정 라인에 인라인 댓글로 게시됩니다. 문제가 발견되지 않으면 Claude는 PR에 짧은 확인 댓글을 게시합니다. 리뷰는 PR을 승인하거나 차단하지 않으므로 기존 리뷰 워크플로우는 그대로 유지됩니다.

리뷰는 PR 크기 및 복잡도에 따라 비용이 증가하며 평균 20분 내에 완료됩니다.

심각도 수준

각 결과에는 심각도 수준이 태그됩니다:

마커	심각도	의미
🔴	일반	병합 전에 수정해야 하는 버그
🟡	사소한 문제	사소한 문제로 수정할 가치가 있지만 차단하지는 않음
🟣	기존 문제	코드베이스에 존재하지만 이 PR에서 도입되지 않은 버그

결과에는 확장 가능한 확장 추론 섹션이 포함되어 있어 Claude가 문제를 플래그한 이유와 문제를 검증한 방법을 확인할 수 있습니다.

코드 리뷰가 확인하는 항목

기본적으로 코드 리뷰는 정확성에 중점을 두고 있습니다. 즉, 프로덕션을 중단할 버그이지만 형식 기본 설정이나 누락된 테스트 커버리지는 아닙니다. 리포지토리에 지침 파일을 추가하여 확인 범위를 확장할 수 있습니다.

코드 리뷰 설정

Team 및 Enterprise 플랜의 소유자 및 주 소유자는 조직에 대해 한 번 코드 리뷰를 활성화하고 포함할 리포지토리를 선택할 수 있습니다. Claude 조직 내의 소유자 역할 외에도 GitHub 조직에 GitHub 앱을 설치할 수 있는 권한이 필요합니다.

조직 설정 > Claude Code로 이동하여 코드 리뷰 섹션을 찾습니다.
"구성"을 클릭하여 GitHub 앱 설치 흐름을 시작합니다.
프롬프트를 따라 Claude GitHub 앱을 GitHub 조직에 설치합니다. 앱은 콘텐츠, 문제 및 풀 요청에 대한 읽기 및 쓰기 권한을 요청합니다.
코드 리뷰를 활성화할 리포지토리를 선택합니다. 리포지토리가 보이지 않으면 설치 중에 Claude GitHub 앱에 액세스 권한을 부여했는지 확인합니다.
리뷰 동작 드롭다운을 사용하여 각 리포지토리에 대한 리뷰 트리거를 설정합니다(각 옵션에 대한 자세한 내용은 다음 섹션 참조).

설정을 확인하려면 테스트 PR을 엽니다. 자동 트리거를 선택한 경우 Claude Code Review라는 체크 실행이 몇 분 내에 나타나야 합니다. 수동을 선택한 경우 PR에 "@claude review"를 댓글로 달아 첫 번째 리뷰를 시작합니다.

리뷰 트리거 선택

설정 후 코드 리뷰 섹션에 테이블의 리포지토리가 표시됩니다. 각 리포지토리에 대해 리뷰 실행 시기를 선택합니다:

PR 생성 후 한 번: PR이 열리거나 검토 준비 완료로 표시될 때 리뷰가 한 번 실행됩니다.
모든 푸시 후: PR 브랜치에 대한 모든 푸시에서 리뷰가 실행되어 PR이 진화함에 따라 새로운 문제를 포착합니다. Claude는 이전에 플래그된 문제를 수정할 때 스레드를 자동으로 해결합니다. 이는 가장 많은 리뷰를 실행하고 비용이 가장 많이 듭니다.
수동: 누군가 PR에 "@claude review"를 댓글로 달 때만 리뷰가 시작됩니다. 높은 트래픽 리포지토리에서 검토할 PR을 선택하려는 경우에 유용합니다.

리포지토리 테이블에는 최근 활동을 기반으로 각 리포지토리의 평균 리뷰 비용도 표시됩니다.

수동으로 리뷰 트리거

풀 요청에 "@claude review"를 댓글로 달아 리뷰를 시작하고 해당 PR을 향후 푸시 트리거 리뷰에 옵트인합니다. 이는 리포지토리의 구성된 트리거와 관계없이 작동합니다.

댓글이 리뷰를 트리거하려면:

diff 라인의 인라인 댓글이 아닌 최상위 PR 댓글로 게시합니다.
댓글의 시작 부분에 "@claude review"를 입력합니다.
리포지토리에 대한 소유자, 멤버 또는 협력자 액세스 권한이 있어야 합니다.
PR은 열려 있어야 하고 초안이 아니어야 합니다.

리뷰가 이미 실행 중인 경우 요청은 진행 중인 리뷰가 완료될 때까지 대기열에 추가됩니다.

리뷰 사용자 정의

코드 리뷰는 리포지토리에서 두 개의 파일을 읽어 플래그 처리 대상을 안내합니다. 둘 다 기본 정확성 확인 위에 추가됩니다.

CLAUDE.md

코드 리뷰는 리포지토리의 CLAUDE.md 파일을 읽고 새로 도입된 위반 사항을 사소한 수준의 결과로 처리합니다. PR이 CLAUDE.md 문을 오래된 것으로 만드는 방식으로 코드를 변경하면 Claude는 문서도 업데이트해야 한다고 플래그합니다.

Claude는 디렉토리 계층 구조의 모든 수준에서 CLAUDE.md 파일을 읽으므로 하위 디렉토리의 CLAUDE.md의 규칙은 해당 경로 아래의 파일에만 적용됩니다.

REVIEW.md

리뷰 특정 규칙에 대해 리포지토리 루트에 REVIEW.md 파일을 추가합니다. 다음을 인코딩하는 데 사용합니다:

회사 또는 팀 스타일 가이드라인
린터에서 다루지 않는 언어 또는 프레임워크별 규칙
Claude가 항상 플래그해야 하는 항목(예: "모든 새 API 경로에는 통합 테스트가 있어야 함")
Claude가 건너뛰어야 할 항목(예: "생성된 코드에 대해 댓글을 달지 마세요")

Claude는 리포지토리 루트에서 REVIEW.md를 자동으로 검색합니다. 구성이 필요하지 않습니다.

가격 및 사용량

코드 리뷰는 토큰 사용량을 기반으로 청구됩니다. 각 리뷰의 평균 비용은 $15–25이며 PR 크기, 코드베이스 복잡도 및 검증이 필요한 문제 수에 따라 확장됩니다.

코드 리뷰 사용량은 추가 사용량을 통해 별도로 청구되며 플랜의 포함된 사용량에 포함되지 않습니다. 선택한 리뷰 트리거는 총 비용에 영향을 미칩니다:

PR 생성 후 한 번은 PR당 한 번 실행됩니다.
모든 푸시 후는 각 푸시에서 실행되어 푸시 수만큼 비용을 곱합니다.
수동은 누군가 "@claude review"를 댓글로 달 때까지 비용이 발생하지 않습니다. 해당 댓글 후 PR에 대한 추가 푸시는 자동으로 리뷰를 트리거합니다.

비용은 조직이 다른 Claude Code 기능에 AWS Bedrock 또는 Google Vertex AI를 사용하는지 여부와 관계없이 Anthropic 청구서에 표시됩니다.

월간 지출 한도를 설정하려면 조직 설정 > 사용량으로 이동하여 Claude Code Review 서비스의 한도를 구성합니다.

분석 대시보드의 주간 비용 차트 또는 관리 설정의 리포지토리별 평균 비용 열을 통해 지출을 모니터링합니다.

사용량 보기

코드 리뷰 분석 대시보드로 이동하여 조직 전체의 활동을 확인합니다. 대시보드에는 다음이 표시됩니다:

검토된 PR: 선택한 시간 범위 동안 검토된 풀 요청의 일일 수입니다.
주간 비용: 코드 리뷰에 대한 주간 지출입니다.
피드백: 누군가 문제를 해결했기 때문에 자동으로 해결된 리뷰 댓글의 수입니다.
리포지토리 분석: 검토된 PR 및 해결된 댓글의 리포지토리별 수입니다.

문제 해결

GitHub 앱 설치 후 리포지토리가 나타나지 않음

Claude GitHub 앱을 설치했지만 리포지토리가 관리 패널에 나타나지 않는 경우:

Claude GitHub 앱이 예상하는 리포지토리에 액세스할 수 있는지 확인합니다. GitHub 조직의 설정으로 이동하여 설치된 GitHub 앱에서 Claude GitHub 앱을 찾고 모든 리포지토리에 액세스할 수 있는지 또는 선택된 리포지토리에만 액세스할 수 있는지 확인합니다.
조직이 Enterprise Managed Users(EMU)를 사용하는 GitHub Enterprise Cloud를 사용하는 경우 Claude GitHub OAuth 앱이 엔터프라이즈 수준에서 승인되었는지 확인합니다. EMU 엔터프라이즈는 승인된 OAuth 앱을 제한할 수 있으며 Claude 앱을 명시적으로 허용해야 합니다.
GitHub 통합을 연결 해제했다가 다시 연결해 봅니다. 조직 설정 > Claude Code로 이동하여 리포지토리 구성을 제거하고 설정을 다시 실행합니다.
문제가 지속되면 지원 팀에 문의하여 조직 이름과 GitHub 조직 이름을 제공하면 조사할 수 있습니다.

새 PR에서 코드 리뷰가 시작되지 않음

PR을 연 후 체크 실행이 나타나지 않는 경우:

리포지토리가 관리 설정에 나열되고 활성화되어 있는지 확인합니다.
리뷰 트리거 설정을 확인합니다. 수동으로 설정된 경우 PR에 "@claude review"를 댓글로 달아야 리뷰가 시작됩니다.
PR이 초안이 아닌지 확인합니다. 코드 리뷰는 초안 PR에서 실행되지 않습니다.
Claude GitHub 앱이 GitHub 조직의 설정에서 리포지토리에 계속 액세스할 수 있는지 확인합니다.

IP 제한이 있는 GitHub Enterprise Cloud

GitHub Enterprise Cloud 조직이 IP 주소로 액세스를 제한하는 경우 Claude GitHub 앱이 리포지토리에 액세스하지 못할 수 있습니다. 이를 해결하려면 GitHub 엔터프라이즈 설정에서 설치된 GitHub 앱에 대한 IP 허용 목록 상속을 활성화합니다. Claude GitHub 앱이 IP 범위를 등록하므로 이 설정을 활성화하면 수동 구성 없이 액세스할 수 있습니다. 대신 범위를 허용 목록에 수동으로 추가하거나 다른 방화벽을 구성하려면 Anthropic API IP 주소를 참조하세요.

GitHub Enterprise Server(자체 호스팅)

코드 리뷰는 현재 github.com에서 호스팅되는 리포지토리가 필요하므로 자체 호스팅 GitHub Enterprise Server는 아직 지원되지 않습니다.

자주 묻는 질문

사용자 정의 역할을 만들 때 코드 리뷰를 기능으로 사용할 수 있습니까?

아니요, 코드 리뷰는 현재 사용자 정의 역할에 추가할 수 없습니다.