Claude Code를 위한 코드 리뷰 설정

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

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

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

코드 리뷰 작동 방식

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

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

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

심각도 수준

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

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

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

코드 리뷰가 확인하는 항목

기본적으로 코드 리뷰는 정확성에 중점을 두고 있습니다: 프로덕션을 중단할 버그이지 형식 선호도나 누락된 테스트 범위가 아닙니다. 저장소에 지침 파일을 추가하여 확인하는 항목을 확장할 수 있습니다.

코드 리뷰 설정

아래 단계는 github.com의 저장소에 대한 설정을 다룹니다. 저장소가 자체 호스팅 GitHub Enterprise Server(GHES) 인스턴스에 있는 경우 전체 설정 가이드는 GitHub Enterprise Server를 사용한 Claude Code를 참조하세요.

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은 열려 있어야 하며 초안이 아니어야 합니다.

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

리뷰 사용자 정의

Code Review는 저장소에서 두 개의 파일을 읽어 플래그를 지정할 항목을 결정합니다. 둘 다 기본 정확성 검사에 추가됩니다.

CLAUDE.md

Code Review는 저장소의 CLAUDE.md 파일을 읽고 새로 도입된 위반 사항을 지적 수준의 발견으로 처리합니다. PR이 CLAUDE.md 문을 구식으로 만드는 방식으로 코드를 변경하면 Claude는 문서도 업데이트해야 함을 플래그합니다.

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

REVIEW.md

저장소 루트에 REVIEW.md 파일을 추가하여 검토 관련 규칙을 지정합니다. 다음을 인코딩하는 데 사용합니다:

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

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

가격 및 사용량

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

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

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

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

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

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

사용량 보기

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

검토된 PR: 선택한 시간 범위 동안 검토된 풀 요청의 일일 수입니다.
주간 비용: Code Review에 대한 주간 지출입니다.
피드백: 누군가 문제를 해결하여 자동으로 해결된 검토 댓글의 수입니다.
저장소 분석: 저장소별 검토된 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 조직 이름을 제공하면 조사할 수 있습니다.

Code Review가 새 PR에서 시작되지 않음

PR을 열 때 검사 실행이 나타나지 않으면:

저장소가 관리 설정에 나열되고 활성화되어 있는지 확인합니다.
검토 트리거 설정을 확인합니다. 수동으로 설정된 경우 PR에서 "@claude review"를 댓글로 달아야 검토가 시작됩니다.
PR이 초안이 아닌지 확인합니다. Code Review는 초안 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 Enterprise Server(GHES)는 별도의 설정 흐름을 통해 지원됩니다. 전체 지침은 GitHub Enterprise Server를 사용한 Claude Code를 참조하세요.

일반적인 GHES 설정 문제:

"Public cannot be private" 오류 설정 중: GHES 호스트 이름은 공개적으로 라우팅 가능한 IP 주소로 확인되어야 합니다. Code Review는 인터넷을 통해 서버에 도달하므로 내부 또는 개인 네트워크 주소는 작동하지 않습니다. 호스트 이름이 공개 IP로 확인되도록 DNS 또는 네트워크 구성을 업데이트한 후 다시 시도합니다.
데이터 상주가 있는 GitHub Enterprise Cloud는 다른 제품입니다. 데이터 상주 테넌트(호스트 이름이 *.ghe.com과 일치)는 Code Review에서 지원되지 않습니다. 자체 호스팅 GitHub Enterprise Server 및 표준 github.com 저장소만 지원됩니다.

자주 묻는 질문

사용자 정의 역할을 만들 때 Code Review를 사용할 수 있습니까?

아니요, Code Review는 현재 사용자 정의 역할에 추가할 수 없습니다.