코드 리뷰

코드 리뷰 (Code Review)

GitHub 풀 리퀘스트를 분석해 로직 오류, 보안 취약점, 회귀를 찾아내는 자동화된 PR 리뷰 서비스예요. 문제를 발견한 코드 줄에 인라인 댓글로 결과를 게시하며, 전문화된 에이전트 그룹이 전체 코드베이스 컨텍스트에서 코드 변경을 살펴봅니다.

출처: 공식문서

본문

Code Review는 research preview로, [Team·Enterprise](https://claude.ai/admin-settings/claude-code) 구독에서 사용할 수 있습니다. [Zero Data Retention](/docs/en/zero-data-retention)을 활성화한 조직에서는 사용할 수 없습니다. 다른 플랜에서는 `/code-review` 명령으로 [로컬에서 diff를 리뷰](#review-a-diff-locally)할 수 있습니다.

Code Review는 GitHub 풀 리퀘스트를 분석하고 문제를 찾은 코드 줄에 인라인 댓글로 결과를 게시합니다. 전문화된 에이전트 그룹이 전체 코드베이스 컨텍스트에서 코드 변경을 검토하며 로직 오류, 보안 취약점, 깨진 엣지 케이스, 미묘한 회귀를 찾습니다.

결과는 심각도로 태그되며 PR을 승인하거나 차단하지 않으므로 기존 리뷰 워크플로우가 그대로 유지됩니다. 리포지토리에 CLAUDE.md 또는 REVIEW.md 파일을 추가하면 Claude가 무엇을 지적할지 조정할 수 있습니다.

이 관리형 서비스 대신 자체 CI 인프라에서 Claude를 실행하려면 GitHub Actions나 GitLab CI/CD를 참고하세요. 셀프 호스트 GitHub 인스턴스의 리포지토리는 GitHub Enterprise Server를 참고하세요.

이 페이지에서 다루는 내용:

리뷰가 작동하는 방식 (How reviews work)

Owner가 조직의 Code Review를 활성화하면 리뷰는 리포지토리 구성 동작에 따라 PR이 열릴 때, 매 푸시 때, 또는 수동으로 요청받을 때 트리거됩니다. 어떤 모드에서든 @claude review 댓글을 달면 PR에 리뷰가 시작됩니다.

리뷰가 실행되면 여러 에이전트가 Anthropic 인프라에서 diff와 주변 코드를 병렬로 분석합니다. 각 에이전트는 다른 종류의 문제를 찾고, 검증 단계가 후보를 실제 코드 동작과 대조해 오탐(false positive)을 걸러냅니다. 결과는 중복 제거되고 심각도로 정렬된 뒤 문제가 발견된 특정 줄에 인라인 댓글로 게시되며, 리뷰 본문에 요약이 담깁니다. 문제가 없다면 Code Review는 GitHub check run을 업데이트해 문제가 없음을 표시합니다. Claude가 PR에 짧은 확인 댓글을 게시할 수도 있습니다.

리뷰 비용은 PR 크기와 복잡도에 따라 늘며, 평균 20분 안에 완료됩니다. Owner는 애널리틱스 대시보드로 리뷰 활동과 지출을 모니터링할 수 있습니다.

심각도 수준 (Severity levels)

각 결과는 심각도 수준으로 태그됩니다.

마커 심각도 의미
🔴 Important 머지 전에 고쳐야 하는 버그
🟡 Nit 사소한 문제, 고칠 가치가 있지만 차단하지 않음
🟣 Pre-existing 코드베이스에 이미 있지만 이 PR이 도입하지 않은 버그

결과에는 펼칠 수 있는 확장 추론 섹션이 포함되어, Claude가 왜 문제를 지적하고 어떻게 검증했는지 이해할 수 있습니다.

결과 평가·답변 (Rate and reply to findings)

Claude의 각 리뷰 댓글에는 👍와 👎가 이미 붙어 있어 GitHub UI에서 한 번 클릭으로 평가할 수 있습니다. 결과가 유용하면 👍를, 틀리거나 노이즈면 👎를 클릭하세요. Anthropic은 PR이 머지된 뒤 반응 수를 수집해 리뷰어를 튜닝합니다. 반응은 재리뷰를 트리거하거나 PR을 바꾸지 않습니다.

인라인 댓글에 답해도 Claude가 응답하거나 PR을 바꾸지 않습니다. 결과에 대응하려면 코드를 고치고 푸시하세요. PR이 푸시 트리거 리뷰를 구독 중이라면 문제가 고쳐지면 다음 실행이 스레드를 해결합니다. 푸시 없이 새 리뷰를 요청하려면 PR 최상위 댓글로 @claude review를 달아주세요.

Check run 출력 (Check run output)

인라인 리뷰 댓글 외에도 각 리뷰는 CI 체크 옆에 나타나는 Claude Code Review check run을 채웁니다. Details 링크를 펼치면 심각도로 정렬된 모든 결과의 요약을 한곳에서 볼 수 있습니다.

심각도 파일:라인 문제
🔴 Important src/auth/session.ts:142 토큰 갱신이 로그아웃과 경쟁해 오래된 세션을 활성 상태로 남김
🟡 Nit src/auth/session.ts:88 parseExpiry가 잘못된 입력에 조용히 0 반환

각 결과는 Files changed 탭에서 관련 diff 줄에 직접 표시되는 주석(annotation)으로도 나타납니다. Important는 빨간 마커, nit는 노란 경고, 기존 버그는 회색 안내로 렌더링됩니다. 주석과 심각도 표는 인라인 리뷰 댓글과 무관하게 check run에 기록되므로, GitHub가 이동한 줄의 인라인 댓글을 거부해도 계속 사용할 수 있습니다.

check run은 항상 중립(neutral) 결론으로 완료되므로 브랜치 보호 규칙을 통한 머지 차단을 일으키지 않습니다. Code Review 결과로 머지를 게이트하려면 자체 CI에서 check run 출력의 심각도 내역을 읽으세요. Details 텍스트의 마지막 줄은 워크플로우가 gh와 jq로 파싱할 수 있는 기계 판독 가능한 주석입니다. check run ID를 찾으려면 gh api repos/OWNER/REPO/commits/<commit-sha>/check-runs --jq '.check_runs[] | {id, name}'로 커밋의 check run을 나열하고 Claude Code Review 실행의 id를 가져오세요. OWNER, REPO, CHECK_RUN_ID를 리포지토리 소유자, 이름, 그 ID로 바꾸세요.

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

그러면 심각도별 개수 JSON이 반환됩니다. 예: {"normal": 2, "nit": 1, "pre_existing": 0}. normal 키가 Important 결과 수를 담고 있으며, 0이 아니면 Claude가 머지 전에 고칠 가치가 있는 버그를 적어도 하나 찾았다는 뜻입니다.

Code Review가 확인하는 것 (What Code Review checks)

기본적으로 Code Review는 정확성에 집중합니다. 프로덕션을 깨뜨릴 버그이지, 포맷팅 선호나 누락된 테스트 커버리지가 아닙니다. 안내 파일 추가로 확인 범위를 넓힐 수 있습니다.

Code Review 설정 (Set up Code Review)

Owner가 조직에 대해 Code Review를 한 번 활성화하고 포함할 리포지토리를 선택합니다.

Step 1: Claude Code 관리자 설정 열기 — claude.ai/admin-settings/claude-code로 가서 Code Review 섹션을 찾으세요. Claude 조직에서 Owner 또는 Primary Owner 역할과 GitHub 조직에 GitHub Apps를 설치할 권한이 필요합니다.

Step 2: 설정 시작 — Setup을 클릭하세요. GitHub App 설치 흐름이 시작됩니다.

Step 3: Claude GitHub App 설치 — 프롬프트를 따라 Claude GitHub App을 설치하세요. 리뷰할 리포지토리를 소유한 GitHub 조직을 고르고, 앱이 접근할 리포지토리를 선택하며, 요청된 권한을 승인하세요. 풀 리퀘스트를 리뷰하기 위해 Claude는 앱의 읽기 접근으로 리포지토리 내용을 읽고, 풀 리퀘스트·체크에 대한 쓰기 접근으로 댓글과 check run을 게시합니다. 설치 중에 GitHub Actions 같은 다른 Claude 기능이 공유하는 더 넓은 권한 집합도 부여합니다. 전체 목록은 GitHub App 권한을 참고하세요.

Step 4: 리포지토리 선택 — Code Review를 활성화할 리포지토리를 고르세요. 리포지토리가 안 보이면 설치 중에 Claude GitHub App에 그 리포지토리 접근을 줬는지 확인하세요. 나중에 리포지토리를 더 추가할 수 있습니다.

Step 5: 리포지토리별 리뷰 트리거 설정 — 설정이 끝나면 Code Review 섹션이 리포지토리를 표로 보여줍니다. 각 리포지토리에 대해 Review Behavior 드롭다운으로 리뷰가 언제 실행될지 고르세요.

  • Once after PR creation: PR이 열리거나 리뷰 준비 완료로 표시될 때 리뷰 한 번
  • After every push: PR 브랜치에 푸시할 때마다 리뷰. PR이 진화하면서 새 문제를 잡고, 지적된 문제를 고치면 스레드를 자동 해결.
  • Manual: PR을 열거나 푸시해도 리뷰가 시작되지 않음. @claude review 댓글로 요청하거나, @claude review always로 이후 푸시에도 리뷰를 구독.

어느 옵션을 골라도 Claude는 포크의 풀 리퀘스트를 누군가 @claude review 댓글을 달 때만 리뷰합니다.

매 푸시 리뷰는 가장 많은 리뷰를 실행해 비용도 가장 높습니다. Manual 모드는 트래픽이 많은 리포지토리에서 특정 PR만 리뷰에 옵트인하거나, 준비가 됐을 때만 리뷰를 시작하고 싶을 때 유용합니다.

리포지토리 표는 최근 활동을 기준으로 리포지토리당 평균 리뷰 비용도 보여줍니다. 행 작업 메뉴로 리포지토리별 Code Review를 켜거나 끄거나, 리포지토리를 완전히 제거할 수 있습니다.

설정을 검증하려면 테스트 PR을 여세요. 자동 트리거를 골랐다면 몇 분 안에 Claude Code Review라는 check run이 나타납니다. Manual을 골랐다면 PR에 @claude review 댓글을 달아 첫 리뷰를 시작하세요. check run이 안 나타나면 리포지토리가 관리자 설정에 나열됐는지, Claude GitHub App이 접근하는지 확인하세요.

수동 리뷰 트리거 (Manually trigger reviews)

댓글 명령이 필요할 때 리뷰를 시작합니다. 리포지토리 구성 트리거와 무관하게 동작하므로, Manual 모드에서 특정 PR을 리뷰에 옵트인하거나 다른 모드에서 즉시 재리뷰를 받을 때 쓸 수 있습니다.

명령 하는 일
@claude review PR을 이후 푸시에 구독하지 않고 단일 리뷰 시작
@claude review always 리뷰를 시작하고 앞으로 푸시 트리거 리뷰에 PR 구독
@claude review once @claude review와 동일: 구독 없이 단일 리뷰 시작

매 푸시마다 새 리뷰를 시작하고 싶을 때, 예를 들어 Manual 모드로 설정된 리포지토리의 우선순위 높은 PR에서 @claude review always를 쓰세요. 단순 명령은 PR을 구독하지 않으므로, 이후 푸시가 리뷰를 트리거할지 바꾸지 않고 일회성 2차 의견을 요청할 수 있습니다.

2026년 7월 업데이트 이전에는 `@claude review`가 PR을 푸시 트리거 리뷰에 구독했습니다. 그 동작에 의존했다면 대신 `@claude review always` 댓글을 다세요. `@claude review once`는 여전히 동작하며 단순 명령과 같습니다.

다음 명령 중 하나로 리뷰를 트리거하려면:

  • diff 줄의 인라인 댓글이 아니라 PR 최상위 댓글로 게시
  • once나 always는 나머지 명령과 같은 줄에, 댓글 맨 앞에 명령을 둘 것
  • 리포지토리에 write, maintain, admin 권한이 있어야 함
  • PR이 열려 있어야 함

리포지토리가 조직에 속하고 그 조직에서 회원 자격이 비공개(기본값)라면 GitHub는 사용자를 Claude에게 멤버로 식별하지 않습니다. Claude가 👀으로 댓글에 반응할 수는 있어도, 팀이나 조직 기본 권한이 쓰기 접근을 줘도 리포지토리에 협력자로 직접 추가되지 않았다면 리뷰를 시작하지 않습니다. 해결하려면 조직 회원 자격을 공개하거나 리포지토리 관리자에게 협력자로 추가해 달라고 하세요.

자동 트리거와 달리 수동 트리거는 드래프트 PR에서도 실행됩니다. 명시적 요청이 드래프트 상태와 무관하게 지금 리뷰를 원한다는 신호이기 때문입니다.

그 PR에서 이미 리뷰가 실행 중이면 요청은 진행 중인 리뷰가 끝날 때까지 대기합니다. PR의 check run으로 진행 상황을 모니터링할 수 있습니다.

포크의 풀 리퀘스트 리뷰 (Review pull requests from forks)

Claude는 리포지토리의 Review Behavior 설정과 무관하게 포크의 풀 리퀘스트를 자동으로 리뷰하지 않습니다. 시작하려면 풀 리퀘스트에 @claude review 댓글을 다세요. 댓글 명령 요구사항이 그대로 적용되고, 필요한 쓰기 접근은 포크가 아니라 기본(base) 리포지토리에 대한 것입니다.

포크 풀 리퀘스트를 다시 리뷰받으려면 새 @claude review 댓글을 게시하세요. @claude review always도 동작하지만 이후 푸시의 리뷰에 풀 리퀘스트를 구독하지 않습니다. 댓글 명령 외에는 포크 풀 리퀘스트에서 리뷰를 시작하는 것이 없습니다.

  • check run의 Re-run 클릭은 리뷰를 시작하지 않음
  • After every push로 설정된 리포지토리에서도 새 커밋 푸시는 리뷰를 시작하지 않음

리뷰 커스터마이징 (Customize reviews)

Code Review는 리포지토리에서 두 파일을 읽어 무엇을 지적할지 안내합니다. 리뷰에 미치는 영향력이 다릅니다.

  • CLAUDE.md: 리뷰에만이 아니라 모든 작업에 Claude Code가 쓰는 공유 프로젝트 지시. Code Review는 이를 프로젝트 컨텍스트로 읽고 새로 도입된 위반을 nit으로 지적합니다.
  • REVIEW.md: 리뷰 전용 지시. 결과를 찾고 검증하는 에이전트에 주어지며, 순위를 매기고 보고하는 에이전트가 참고합니다. 팀이 무엇을 지적받고 싶은지, 어떤 심각도로, 결과가 어떻게 보고되는지 정할 때 씁니다.

CLAUDE.md

Code Review는 리포지토리의 CLAUDE.md 파일을 읽고 새로 도입된 위반을 nit 수준 결과로 취급합니다. 양방향으로 동작합니다. PR이 CLAUDE.md 문장을 outdated로 만드는 방식으로 코드를 바꾸면 Claude는 문서도 업데이트가 필요하다고 지적합니다.

Claude는 디렉토리 계층의 모든 수준에서 CLAUDE.md 파일을 읽으므로, 하위 디렉토리 CLAUDE.md의 규칙은 그 경로 아래 파일에만 적용됩니다. CLAUDE.md가 작동하는 방식은 메모리 문서를 참고하세요.

일반 Claude Code 세션에 적용하고 싶지 않은 리뷰 전용 안내는 REVIEW.md를 쓰세요.

REVIEW.md

REVIEW.md는 리포지토리 루트의 파일로 Code Review를 리포지토리에 맞게 조정합니다. 결과를 찾고 검증하는 에이전트는 그 내용을 Code Review 기본 리뷰 안내와 함께 리포지토리 리뷰 지시로 받고, 결과를 순위 매기고 보고하는 에이전트는 심각도를 정하고 리뷰를 쓰기 전에 참고합니다.

에이전트는 파일 텍스트를 그대로 읽으므로 REVIEW.md는 평문 지시입니다. @ import 문법은 확장되지 않고, 참조된 파일도 함께 읽지 않습니다. 적용할 규칙을 파일에 직접 넣으세요.

튜닝할 수 있는 것 (What you can tune)

REVIEW.md는 자유 형식 마크다운이므로 리뷰 지시로 표현할 수 있는 것은 무엇이든 범위에 들어갑니다. 다음 패턴이 실제로 가장 영향이 큽니다.

심각도: 🔴 Important가 리포지토리에서 무엇을 의미하는지 재정의하세요. 기본 보정은 프로덕션 코드를 목표로 합니다. 문서 저장소, 구성 저장소, 프로토타입은 훨씬 좁은 정의를 원할 수 있습니다. 어떤 종류의 결과가 Important이고 어떤 것이 기껏해야 Nit인지 명시적으로 정하세요. 반대 방향으로 올릴 수도 있는데, 예를 들어 어떤 CLAUDE.md 위반이든 기본 nit 대신 Important로 취급할 수 있습니다.

Nit 볼륨: 단일 리뷰가 게시하는 🟡 Nit 댓글 수를 제한하세요. 산문과 구성 파일은 영원히 다듬을 수 있습니다. "nit는 최대 5개만 보고하고 나머지는 요약에서 개수로 언급" 같은 캡은 리뷰를 실행 가능하게 유지합니다.

건너뛰기 규칙: Claude가 결과를 게시하지 않아야 할 경로, 브랜치 패턴, 결과 범주를 나열하세요. 흔한 후보는 생성 코드, lockfile, vendor 의존성, 머신 작성 브랜치와 CI가 이미 강제하는 lint·스펠체크 같은 것입니다. 완전한 조사 없이 약간의 리뷰가 필요한 경로는 완전히 건너뛰기보다 더 높은 기준을 설정하세요. scripts/에서는 거의 확실하고 심각할 때만 보고하세요.

리포지토리별 검사: 매 PR마다 지적받고 싶은 규칙을 추가하세요. "새 API 라우트는 통합 테스트가 있어야 한다"처럼. REVIEW.md가 모든 결과·검증 에이전트에 직접 닿으므로 긴 CLAUDE.md의 같은 규칙보다 더 확실하게 안착합니다.

검증 기준: 결과 범주가 게시되기 전에 증거를 요구하세요. 예를 들어 "동작 주장은 이름에서 추론이 아니라 소스의 file:line 인용이 필요하다"는, 그렇지 않으면 작성자에게 왕복 비용을 주는 오탐을 줄입니다.

재리뷰 수렴: PR이 이미 리뷰된 적이 있을 때 Claude가 어떻게 행동할지 알려주세요. "첫 리뷰 후에는 새 nit을 억제하고 Important만 게시" 같은 규칙이 한 줄 수정이 스타일만으로 7라운드까지 가는 걸 막습니다.

요약 형태: 리뷰 본문이 2 factual, 4 style 같은 한 줄 집계로 열리고, 그런 경우 "no factual issues"로 시작하게 하세요. 작성자는 세부사항 전에 작업의 모양을 알기를 원합니다.

예시 (Example)

이 REVIEW.md는 백엔드 서비스의 심각도를 재보정하고, nit을 제한하고, 생성 파일을 건너뛰고, 리포지토리별 검사를 추가합니다.

# Review instructions

## What Important means here

Reserve Important for findings that would break behavior, leak data,
or block a rollback: incorrect logic, unscoped database queries, PII
in logs or error messages, and migrations that aren't backward
compatible. Style, naming, and refactoring suggestions are Nit at
most.

## Cap the nits

Report at most five Nits per review. If you found more, say "plus N
similar items" in the summary instead of posting them inline. If
everything you found is a Nit, lead the summary with "No blocking
issues."

## Do not report

- Anything CI already enforces: lint, formatting, type errors
- Generated files under `src/gen/` and any `*.lock` file
- Test-only code that intentionally violates production rules

## Always check

- New API routes have an integration test
- Log lines don't include email addresses, user IDs, or request bodies
- Database queries are scoped to the caller's tenant
집중 유지 (Keep it focused)

길이는 비용이 있습니다. 긴 REVIEW.md는 가장 중요한 규칙을 희석합니다. 리뷰 동작을 바꾸는 지시만 두고 일반 프로젝트 컨텍스트는 CLAUDE.md에 남기세요.

사용량 보기 (View usage)

claude.ai/analytics/code-review에서 조직 전체의 Code Review 활동을 보세요. 대시보드가 보여주는 것:

섹션 보여주는 것
PRs reviewed 선택한 시간 범위에서 리뷰된 풀 리퀘스트의 일별 개수
Cost weekly Code Review 주간 지출
Feedback 개발자가 문제를 해결해 자동 해결된 리뷰 댓글 수
Repository breakdown 리포지토리별 리뷰된 PR 수와 해결된 댓글 수

대시보드 비용 수치는 활동 모니터링용 추정치입니다. 청구서 정확도가 필요한 지출은 Anthropic 청구서를 참고하세요.

가격 (Pricing)

Code Review는 토큰 사용량으로 청구됩니다. 각 리뷰는 평균 \$15-25이며, PR 크기, 코드베이스 복잡도, 검증이 필요한 이슈 수에 따라 조정됩니다. Code Review 사용량은 usage credits를 통해 별도 청구되며 플랜의 포함 사용량에 계산되지 않습니다.

고른 리뷰 트리거가 총 비용에 영향을 줍니다.

  • Once after PR creation: PR당 한 번
  • After every push: 푸시마다 실행되어 푸시 수만큼 비용 배가
  • Manual: 열기·푸시에서 리뷰 없음. 누군가 요청한 리뷰에서만 비용 발생

Once after PR creation 또는 Manual 모드에서 @claude review always 댓글은 PR을 푸시 트리거 리뷰에 옵트인하므로 그 댓글 이후 푸시당 추가 비용이 발생합니다. After every push 모드에서는 푸시가 이미 리뷰를 트리거하므로 구독이 푸시당 비용을 바꾸지 않습니다. @claude review 댓글은 이후 푸시 구독 없이 단일 리뷰를 실행합니다. Claude는 누군가 @claude review 댓글을 달 때만 포크의 풀 리퀘스트를 리뷰하므로, 포크 풀 리퀘스트는 어떤 모드에서도 푸시당 비용이 발생하지 않습니다.

조직이 다른 Claude Code 기능에 Amazon Bedrock이나 Google Cloud's Agent Platform을 쓰는지와 무관하게 비용은 Anthropic 청구서에 나타납니다. Code Review 월별 지출 상한을 설정하려면 claude.ai/admin-settings/usage로 가서 Claude Code Review 서비스 제한을 구성하세요.

지출은 애널리틱스의 주간 비용 차트나 관리자 설정의 리포지토리당 평균 비용 열로 모니터링하세요.

문제 해결 (Troubleshooting)

리뷰 실행은 best-effort입니다. 실패한 실행이 PR을 차단하지는 않지만 자체적으로 재시도하지도 않습니다. 이 섹션은 실패한 실행에서 복구하는 방법과 check run이 찾을 수 없는 문제를 보고할 때 어디를 봐야 하는지 다룹니다.

실패·타임아웃 리뷰 재트리거 (Retrigger a failed or timed-out review)

리뷰 인프라가 내부 오류를 만나거나 시간 제한을 초과하면 check run이 Code review encountered an error 또는 Code review timed out 제목으로 완료됩니다. 결론은 여전히 중립이라 머지를 막지 않지만 결과가 게시되지 않습니다.

리뷰를 다시 실행하려면 PR에 @claude review 댓글을 다세요. PR을 이후 푸시에 구독하지 않고 새 리뷰를 시작합니다. PR이 포크 것이 아니면 GitHub의 Checks 탭에서 Claude Code Review 체크의 Re-run을 클릭할 수도 있습니다. 재실행도 구독 없이 새 리뷰를 시작합니다.

리뷰가 실행되지 않고 PR에 지출 상한 메시지 (Review didn't run and the PR shows a spend-cap message)

조직의 월별 지출 상한에 도달하면 Code Review는 PR에 리뷰가 건너뛰었다고 설명하는 댓글 하나를 게시합니다. 다음 결제 주기 시작에 리뷰가 자동으로 재개되거나, 관리자가 claude.ai/admin-settings/usage에서 상한을 올리면 즉시 재개됩니다.

인라인 댓글로 표시되지 않는 이슈 찾기 (Find issues that aren't showing as inline comments)

check run 제목이 이슈를 찾았다고 하지만 diff에 인라인 리뷰 댓글이 안 보인다면 결과가 표시되는 다른 위치를 보세요.

  • Check run Details: Checks 탭의 Claude Code Review 체크 옆 Details를 클릭. 심각도 표가 인라인 댓글 수락 여부와 무관하게 모든 결과를 파일·줄·요약과 함께 나열.
  • Files changed 주석: PR에서 Files changed 탭을 엶. 결과가 리뷰 댓글과 별개로 diff 줄에 직접 붙은 주석으로 렌더링.
  • 리뷰 본문: 리뷰 실행 중 PR에 푸시했다면 일부 결과가 현재 diff에 더 이상 없는 줄을 참조할 수 있음. 그것들은 인라인 댓글 대신 리뷰 본문 텍스트의 Additional findings 제목 아래 나타남.

로컬 diff 리뷰 (Review a diff locally)

/code-review 명령은 GitHub App 설치 없이 터미널에서 diff를 리뷰합니다. 정확성 버그와 재사용·단순화·효율성 정리를 보고합니다.

/review는 /code-review의 별칭입니다. v2.1.223 이전에는 GitHub 풀 리퀘스트의 단일 패스·읽기 전용 리뷰를 실행하는 별도 명령이었습니다.

Step 1: /code-review 실행 — 작업 중인 세션에서 명령을 실행하세요.

/code-review

업스트림보다 앞선 브랜치 커밋과 커밋되지 않은 변경을 리뷰하므로, 보고할 것이 있으려면 브랜치나 워킹 트리에 작업이 필요합니다. 다른 것을 리뷰하려면 대상을 전달하세요. 파일 경로, PR 번호, 브랜치 이름, main...my-feature 같은 ref 범위입니다.

플래그도 추가할 수 있습니다.

  • --fix: 리뷰 후 결과를 워킹 트리에 적용
  • --comment: GitHub 풀 리퀘스트에 인라인 댓글로, GitLab 머지 리퀘스트에는 단일 노트로 결과 게시
  • --post: github.com 풀 리퀘스트의 ultra 클라우드 리뷰에서, 완료된 결과를 시작 대화상자의 PR에 게시하도록 미리 선택. 풀 리퀘스트에 결과 게시 참고. Claude Code v2.1.227 이상 필요.

GitLab 머지 리퀘스트에 --comment를 전달하면 Claude Code가 GitLab의 glab CLI로 결과를 게시합니다. Claude Code v2.1.257 이상 필요. glab이 없으면 Claude가 터미널에 결과를 출력합니다.

머지 리퀘스트를 URL이나 !123 참조로 전달하세요. Claude Code는 체크아웃의 origin이 gitlab.com에 있을 때만 숫자나 브랜치 이름을 머지 리퀘스트로 취급합니다. 셀프 매니지드 GitLab 인스턴스에서는 URL이나 !123 형태를 전달하세요.

Step 2: 계속 작업 — 리뷰는 자기 컨텍스트 창을 가진 백그라운드 서브에이전트로 실행되므로 대화를 채우지 않습니다. 리뷰가 완료되면 결과가 대화에 도착합니다.

Step 3: 결과에 대응 — 리뷰가 찾은 것을 Claude에게 고치게 하세요. --fix나 --comment를 전달했다면 리뷰가 이미 결과를 적용했거나 게시했습니다.

다음 두 실행에서는 호스트 애플리케이션이 아래 설명하는 결과 목록을 요청해도 Claude가 답변에 텍스트로 결과를 보고합니다.

  • 터미널 세션에서, /code-review가 리뷰를 포크된 서브에이전트로 실행하는 경우
  • -p 실행에서 텍스트·JSON 출력이 있는 경우

데스크톱 앱처럼 결과 목록을 요청하는 호스트 애플리케이션에서는 Claude가 대신 ReportFindings 도구로 리뷰 결과를 보고합니다. Claude Code는 결과를 결과 목록으로 렌더링하고, 각 항목이 파일 위치, 한 문장 요약, 결과가 가진 경우 correctness 같은 범주 태그를 보여줍니다. 호스트 요청은 모든 노력 수준에 적용되며 Claude Code v2.1.218 이상이 필요합니다.

Claude가 세션 후반에 보고된 결과를 고치면 다시 보고하고, Claude Code는 업데이트된 결과 목록에서 각 결과를 fixed, skipped, no change needed로 표시합니다.

리뷰가 읽고 편집하는 것 (What the review reads and edits)

리뷰는 다른 Claude Code 세션처럼 CLAUDE.md를 따르지만 REVIEW.md는 읽지 않습니다. 백그라운드 리뷰가 --fix 편집을 세션의 체크포인트 밖에 적용하므로 /rewind가 되돌리지 못합니다. git으로 되돌리세요. 리뷰가 포그라운드에서 실행되면 자기 턴 중에 워킹 트리를 편집하므로 /rewind가 평소처럼 편집을 복원합니다.

노력과 인자 튜닝 (Tune effort and arguments)

노력 수준을 전달해 커버리지를 확신과 교환하세요. low·medium에서는 가장 확신하는 결과만 보고해 오탐이 줄고, high부터 max까지는 커버리지를 넓혀 리뷰가 덜 확신하는 결과도 포함할 수 있습니다.

수준을 입력하지 않으면 리뷰는 이전 세션에서 입력한 low부터 max의 마지막 수준을 재사용하고, Claude Code는 Reusing high effort, the level you typed last time 같은 안내를 보여줍니다. /code-review high처럼 수준을 입력해 이후 실행이 재사용하는 것을 바꿀 수 있습니다. 비인터랙티브 -p 실행에서 전달한 수준은 업데이트되지 않습니다. ultra는 기억된 수준을 업데이트하지도 사용하지도 않습니다. 한 번도 수준을 입력한 적 없다면 리뷰는 세션의 현재 노력을 사용합니다. v2.1.223 이전에는 수준 없는 /code-review가 항상 세션의 현재 노력을 썼습니다.

노력 수준과 플래그 다음에 Claude Code는 한 줄의 나머지를 두 가지 중 하나로 읽습니다.

  • ultra 없음: 남은 전부가 리뷰 대상. 다른 명령 이름으로 시작해도 마찬가지입니다. /code-review /fix-issue 123은 /fix-issue를 두 번째 스택 스킬로 로드하는 대신 /fix-issue 123을 대상 텍스트로 리뷰합니다. v2.1.218 이전에는 /code-review 뒤에 스택된 명령이 자체 스킬로 확장됐습니다.
  • ultra 포함: Claude Code는 단어 하나를 기본 브랜치나 PR 번호로 읽고, 브랜치·PR 이름이 아닌 더 긴 텍스트는 리뷰에 붙은 노트로 바꿉니다. /code-review ultra check my auth changes는 현재 브랜치를 리뷰하고 Claude는 결과를 노트와 연결합니다.

포그라운드 실행 (Run in the foreground)

리뷰는 기본적으로 백그라운드에서 실행됩니다. v2.1.218 이전에는 대화 안에서 실행됐습니다. 대신 포그라운드로 실행되는 경우:

Claude가 리뷰를 시작하게 하기 (Let Claude start the review)

Claude가 스스로 /code-review를 시작할 수 있습니다. 평문으로 변경을 리뷰해 달라고 하면 명령을 직접 입력하지 않아도 스킬을 실행할 수 있고, 프롬프트가 /code-review인 예약 작업이 리뷰를 실행합니다.

예약 작업은 클라우드 리뷰를 절대 시작하지 않으므로 ultra 인자 없이 /code-review를 예약하세요.

Claude와 예약 작업이 리뷰를 시작하지 못하게 하면서 직접 /code-review를 입력하는 것을 유지하려면 설정 파일(예: ~/.claude/settings.json)에 skillOverrides 항목을 추가하세요.

{
  "skillOverrides": {
    "code-review": "user-invocable-only"
  }
}

v2.1.246 이전에는 Anthropic에서 가져온 기능 플래그가 켠 경우에만 Claude가 스스로 /code-review를 시작했습니다. 기능 플래그를 가져오지 않는 세션에서는 직접 입력할 때만 /code-review가 실행됐고, 예약된 /code-review는 평문으로 Claude에게 닿았습니다.

ultrareview로 에스컬레이션 (Escalate to ultrareview)

/code-review ultra --fix는 클라우드에서 더 깊은 ultrareview를 실행한 뒤, 결과가 세션에 돌아오면 워킹 트리에 적용합니다.

Ultrareview는 자체 범위를 씁니다. 리포지토리의 기본 브랜치에 대한 현재 브랜치, 더하기 워킹 트리의 커밋되지 않고 스테이지된 변경입니다. .env나 *.tfvars 파일처럼 자격 증명이나 키처럼 이름 붙은 파일의 커밋되지 않은 변경에는 Claude Code가 로컬 리포지토리를 GitHub 없이 클라우드 세션에 보내기 규칙을 따릅니다. /code-review ultra develop처럼 브랜치 이름을 전달해 다른 베이스를 비교하세요.

대상이 github.com 풀 리퀘스트라면 Claude에게 완료된 결과를 PR에 게시하게 해 GitHub 계정의 댓글로 남길 수 있습니다. Claude Code v2.1.227 이상 필요.

Ultrareview는 claude.ai 계정 인증이 필요하며 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry나 Zero Data Retention을 활성화한 조직에서는 사용할 수 없습니다. Ultrareview를 쓸 수 없으면 `/code-review ultra`가 세션에서 로컬 리뷰를 실행합니다.

스크립트나 CI에서 클라우드 리뷰를 시작하려면 claude -p '/code-review ultra'를 실행하세요. Claude Code가 리뷰를 시작하고 추적 링크를 출력합니다. Claude Code v2.1.218 이상 필요.

리뷰가 usage credits을 청구할 때 Claude Code는 시작 전에 멈춥니다. 청구 확인이 인터랙티브 세션을 필요로 하기 때문입니다. 대신 claude ultrareview 서브커맨드를 실행하세요. 실행함으로써 요금에 동의하는 것입니다.

이 명령은 v2.1.147 이전에 /simplify라는 이름이었고, 그때는 기본적으로 수정을 적용했습니다. /simplify는 이제 버그를 찾지 않고 수정을 적용하는 별도의 정리 전용 리뷰를 실행합니다. 버그 찾기용으로 /simplify를 스크립트했다면 /code-review --fix로 바꾸세요.

더 알아보기