Deepseek ArtifactsDeepseek Artifacts
코드 리뷰 · v2.1.288 반영

Claude Code 코드 리뷰: /code-review, 스킬, effort 총정리

내장 /code-review 명령어의 사용법: 브랜치나 PR에 향하게 하고, 근거와 영향이 붙은 지적을 순위별로 읽고, effort와 --max-findings를 조절한 뒤 모든 풀 리퀘스트에 리뷰를 붙이는 것까지.

요약

  • 코드 리뷰는 기본 내장입니다. /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. 1

    Claude Code 업데이트 후 명령어 실행

    코드 리뷰는 기본 내장이라 설치할 플러그인이 없습니다. 새 플래그를 쓰려면 v2.1.288 이상으로 업데이트하고, /code-review(옛 표기 /review는 이제 별칭)를 입력하고 엔터를 치세요. 리뷰는 백그라운드에서 시작되니 하던 작업을 계속할 수 있습니다.

    Anthropic's Introducing Code Review title card with the pixel crab mascot announcing the code review feature built into Claude Code
    Anthropic은 내장 리뷰어를 전용 타이틀 카드로 발표했습니다.영상 0:07 지점 보기
  2. 2

    리뷰를 올바른 diff로 향하게 하기

    인수 없이 실행하면 /code-review는 upstream보다 앞선 커밋과 커밋하지 않은 변경을 검사합니다. 다른 대상을 지정하려면 파일 경로, PR 번호, 브랜치 이름 또는 main...my-feature 같은 범위를 넘기세요.

    Claude Code desktop launcher opened on the acme/saas-app repo with the task prompt typed in and the Opus 4.6 model selector visible above the input
    리뷰 세션이 시작되기 전에 저장소를 고르고 작업을 문장으로 적습니다.영상 0:08 지점 보기
  3. 3

    백그라운드에서 돌려두기

    리뷰는 별도의 에이전트라 코드를 읽는 동안에도 프롬프트는 자유입니다. 진행 중인 리뷰를 다시 앞으로 가져오려면 /code-review를 한 번 더 실행하세요. 항상 포그라운드로 실행하려면 print 모드나 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1을 씁니다.

    Claude Code session showing the review task description above a Starting Claude Code status line with a Ready to code input waiting below
    Starting Claude Code 상태가 보이면 리뷰가 이미 출발했다는 뜻입니다.영상 0:12 지점 보기
  4. 4

    근거와 영향이 붙은 지적 읽기

    모든 지적에는 Important, Nit, Pre-existing 표식이 붙고 구체적 근거, 영향, 수정안이 함께 나옵니다. 공식 데모에서는 실제 풀 리퀘스트에서 CVSS 9.1 Critical 등급의 IDOR 버그가 잡히는 모습이 나옵니다.

    Claude bot review finding on a GitHub pull request listing Concrete proof, Impact and fix for an IDOR bug rated CVSS 9.1 Critical
    지적 하나의 근거·영향·수정안. 봇이 올린 그대로입니다.영상 0:23 지점 보기

지적을 수정으로 바꾸기

  1. 5

    지적을 풀 리퀘스트로 보내기

    --comment를 붙이면 각 지적이 GitHub PR의 인라인 코멘트로 올라옵니다(GitLab MR은 v2.1.257부터 glab 경유). github.com에서 Claude GitHub 앱이 돌리는 리뷰도 같은 방식으로 지적이 도착합니다.

    Claude bot comment posted under a src/api/sessions.ts diff after reviewing the pull request two minutes earlier, with a Resolve conversation button
    Claude 봇이 diff 아래에 코멘트를 달고 스레드별로 해결 버튼이 붙습니다.영상 0:18 지점 보기
  2. 6

    --fix 또는 한 번 붙여넣기로 수정 적용

    /code-review --fix를 실행하면 채택된 지적이 작업 트리에 바로 적용됩니다. 아니면 제안을 세션에 다시 붙여넣으세요. 데모에서는 파일을 고치고 todo를 지워 나가는 과정이 손도 안 대고 진행됩니다.

    Claude Code todo list striking out finished fix tasks after editing sessions.test.ts while the session status reads Claudeing
    세션이 수정 목록의 todo를 하나씩 지워 나가는 모습을 그대로 볼 수 있습니다.영상 0:14 지점 보기
  3. 7

    diff가 수렴할 때까지 재리뷰

    수정 후 /code-review를 다시 실행하면 바뀐 부분만 재검사합니다. 재리뷰는 다시 따지는 게 아니라 수렴하라는 지시를 받기 때문에 두 번째 패스는 쌉니다. todo를 모두 지웠다면 같은 세션에서 push하고 PR을 열면 됩니다.

    Claude Code session reporting all tasks complete and ready to create a PR, with Create PR, VS Code and CLI buttons under the transcript
    모든 작업 완료. 세션은 PR 생성 준비가 끝났습니다.영상 0:24 지점 보기
  4. 8

    --max-findings로 건수 조절

    v2.1.288 신규: /code-review --max-findings 5 또는 --max-findings all은 기본 상한을 무시하고, 이 선택은 --max-findings default를 넘겨 되돌릴 때까지 이후 리뷰에서도 재사용됩니다.

    Claude bot review thread on a pull request with an Extended reasoning section, a thumbs up reaction and a Reply box under the code change
    등급·근거·수정안을 갖춰 PR 스레드에 올라온 단 하나의 critical 지적.영상 0:20 지점 보기

깊이·자동화·규칙 조정하기

  1. 9

    effort를 max까지, 아니면 ultra로

    리뷰는 low, medium, high, max effort를 받고 마지막 선택을 세션을 넘어 기억합니다. 한 번만 입력하면 됩니다. /code-review ultra는 클라우드 ultrareview로 에스컬레이션하고, /code-review ultra --fix처럼 조합하거나 CI에서 claude ultrareview를 실행할 수도 있습니다.

    Claude GitHub App permission card with a hand cursor clicking the Setup button that lets Claude read code and review pull requests
    리뷰 깊이는 모델 선택기 바로 옆의 다이얼입니다.영상 0:04 지점 보기
  2. 10

    Claude GitHub 앱을 설치해 모든 PR 커버

    Owner는 관리 설정에서 Code Review를 켜 Claude GitHub 앱을 설치할 수 있습니다. 저장소마다 트리거를 고르세요. PR 생성 후 한 번, 매 push 후, 또는 수동. 이후 열린 PR에서 @claude review라고 코멘트하면 실행됩니다.

    Claude admin settings page showing the Code Review preview row that requires the Claude GitHub App to be installed on the organization
    Setup을 한 번 클릭하면 Claude GitHub 앱이 코드를 읽을 수 있게 됩니다.영상 0:02 지점 보기
  3. 11

    우리 팀의 규칙을 가르치기

    경로에 있는 모든 CLAUDE.md는 그대로 지켜지고, 새 위반은 nit로 표시됩니다. 호스티드 리뷰는 저장소 루트의 REVIEW.md도 읽습니다. 심각도 재정의, nit 상한, 제외 경로나 브랜치, 검증 허들 설정이 가능합니다. skillOverrides로 스킬을 직접 실행할 때만 쓰이게 제한할 수도 있습니다.

    security-review.md prompt open in the anthropics/claude-code-security-review repository defining severity rules from hardcoded API keys to injection checks
    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 발견 시 빌드를 실패 처리하세요.

Claude Code 코드 리뷰 FAQ

Claude Code 가이드 더 보기