Claude Code GitHub 코드 리뷰: 봇 vs 로컬 리뷰

- 요금, research preview 상태, 그리고 아래 심각도 표는 작성 시점(2026-08-20)에 code.claude.com/docs/en/code-review와 직접 대조해 확인했어요. Anthropic은 이 기능을 빠르게 바뀌는 것으로 명시하고 있으니, 정확한 수치에 의존하기 전에 라이브 문서를 확인하세요.

네이티브 GitHub Code Review 봇의 정체

이것은 Owner가 조직 레벨에서 설치하는 GitHub App으로, 어떤 리포지토리에 적용할지 선택해요. 활성화하면 PR이 열릴 때, 푸시할 때마다, 또는 누군가 PR에 @claude review라고 댓글을 달 때 - 각 리포지토리의 트리거 설정에 따라 - 리뷰가 자동으로 실행돼요.

리뷰가 실행되면 여러 에이전트가 diff를 병렬로 분석하며, 각자 코드베이스 전체의 맥락 속에서 서로 다른 종류의 문제를 찾아요. 이어서 검증 단계가 후보들을 실제 코드 동작과 대조해 오탐(false positive)을 걸러내요. 결과는 중복이 제거되고 심각도로 순위가 매겨져, 문제가 발견된 정확한 줄에 인라인 코멘트로 게시되며, 맨 위에 요약이 붙어요. 그와 함께 Claude Code Review라는 이름의 check run이 다른 CI 체크 옆에 나타나요 - 아무것도 발견되지 않으면 그 check run도 그렇게 표시하도록 업데이트돼요. 출처: code.claude.com/docs/en/code-review.

인라인 코멘트 외에도, check run의 Details 뷰에는 모든 지적이 심각도순으로 한곳에 모여 나열돼요 - 예를 들어 src/auth/session.ts:142를 가리키는 🔴 Important 줄 바로 아래에 🟡 Nit 줄이 있는 식으로 - diff를 스크롤하는 대신 PR 전체의 지적을 한 화면에서 보고 싶을 때 편리해요. 같은 지적은 Files changed 탭에도 어노테이션으로 바로 표시돼요. 리뷰가 아직 예전 diff를 분석하는 중에 새 커밋을 푸시하면, 위치가 옮겨진 플래그된 줄이 그냥 사라지지 않고 - 대신 리뷰 본문의 Additional findings 제목 아래에 다시 나타나요.

봇 vs 로컬 /code-review - 아무도 하지 않는 비교

이 기능을 다루는 대부분의 글은 봇만 설명하거나 서드파티 SaaS 도구와 비교해요. Claude Code에 이미 포함된 무료 리뷰 명령과 나란히 비교하는 글은 거의 없어요. 여기 직접 비교를 정리했어요:

Codex도 쓴다면, 그에 해당하는 리뷰 명령은 /review예요 - 프리셋도 셋업도 달라요 - 자세한 내용은 별도의 Codex Code Review (/review)에서 다뤄요.

심각도 티어(severity tiers) 설명

모든 지적에는 문서 표기 그대로의 세 가지 태그 중 정확히 하나가 붙어요:

각 지적에는 Claude가 왜 그것을 플래그했는지, 그리고 문제를 어떻게 검증했는지 설명하는 접을 수 있는 추론 섹션도 함께 있어요. 코멘트에는 👍/👎로 바로 반응할 수 있어요 - Anthropic은 PR이 머지된 뒤 그것들을 집계해 리뷰어를 튜닝하지만, 반응이 재리뷰를 트리거하거나 PR 자체에 무언가를 바꾸지는 않아요.

REVIEW.md - 무엇이 플래그될지 튜닝하는 방법

REVIEW.md는 리포지토리 루트에 두며, 리뷰 파이프라인의 모든 에이전트의 시스템 프롬프트에 최우선 지시 블록으로 그대로 주입되어 기본 리뷰 가이드를 덮어써요. 그대로 붙여넣기 때문에 @path 임포트 문법은 그 안에서 확장되지 않아요 - 리뷰어가 알아야 할 내용은 모두 파일에 직접 써야 해요.

CLAUDE.md도 함께 읽히지만 어디까지나 프로젝트 맥락으로만이고, 새로 들어온 위반은 많아야 Nit까지만 태그되며 그보다 높아지지 않아요. 양방향으로도 작동해요: 당신의 PR로 인해 CLAUDE.md의 진술이 낡아지면, Claude는 문서도 업데이트가 필요하다고 플래그해요.

놓치기 쉬운 부분: 로컬 /code-review 명령은 REVIEW.md를 읽지 않아요. 일반적인 Claude Code 세션과 마찬가지로 CLAUDE.md만 따라요. 매니지드 봇을 특별히 튜닝하고 싶다면, 거기서 효과가 있는 파일은 REVIEW.md뿐이에요.

문서를 바꿔 말한 간결한 예시예요(Important를 재정의하고, nit에 상한을 두며, 생성 파일을 건너뜀):

# Review instructions

## What Important means here
Reserve Important for findings that would break behavior, leak data,
or block a rollback. Style/naming/refactor suggestions are Nit at most.

## Cap the nits
Report at most 5 Nits per review; roll up the rest as "plus N similar items"
in the summary.

## Do not report
- Anything CI already enforces: lint, formatting, type errors
- Generated files under src/gen/ and any *.lock file

셋업 - Owner가 켜는 방법

claude.ai/admin-settings/claude-code로 가서 Code Review 섹션을 찾으세요 - Claude 조직에서 Owner 또는 Primary Owner 역할과, GitHub 조직에서 GitHub App을 설치할 권한이 필요해요. Setup을 클릭해 GitHub App 설치 플로우를 시작하세요: 리포지토리를 소유한 GitHub 조직을 고르고, 접근할 수 있는 리포지토리를 선택하고, 요청된 권한을 승인하세요. 설치가 끝나면 활성화할 리포지토리를 선택하고, 각각에 대해 Review Behavior를 고르세요: Once after PR creation, After every push, 또는 Manual(누군가 @claude review라고 댓글을 달 때만 실행).

중요한 조건: 이것은 Pro/Max를 쓰는 1인 개발자가 스스로 활성화할 수 있는 것이 아니에요 - Team/Enterprise 조직이 필요하고, 누군가 Owner 역할을 가지고 있어야 해요.

일단 실행되면, Owner는 claude.ai/analytics/code-review의 analytics 대시보드에서 도입 현황을 추적할 수 있어요: 하루에 리뷰된 PR 수, 주간 지출, 그리고 누군가 플래그된 문제를 고쳐서 리뷰 코멘트가 자동 해결된 건수가 리포지토리별로 나뉘어 표시돼요. 대시보드 숫자는 추세를 파악하기 위한 추정치로 취급하세요 - 청구서와 일치하는 정확한 지출은 실제 Anthropic 청구서에서 확인하세요.

요금 - 실제로 얼마나 드는가

각 리뷰는 평균 $15~25이며, 실제 토큰 사용량에 따라 청구되고, PR 크기와 코드베이스 복잡도에 따라 늘어나요. 이 비용은 usage credits를 통해 별도로 청구되며, Team/Enterprise 플랜에 포함된 사용량에는 산입되지 않아요. 트리거 선택이 총액을 눈에 띄게 곱해요: Once after PR creation은 PR당 정확히 한 번, Manual은 누군가 댓글을 달 때만, After every push는 푸시할 때마다 다시 실행돼요 - 셋 중 가장 비싸요. 조직은 admin settings에서 월별 지출 상한을 설정할 수 있고, 상한에 도달하면 리뷰가 일시 중지되었다가 다음 청구 주기에 자동으로 재개돼요(관리자가 상한을 올리면 즉시 재개).

비교하자면: 로컬 /code-review 명령은 이미 지불하고 있는 사용량 외에 드는 비용이 전혀 없어요.

머지를 막나요?

아니요 - 결코 막지 않아요. check run은 항상 neutral 결론으로 완료되므로, 원한다 해도 branch protection으로 그것을 직접 게이트로 삼을 수 없어요. 이것을 강력한 머지 게이트로 평가하는 팀에게는 정말 의외인 부분이에요: 실제로 강제하려면, check run 출력 끝에 있는 기계 판독 가능한 심각도 내역을 당신의 CI에서 직접 파싱해야 해요. 예:

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'
# => {"normal": 2, "nit": 1, "pre_existing": 0}

normal 키는 Important 지적의 개수예요. 0이 아닌 값은 머지 전에 고칠 가치가 있는 버그가 적어도 하나 있다는 뜻이에요.

알아두면 좋은 또 하나의 뉘앙스: 리뷰는 베스트 에포트예요. 실행이 내부 오류에 부딪히거나 타임아웃되면, check run의 제목이 Code review encountered an error 또는 Code review timed out으로 바뀌어요 - 하지만 어느 쪽이든 결론은 neutral로 유지되므로, 실패한 실행이 깨끗한 실행보다 당신을 더 막지는 않아요. 다시 시도하려면 @claude review라고 댓글을 다세요. GitHub 자체 Checks 탭의 Re-run 버튼으로는 Code Review가 다시 트리거되지 않아요.

세 번째 옵션 - 로컬에서 커스터마이즈 가능한 리뷰어

매니지드 봇과 무료 로컬 명령 외에, 솔직히 이름을 붙일 만한 세 번째 길이 있어요: AgentKit의 Engineer Kit에는 로컬 리뷰 에이전트(code-reviewer)가 들어 있고, /ak:review로 호출해요 - /code-review를 실행하는 것과 비슷하지만, 킷의 다른 에이전트/워크플로와 함께 묶여 있고, 당신이 정의한 프로세스에 맞게 커스터마이즈할 수 있으며, Team/Enterprise로 제한되지 않고, 리뷰마다 청구되지도 않아요 - 대신 킷의 1회성 가격이에요. 이것은 Anthropic 자체 봇에 대한 기능 동등성 주장이 아니라 - 다른 두 가지 중 어느 것도 원하지 않는 독자를 위한 솔직한 세 번째 비교 포인트일 뿐이에요. 로컬 명령을 자세히 보려면 로컬 /code-review 자세한 설명을 참고하세요. 제품 개요는 AgentKit 리뷰를 읽어 보세요.

어떤 것을 써야 할까요?

상호 배타적이지 않아요 - 많은 팀이 둘 이상을 함께 써요:

• 1인 개발자, 모든 플랜: 로컬 /code-review 명령 - 무료로 충분해요.
• 명령을 가르치지 않고 모든 PR에 자동 커버리지를 원하는 팀: 매니지드 봇 - 리뷰당 $15~25 예산을.
• 리뷰별 청구 없이, 모든 플랜에서 커스터마이즈 가능한 리뷰어를 원함: 킷 기반 리뷰 에이전트.

자주 묻는 질문(FAQ)

Claude Code의 네이티브 GitHub Code Review란?

조직 Owner가 활성화하는 GitHub App 봇으로, GitHub의 풀 리퀘스트를 자동으로 리뷰하고 심각도로 태그된 인라인 코멘트를 게시해요. 현재 research preview 상태예요.

무료인가요?

아니요. 리뷰 1건당 평균 $15~25이며, usage credits를 통해 별도로 청구되고, 플랜에 포함된 사용량에는 산입되지 않아요. 무료 옵션은 로컬 /code-review 명령이에요.

어떤 플랜에서 Code Review를 쓸 수 있나요?

Team과 Enterprise만(research preview)이며, Zero Data Retention이 활성화된 조직에서는 사용할 수 없어요. Pro/Max는 봇을 스스로 활성화할 수 없지만, 로컬 /code-review 명령은 모든 플랜에서 쓸 수 있어요.

머지를 막나요?

결코 막지 않아요. check run은 항상 neutral 결론으로 완료되므로 branch protection으로 그것을 직접 게이트로 삼을 수 없어요 - 강력한 게이트에는 기계 판독 가능한 심각도 내역을 CI에서 직접 파싱해야 해요.

REVIEW.md와 CLAUDE.md의 차이는?

REVIEW.md는 리뷰 전용이며, 모든 리뷰 에이전트에 최우선 지시로 주입돼요. CLAUDE.md는 일반적인 프로젝트 맥락이고, 거기서의 새 위반은 Nit까지만 태그돼요. 로컬 /code-review 명령은 CLAUDE.md는 읽지만 REVIEW.md는 읽지 않아요.

대신 로컬 /code-review 명령을 쓸 수 있나요?

네, 게다가 모든 플랜에서 무료예요. 트레이드오프: 직접 실행해야 하고, 봇이 제공하는 것처럼 모든 PR에 대한 자동 커버리지는 못 얻으며, REVIEW.md도 읽지 않아요.

결론

세 가지 옵션, 세 가지 상황: GitHub Code Review 봇은 Team/Enterprise의 research preview이고, 리뷰당 $15~25이며, 결코 머지를 막지 않아요. 로컬 /code-review 명령은 모든 플랜에서 무료지만 직접 실행해야 해요. 킷 기반 리뷰 에이전트는 커스터마이즈 가능하고 1회성 가격인 옵션이에요. 로컬 명령을 자세히 알고 싶나요? /code-review로 하는 AI 코드 리뷰를 보세요. 보안에 초점을 맞춘 완전히 다른 리뷰 레이어가 필요한가요? /security-review로 하는 보안 감사를 보세요.