요약
- 코드 리뷰는 기본 내장입니다. /code-review(별칭 /review)가 upstream보다 앞선 브랜치 커밋과 커밋하지 않은 변경을 백그라운드에서 검사합니다.
- 지적 사항은 Important, Nit, Pre-existing로 등급이 매겨지고, 각각 구체적 근거·영향·수정안이 붙으며 --fix로 바로 적용할 수 있습니다.
- 깊이는 다이얼 방식입니다. low, medium, high, max effort은 세션을 넘어 기억되고, ultra는 클라우드 ultrareview로 에스컬레이션하며, --max-findings(v2.1.288+)가 건수 상한을 조절합니다.
- GitHub에서는 Claude 앱이 설정한 트리거대로 PR을 리뷰하고 인라인 코멘트를 남깁니다. check run은 항상 neutral로 끝나기 때문에 머지를 막는 일은 없습니다.
Introducing Code Review
채널: Anthropic · Claude0:45
Anthropic's NEW Claude Code Review Agent
채널: Patrick Ellis29:56
Claude Code release notes — v2.1.288
릴리스 노트: github.com/anthropics/claude-code
Review pull requests with Claude Code — official docs
공식 문서: code.claude.com/docs
이 페이지의 사실은 공식 코드 리뷰 문서와 v2.1.288 체인지로그와 대조해 확인했고, 이미지는 위 두 영상에서 뽑은 프레임을 하나씩 검증한 것입니다. 설명된 동작은 Claude Code v2.1.288(2026년 10월) 기준입니다.
스크린샷은 Anthropic의 「Introducing Code Review」와 Patrick Ellis의 「Anthropic's NEW Claude Code Review Agent」에서 가져온 프레임으로, 출처를 밝혔으며 매 단계마다 원본 영상의 타임스탬프로 연결됩니다.
코드 리뷰, 단계별로
리뷰 돌리기
- 1
Claude Code 업데이트 후 명령어 실행
코드 리뷰는 기본 내장이라 설치할 플러그인이 없습니다. 새 플래그를 쓰려면 v2.1.288 이상으로 업데이트하고, /code-review(옛 표기 /review는 이제 별칭)를 입력하고 엔터를 치세요. 리뷰는 백그라운드에서 시작되니 하던 작업을 계속할 수 있습니다.

Anthropic은 내장 리뷰어를 전용 타이틀 카드로 발표했습니다.영상 0:07 지점 보기 - 2
리뷰를 올바른 diff로 향하게 하기
인수 없이 실행하면 /code-review는 upstream보다 앞선 커밋과 커밋하지 않은 변경을 검사합니다. 다른 대상을 지정하려면 파일 경로, PR 번호, 브랜치 이름 또는 main...my-feature 같은 범위를 넘기세요.

리뷰 세션이 시작되기 전에 저장소를 고르고 작업을 문장으로 적습니다.영상 0:08 지점 보기 - 3
백그라운드에서 돌려두기
리뷰는 별도의 에이전트라 코드를 읽는 동안에도 프롬프트는 자유입니다. 진행 중인 리뷰를 다시 앞으로 가져오려면 /code-review를 한 번 더 실행하세요. 항상 포그라운드로 실행하려면 print 모드나 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1을 씁니다.

Starting Claude Code 상태가 보이면 리뷰가 이미 출발했다는 뜻입니다.영상 0:12 지점 보기 - 4
근거와 영향이 붙은 지적 읽기
모든 지적에는 Important, Nit, Pre-existing 표식이 붙고 구체적 근거, 영향, 수정안이 함께 나옵니다. 공식 데모에서는 실제 풀 리퀘스트에서 CVSS 9.1 Critical 등급의 IDOR 버그가 잡히는 모습이 나옵니다.

지적 하나의 근거·영향·수정안. 봇이 올린 그대로입니다.영상 0:23 지점 보기
지적을 수정으로 바꾸기
- 5
지적을 풀 리퀘스트로 보내기
--comment를 붙이면 각 지적이 GitHub PR의 인라인 코멘트로 올라옵니다(GitLab MR은 v2.1.257부터 glab 경유). github.com에서 Claude GitHub 앱이 돌리는 리뷰도 같은 방식으로 지적이 도착합니다.

Claude 봇이 diff 아래에 코멘트를 달고 스레드별로 해결 버튼이 붙습니다.영상 0:18 지점 보기 - 6
--fix 또는 한 번 붙여넣기로 수정 적용
/code-review --fix를 실행하면 채택된 지적이 작업 트리에 바로 적용됩니다. 아니면 제안을 세션에 다시 붙여넣으세요. 데모에서는 파일을 고치고 todo를 지워 나가는 과정이 손도 안 대고 진행됩니다.

세션이 수정 목록의 todo를 하나씩 지워 나가는 모습을 그대로 볼 수 있습니다.영상 0:14 지점 보기 - 7
diff가 수렴할 때까지 재리뷰
수정 후 /code-review를 다시 실행하면 바뀐 부분만 재검사합니다. 재리뷰는 다시 따지는 게 아니라 수렴하라는 지시를 받기 때문에 두 번째 패스는 쌉니다. todo를 모두 지웠다면 같은 세션에서 push하고 PR을 열면 됩니다.

모든 작업 완료. 세션은 PR 생성 준비가 끝났습니다.영상 0:24 지점 보기 - 8
--max-findings로 건수 조절
v2.1.288 신규: /code-review --max-findings 5 또는 --max-findings all은 기본 상한을 무시하고, 이 선택은 --max-findings default를 넘겨 되돌릴 때까지 이후 리뷰에서도 재사용됩니다.

등급·근거·수정안을 갖춰 PR 스레드에 올라온 단 하나의 critical 지적.영상 0:20 지점 보기
깊이·자동화·규칙 조정하기
- 9
effort를 max까지, 아니면 ultra로
리뷰는 low, medium, high, max effort를 받고 마지막 선택을 세션을 넘어 기억합니다. 한 번만 입력하면 됩니다. /code-review ultra는 클라우드 ultrareview로 에스컬레이션하고, /code-review ultra --fix처럼 조합하거나 CI에서 claude ultrareview를 실행할 수도 있습니다.

리뷰 깊이는 모델 선택기 바로 옆의 다이얼입니다.영상 0:04 지점 보기 - 10
Claude GitHub 앱을 설치해 모든 PR 커버
Owner는 관리 설정에서 Code Review를 켜 Claude GitHub 앱을 설치할 수 있습니다. 저장소마다 트리거를 고르세요. PR 생성 후 한 번, 매 push 후, 또는 수동. 이후 열린 PR에서 @claude review라고 코멘트하면 실행됩니다.

Setup을 한 번 클릭하면 Claude GitHub 앱이 코드를 읽을 수 있게 됩니다.영상 0:02 지점 보기 - 11
우리 팀의 규칙을 가르치기
경로에 있는 모든 CLAUDE.md는 그대로 지켜지고, 새 위반은 nit로 표시됩니다. 호스티드 리뷰는 저장소 루트의 REVIEW.md도 읽습니다. 심각도 재정의, nit 상한, 제외 경로나 브랜치, 검증 허들 설정이 가능합니다. skillOverrides로 스킬을 직접 실행할 때만 쓰이게 제한할 수도 있습니다.

Anthropic 저장소에서 그대로 가져온 markdown 형식의 보안 리뷰 기준표.영상 18:30 지점 보기
/code-review vs /review vs /security-review vs /simplify vs ultra
Claude Code에는 리뷰 계열 명령어가 몇 개 함께 들어 있어 헷갈리기 쉽습니다. 각각이 정답이 되는 순간을 정리했습니다.
- 1/code-review — 기본 버그 사냥. upstream보다 앞선 커밋과 커밋하지 않은 변경을 검사하고, 지적을 심각도순으로 정렬하며, 작업을 계속하는 동안 백그라운드에서 돌아갑니다.
- 2/review — 같은 명령어입니다. v2.1.223부터 /review는 /code-review의 별칭입니다. 그 전에는 별개의 읽기 전용 단일 패스 PR 리뷰였기 때문에 옛 튜토리얼과 설명이 다릅니다.
- 3/security-review — Anthropic의 오픈소스 플레이북으로 만든 보안 전용 패스. 취약점만 노립니다. Patrick Ellis의 데모에서는 심어 둔 가짜 API 키를 잡아냈고, 이것 역시 Claude Code에 기본 포함입니다.
- 4/simplify — 버그 사냥이 아니라 청소. 정당성을 판단하지 않고 단순한 리팩터링과 포맷만 적용합니다. 옛 /simplify로 버그를 찾던 스크립트가 있다면 그 대상을 /code-review --fix로 바꾸세요.
- 5ultra — 클라우드 에스컬레이션. /code-review ultra는 기본 브랜치와 비교한 브랜치 전체 diff를 더 깊은 클라우드 리뷰로 보냅니다. --fix와 결합해 결과를 로컬에 적용하거나, CI에서 claude ultrareview를 실행하세요.
실전 배치는 이렇게 합니다. 코딩 중 내부 루프 기본값은 /code-review, 인증·결제·토큰을 다루는 모든 곳은 /security-review, ultra는 평소라면 동료에게 더블체크를 부탁했을 위험한 마이그레이션용으로 남겨둡니다. 순수한 스타일 정리는 /simplify의 몫이고, 애초에 리뷰가 아닙니다.
리뷰가 조용하거나, 수다스럽거나, GitHub에 없나요? 응급 처치
코드 리뷰 문제는 대부분 한 줄로 해결됩니다. 설정을 만지기 전에 이 목록부터 훑어세요.
- 1「Unknown command」이 뜨거나 옛 튜토리얼과 같은 동작 — 먼저 업데이트하세요. --max-findings는 v2.1.288+, /review 별칭은 v2.1.223부터, GitLab MR의 --comment는 v2.1.257+가 필요합니다.
- 2리뷰가 끝났는데 「아무것도 없다」 — 기본 건수 상한이 보고서를 짧게 유지합니다. --max-findings all로 다시 실행해 상한을 풀고, Critical만 기다리지 말고 Nit와 Pre-existing 표식도 살펴보세요.
- 3백그라운드로 사라졌다 — 의도된 설계입니다. 진행 중인 리뷰에 다시 붙으려면 /code-review를 재실행하고, 항상 포그라운드를 원하면 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1을 설정하세요.
- 4규칙이 무시되는 것 같다 — 로컬 /code-review는 CLAUDE.md를 따르지만 REVIEW.md는 절대 읽지 않습니다. REVIEW.md는 호스티드 GitHub 리뷰의 파일입니다. 저장소 전용 체크리스트는 REVIEW.md에, 개인·프로젝트 스타일은 CLAUDE.md에 두세요.
- 5GitHub에서 PR 리뷰가 안 올라온다 — 저장소 트리거(PR 생성 후 한 번, 매 push, 수동)를 확인하고, 코멘트하는 사람에게 write 이상 권한이 있는지 확인하세요. 포크 PR은 명시적인 @claude review 코멘트가 있어야만 리뷰됩니다.
함정 하나 더: check run의 이름은 항상 Claude Code Review이고 결론은 항상 neutral이라, 브랜치 프로텍션이 이것 때문에 머지를 막는 일은 없습니다. 막고 싶다면 자체 CI 잡에서 check run의 bughunter-severity 요약 줄을 파싱해 Important 발견 시 빌드를 실패 처리하세요.
