/code-review로 로컬 리뷰하기

기준일: 2026-10-23
공식 기준: Review locally with /code-review

개요

/code-review는 작업 중인 Claude Code 세션의 프롬프트에 입력하는 명령입니다. Claude가 브랜치의 변경을 검토해 정확성 버그를 찾고 결과를 대화에 보고합니다. 모델과 effort 수준에 따라 재사용·단순화·효율 정리까지 다룹니다. 모든 플랜에서 동작하고 리뷰가 내 세션에서 실행되므로 나머지 세션처럼 플랜 사용량이나 API 과금에 집계됩니다.

• GitHub에서 저장소의 모든 PR을 자동으로 리뷰하려면 Owner가 조직에 켜는 관리형 서비스 Code Review를 보세요.
• /review는 /code-review의 alias입니다. v2.1.223 이전의 /review는 GitHub PR을 읽기 전용 단일 패스로 리뷰하는 별도 명령이었습니다(2.1.223에서 alias로 변경).

핵심 개념

항목	설명
실행	백그라운드 subagent가 자체 컨텍스트 창에서 리뷰 → 대화를 채우지 않고 완료 시 결과 도착
--fix	리뷰 후 findings를 작업 트리에 적용하도록 요청. 편집은 permission mode를 거침
--comment	GitHub PR에는 inline 코멘트, GitLab merge request에는 단일 노트로 게시
--post	ultra 클라우드 리뷰(github.com PR)에서 완료된 findings를 PR에 게시하는 옵션을 launch 대화상자에서 미리 선택 (2.1.227+)
--max-findings <n> / all / default	보고할 findings 수 조정 (2.1.288+)
effort 수준	low~`max, ultra`(클라우드 리뷰)

상세

사용 순서

1. 실행

/code-review

대상을 주지 않으면 현재 브랜치의 변경을 리뷰합니다. 플래그를 추가할 수 있습니다: --fix(리뷰 후 findings를 작업 트리에 적용하도록 요청, 편집은 permission mode 경유), --comment(GitHub PR inline 코멘트 또는 GitLab merge request 단일 노트로 게시).

2. 계속 작업: 리뷰는 자체 컨텍스트 창의 백그라운드 subagent로 실행되어 대화를 채우지 않고, 완료되면 findings가 대화에 도착합니다.

3. findings 처리: Claude에게 findings를 고치라고 요청합니다. --fix나 --comment를 쓰면 리뷰의 일부로 적용·게시하며 편집 승인을 요청받을 수 있습니다.

리뷰 대상 선택

effort 수준과 플래그 뒤에 대상을 입력합니다. 대상은 PR 번호, 브랜치 이름, 파일 경로, Git revision 범위일 수 있습니다.

리뷰 대상	입력
현재 브랜치와 커밋 안 한 변경	/code-review
최근 커밋 15개	/code-review HEAD~15..HEAD
한 브랜치를 다른 브랜치와 비교	/code-review main...my-feature
단일 커밋(abc1234는 커밋 해시)	/code-review abc1234^..abc1234
번호로 지정한 PR	/code-review 1234
파일 또는 디렉터리 경로	/code-review src/auth

대상이 없으면 upstream 브랜치보다 앞선 브랜치 커밋과 커밋 안 한 변경을 리뷰합니다. upstream이 없으면 main과 비교하거나 이전 커밋과 비교합니다. ultra와 함께 쓰면 대상을 다르게 읽습니다(아래 "effort 수준 뒤 텍스트").

리뷰가 읽고 편집하는 것

특히 --fix 전에 확인하세요.

• 편집: --fix 없이는 리뷰 지시가 Claude에게 보고만 요청하고, --fix는 findings를 작업 트리에 적용하도록도 요청합니다. 어느 쪽이든 편집은 permission mode를 거칩니다.
• 되감기: 백그라운드 리뷰의 --fix 편집은 세션의 checkpoint 밖에서 적용됩니다. 이후 /rewind는 대화에서 이미 Claude가 편집한 파일만 복원하며 리뷰의 다른 파일 편집은 남으므로 git으로 되돌립니다. 리뷰를 foreground로 실행하면 내 턴에서 작업 트리를 편집하므로 /rewind가 평소처럼 복원합니다. (2.1.309: /code-review --fix로 checkpoint 파일을 바꾼 턴이 /rewind 목록에서 "No code changes"로 표시되던 문제 수정)
• 지침: 리뷰는 비대화형 -p 실행을 포함해 CLAUDE.md를 따릅니다. REVIEW.md는 읽지 않으며 이 파일은 GitHub PR의 관리형 Code Review 서비스를 구성합니다.

findings 보고 방식

터미널 세션(/code-review가 forked subagent로 리뷰 실행)과 텍스트/JSON 출력의 -p 실행에서는 응답 텍스트로 보고합니다. 데스크톱 앱 같은 호스트 애플리케이션이 findings 목록을 요청하면 ReportFindings 도구로 보고하며 파일 위치, 한 문장 요약, 해당되면 correctness 같은 카테고리 태그가 든 findings 목록으로 표시됩니다. 호스트 요청은 모든 effort에서 적용되며 Claude Code v2.1.218+가 필요합니다. 나중에 세션에서 Claude가 보고된 findings를 고치면 다시 보고하고, Claude Code가 갱신된 findings 목록에서 각 항목을 fixed/skipped/no change needed로 표시합니다. (2.1.296: 클라우드 세션·Agent SDK·IDE 통합에서 원시 JSON 배열로 끝나던 문제를 번호 목록으로 수정)

인자와 effort 조정

--fix, --comment 외 플래그:

• --post: ultra 클라우드 리뷰의 github.com PR에서 완료된 findings를 PR에 게시하는 것을 launch 대화상자에서 미리 선택(PR에 findings 게시). v2.1.227+
• --max-findings <n>, --max-findings all, --max-findings default: 평소 한도 대신 최대 n개 또는 all로 모든 findings 보고. findings 도구로 보고하는 곳의 한도는 32. 이후 리뷰는 --max-findings default를 전달하기 전까지 입력한 값을 재사용하지만 비대화형 -p 실행에서 전달한 값은 기억하지 않습니다. v2.1.288+

effort 수준으로 커버리지와 확신을 조절합니다. low는 가장 확신하는 findings만 보고해 오탐이 줄고, medium~`max`는 커버리지를 넓힙니다. (2.1.290: medium effort에서 튜닝된 리뷰 설정이 없는 모델(Opus 5.5, Sonnet 5.5 포함)도 cleanup과 CLAUDE.md 규약 findings를 함께 보고. 2.1.274: 튜닝된 설정이 없는 모델은 많은 리뷰 subagent를 띄우는 대신 더 가벼운 inline 리뷰 프롬프트 사용. 2.1.232: high/xhigh/max effort도 다른 수준처럼 백그라운드 에이전트로 실행)

수준을 입력하지 않으면 이전 세션이라도 마지막으로 입력한 low~`max수준을 재사용하며Reusing high effort, the level you typed last time` 같은 알림이 표시됩니다(2.1.223+, 이전에는 세션의 현재 effort 사용). 규칙:

• 수준 입력: /code-review high처럼 입력한 수준이 이후 실행이 재사용할 값을 바꿈
• 비대화형 실행: 비대화형 -p에서 전달한 수준은 기억된 수준을 갱신하지 않음
• ultra: 기억된 수준을 사용하지도 갱신하지도 않음
• 수준을 입력한 적 없음: 세션의 현재 effort 사용

GitLab merge request에 findings 게시

GitLab merge request에 --comment를 쓰면 GitLab의 glab CLI로 게시합니다(Claude Code v2.1.257+, glab mr note). glab이 설치돼 있지 않으면 터미널에 findings를 출력합니다. merge request는 URL 또는 !123 참조로 전달하세요. checkout의 origin이 gitlab.com일 때만 번호나 브랜치 이름만 있어도 merge request로 취급하며, 자체 호스팅 GitLab에서는 URL 또는 !123 형태를 씁니다.

effort 수준과 플래그 뒤 텍스트

effort 수준과 플래그 뒤 나머지 줄을 리뷰 대상으로 읽으며 ultra가 읽는 방식을 바꿉니다.

• ultra와 함께: 한 단어는 base 브랜치 또는 PR 번호로 읽고, 브랜치나 PR을 지정하지 않는 더 긴 텍스트는 리뷰에 붙는 메모가 됩니다. /code-review ultra check my auth changes는 현재 브랜치를 리뷰하고 Claude가 findings를 메모와 연결합니다.
• ultra 없이: 다른 명령 이름으로 시작해도 남은 모든 것이 리뷰 대상입니다. /code-review /fix-issue 123은 /fix-issue를 두 번째 stacked skill로 로드하지 않고 /fix-issue 123을 대상 텍스트로 리뷰합니다. v2.1.218 이전에는 /code-review 뒤에 쌓은 명령이 별개의 skill로 확장됐습니다.

foreground로 실행

다음 중 하나로 foreground 실행합니다.

• 비대화형 모드(-p 플래그 또는 Agent SDK): Claude Code가 리뷰를 기다려 응답에 findings를 포함합니다(ultra는 클라우드 리뷰를 기다리지 않음).
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS를 1로 설정(다른 모든 백그라운드 태스크 기능도 꺼짐)
• 이전 리뷰가 진행 중일 때 /code-review를 다시 실행

v2.1.218 이전에는 리뷰가 대화 안에서 실행됐습니다.

Claude가 리뷰를 시작하게 하기

Claude는 명령을 입력하지 않아도 스스로 /code-review를 시작할 수 있습니다. 변경을 리뷰해 달라고 일반 말로 요청하면 skill을 실행하고, /code-review를 프롬프트로 한 세션 범위 예약 작업이 리뷰를 실행합니다. 세션 범위 예약 작업은 클라우드 리뷰를 시작하지 않으므로 ultra 인자 없이 예약하세요.

내가 입력하는 /code-review는 유지한 채 Claude와 예약 작업의 시작을 막으려면 ~/.claude/settings.json 같은 settings 파일에 skillOverrides를 추가합니다.

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

v2.1.246 이전에는 Anthropic에서 가져오는 feature flag가 켠 곳에서만 Claude가 /code-review를 스스로 시작했습니다. feature flag를 가져오지 않는 세션에서는 직접 입력할 때만 실행됐고 예약된 /code-review는 일반 텍스트로 Claude에 전달됐습니다. 2.1.246부터 Bedrock, Vertex AI, Foundry, Claude apps gateway, 텔레메트리·비필수 트래픽 비활성 세션에서도 Claude가 스스로 시작할 수 있습니다.

ultrareview로 확장

/code-review ultra --fix는 더 깊은 ultrareview를 클라우드에서 실행하고 findings가 세션에 도착하면 작업 트리에 적용하도록 Claude에 요청합니다. 자체 범위를 가집니다.

• 비교 대상: 현재 브랜치와 저장소 기본 브랜치, 그리고 작업 트리의 커밋 안 한 변경과 staged 변경
• 민감한 파일: .env, *.tfvars처럼 자격 증명·키로 이름 붙은 파일의 커밋 안 한 변경은 로컬 저장소를 클라우드 세션에 업로드하는 규칙을 따름
• 다른 base: /code-review ultra develop처럼 브랜치 이름을 전달

대상이 github.com PR이면 Claude가 완료된 findings를 내 GitHub 계정 코멘트로 PR에 게시하게 할 수 있습니다(v2.1.227+).

참고: ultrareview는 claude.ai 계정 인증이 필요합니다. Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry와 Zero Data Retention 또는 HIPAA 구성 조직에서는 사용할 수 없습니다. 이 경우 /code-review ultra는 세션에서 로컬 리뷰를 실행합니다. 고객 관리 암호화 키(CMEK)를 쓰는 조직은 ultrareview를 실행할 수 없으며 변경을 로컬로 리뷰하려면 /code-review를 실행하세요.

스크립트나 CI job에서 클라우드 리뷰를 돌리려면 claude ultrareview 서브커맨드를 쓰세요. findings를 기다려 stdout에 출력합니다.

리뷰를 바꾸거나 확장

/code-review는 bundled skill로 지침이 Claude Code에 내장돼 열어 편집할 SKILL.md가 디스크에 없습니다. 모든 리뷰에 프로젝트 규칙을 따르게 하려면 CLAUDE.md에 추가합니다. 더 나아가려면:

• 명령 교체: code-review라는 이름의 프로젝트/개인 skill이 번들 skill 대신 실행되고 /review alias는 번들 리뷰를 계속 실행(같은 이름을 공유하는 skills 해결 규칙 참고)
• 직접 리뷰어 구축: 리뷰어 subagent 또는 리뷰 skill 작성
• 인접 명령: /simplify는 정리 리뷰만 하고 수정을 적용하며, /verify는 앱을 실행해 변경이 동작하는지 확인

이 명령은 v2.1.147 이전에는 기본으로 수정을 적용하던 /simplify라는 이름이었습니다. 버그 찾기용으로 /simplify를 스크립트에 썼다면 /code-review --fix로 바꾸세요.

함께 보기

• Code Review (관리형 서비스)
• Ultrareview
• Commands
• Skills