Claude Code /code-review 사용법: AI 코드 검토와 --max-findings 설정

Claude Code가 “테스트가 통과했다”고 말해도 검토가 끝난 것은 아닙니다. 테스트가 다루지 않은 입력, 권한 문자열을 느슨하게 비교한 조건, 실패했는데 이미 값이 바뀐 상태는 그대로 남을 수 있습니다. /diff 패널은 사람이 변경 줄을 읽는 화면이고, /code-review는 별도 서브에이전트가 실제 diff에서 정확성 문제를 찾는 명령입니다.[1]

이 글에서는 Claude Code 2.1.288 기준으로 /code-review의 기본 범위, low부터 max까지의 effort, 발견 개수를 제한하는 --max-findings, 자동 수정 옵션인 --fix를 구분합니다. 결함을 넣은 작은 JavaScript 저장소로 기존 테스트와 경계 조건 테스트가 어떻게 달라지는지도 함께 확인합니다.

/code-review가 필요한 이유

AI 코딩 도구는 구현과 검토를 같은 대화에서 이어 가기 쉽습니다. 하지만 방금 코드를 작성한 흐름 안에서는 처음 세운 가정까지 다시 의심하기 어렵습니다. /code-review는 기본적으로 별도 컨텍스트를 가진 백그라운드 서브에이전트에서 실행됩니다.[1]

역할을 나누면 다음과 같습니다.

• /diff: 추가·삭제 줄과 파일 범위를 사람이 빠르게 확인

• /code-review: 변경된 코드에서 논리 오류, 경계 조건, 회귀 가능성을 탐색

• 테스트·빌드: 발견을 수정한 뒤 실제 동작 확인

• git status·git diff: 자동 수정이 요청 범위를 넘지 않았는지 확인

/code-review 전후의 개념 흐름입니다. 작은 화면에서는 이미지를 눌러 단계 순서를 확인할 수 있습니다.

즉 /code-review가 사람의 최종 승인을 대신하지는 않습니다. AI 검토를 한 번 더 붙여 사람이 먼저 볼 위험 지점을 좁히는 도구에 가깝습니다. 변경 줄을 직접 읽는 순서는 클로드 코드 /diff 패널 사용법에서 이어서 볼 수 있습니다.

검토 범위와 실행 방식

Claude Code 세션 안에서 다음 명령을 입력합니다.

/code-review

대상을 적지 않으면 현재 브랜치가 upstream보다 앞선 커밋과 아직 커밋하지 않은 변경을 함께 검토합니다.[1] 그래서 깨끗한 main 브랜치에서 실행하면 검토할 diff가 없을 수 있습니다.

다른 범위를 지정할 수도 있습니다.

/code-review src/orders.js
/code-review feature/payment
/code-review main...feature/payment
/code-review 123

대상은 파일 경로, 브랜치, ref 범위, PR 번호가 될 수 있습니다. 저장소 전체를 막연히 읽히기보다 이번 작업에 맞는 범위를 직접 적으면 결과를 해석하기 쉽습니다.

/review도 현재는 /code-review의 별칭입니다. 다만 2.1.223 이전에는 GitHub PR을 한 번 읽는 별도 단일 패스 명령이었으므로, 팀 문서에는 정식 이름인 /code-review를 쓰는 편이 분명합니다.[1]

버전과 실습 환경

--max-findings는 Claude Code 2.1.288부터 지원합니다.[1][2] 먼저 설치 버전을 확인합니다.

claude --version

이번 격리 확인 환경은 다음과 같습니다.

기존 설치를 바꾸지 않고 정확한 버전만 확인하려면 npm 패키지를 버전까지 고정할 수 있습니다.

npx -y @anthropic-ai/claude-code@2.1.288 --version

확인 환경에서는 다음 값이 출력됐습니다.

2.1.288 (Claude Code)

버전이 낮다면 세션을 닫고 업데이트한 뒤 다시 확인합니다.

claude update
claude --version

발견 개수와 검토 강도

/code-review에는 서로 다른 두 조절축이 있습니다.

• effort: 얼마나 넓게 탐색하고 어느 정도 확신의 발견까지 보고할지 조절

• --max-findings: 최종 결과로 표시할 발견 개수의 상한 조절

둘을 같은 기능으로 보면 안 됩니다. --max-findings 2는 코드에서 두 군데만 읽으라는 뜻이 아니고, 검토가 보고하는 발견을 최대 두 건으로 줄이라는 뜻입니다.

Effort 선택

명령 뒤에 effort를 적습니다.

/code-review low
/code-review medium
/code-review high
/code-review max

공식 문서는 low와 medium은 확신이 높은 발견을 중심으로 보고해 오탐을 줄이고, high부터 max는 검토 범위를 넓혀 확신이 낮은 후보도 포함할 수 있다고 설명합니다.[1]

처음에는 다음 기준이 실용적입니다.

• 한 파일의 짧은 수정: medium

• 여러 모듈을 건드린 기능 변경: high

• 인증·결제·데이터 손실처럼 놓치기 어려운 변경: max

대화형 세션에서 직접 입력한 마지막 low~max 값은 다음 리뷰에도 재사용됩니다. 아무 단계도 입력한 적이 없다면 현재 세션의 effort를 사용합니다. -p 비대화형 실행에서 넘긴 단계는 저장된 값을 바꾸지 않습니다.[1] 일반 /effort의 모델별 설정과 상한은 Claude Code /effort 설정에서 따로 설명합니다.

--max-findings 설정

Claude Code 2.1.288에는 다음 세 가지 형태가 추가됐습니다.[1][2]

/code-review high --max-findings 2
/code-review high --max-findings all
/code-review --max-findings default

• 숫자: 최대 N건까지만 보고

• all: 찾은 발견을 모두 보고

• default: 저장된 선택을 지우고 제품의 일반 제한으로 복귀

입력한 숫자나 all은 현재 한 번만 쓰고 사라지는 값이 아닙니다. default를 입력할 때까지 이후 리뷰에서 재사용됩니다. 팀원이 “왜 두 건만 계속 나오지?”라고 묻는다면 검토 품질보다 저장된 상한부터 확인해야 합니다.

처음에는 2나 3으로 중요한 문제부터 처리하고, 수정 후 all로 한 번 더 보는 흐름이 부담이 적습니다.

/code-review high --max-findings 2
# 중요한 발견을 읽고 직접 수정
/code-review high --max-findings all
# 남은 후보 확인
/code-review --max-findings default

결함을 넣은 격리 저장소

운영 프로젝트에서 처음부터 --fix를 시험하지 않습니다. 작은 Git 저장소를 만들고 정상 구현을 커밋한 뒤, 세 가지 검증을 느슨하게 바꿔 미커밋 diff를 만듭니다.

export function applyDiscount(total, percent) {
  return total - total * (percent / 100);
}

export function canViewAdmin(user) {
  return user?.role?.includes('admin') ?? false;
}

export function reserveStock(stock, quantity) {
  stock.available -= quantity;
  if (stock.available < 0) {
    return { ok: false, available: stock.available };
  }
  return { ok: true, available: stock.available };
}

겉으로는 짧고 자연스러워 보이지만 경계 조건이 세 군데 있습니다.

1. 할인율이 100을 넘거나 음수여도 계산함

2. superadmin-disabled처럼 admin을 포함한 문자열도 관리자 권한으로 인정함

3. 재고가 부족한 실패 경로에서도 stock.available을 먼저 줄임

기존 테스트는 정상 입력만 다룹니다.

test('applies a normal discount', () => {
  assert.equal(applyDiscount(100, 20), 80);
});

test('recognizes the admin role', () => {
  assert.equal(canViewAdmin({ role: 'admin' }), true);
});

test('reserves available stock', () => {
  const stock = { available: 5 };
  assert.deepEqual(reserveStock(stock, 2), { ok: true, available: 3 });
});

실제로 npm test를 실행하면 세 건이 모두 통과합니다.

# tests 3
# pass 3
# fail 0

이 결과는 정상 경로가 동작한다는 뜻이지, 위 세 가지 경계 조건이 안전하다는 뜻은 아닙니다. 로그인된 Claude Code 2.1.288에서 미커밋 diff를 대상으로 다음 명령을 실행했습니다.

/code-review high --max-findings 2

재현 로그를 남기기 위해 실제 실습에서는 같은 명령을 비대화형 래퍼로 호출했습니다. 이 방식은 리뷰가 끝날 때까지 포그라운드에서 기다립니다.

npx -y @anthropic-ai/claude-code@2.1.288 \
  -p '/code-review high --max-findings 2' \
  --output-format text \
  --permission-mode dontAsk

결과는 먼저 세 가지 실제 버그를 찾았다고 밝힌 뒤, 상한에 맞춰 가장 심각한 두 건만 JSON 목록에 담았습니다.

I found three real bugs in the uncommitted changes to `src/orders.js`.
The output cap is 2, so I kept the two most severe:

표시된 두 건은 canViewAdmin의 부분 문자열 권한 검사와 reserveStock의 검증 전 재고 차감이었습니다. 할인율 범위 검사가 사라진 문제는 “상한 때문에 잘린 세 번째 버그”로 목록 아래에 따로 언급됐습니다.

이 비대화형 실행에서는 셸 명령 권한이 거부돼 CLAUDE.md를 확인하지 못했다는 고지도 함께 나왔습니다. 이번 격리 저장소에는 해당 파일이 없었지만, 실제 프로젝트에서 지침 준수까지 검토하려면 리뷰가 필요한 읽기 권한을 받았는지 결과 끝부분까지 확인해야 합니다.

같은 diff를 all로 다시 검토했습니다.

/code-review high --max-findings all

이번에는 7개 발견이 출력됐습니다. 독립된 버그가 일곱 개라는 뜻은 아닙니다. 재고 차감과 수량 검증, 권한 상승과 반환형 문제처럼 한 코드 변화가 여러 발견으로 나뉘었고, 행복 경로만 다루는 테스트의 공백과 안전 검증을 되돌린 변경 의도도 별도 항목으로 포함됐습니다.

발견 개수보다 먼저 파일과 줄, 실패 조건, 재현 가능한 입력이 적혀 있는지 봅니다. 모델 응답은 실행할 때마다 달라질 수 있으므로 다른 환경에서도 같은 일곱 항목이 같은 문장으로 나온다고 기대하면 안 됩니다. 상한을 높이기 전에 첫 발견이 코드와 맞는지 직접 확인합니다.

발견을 테스트로 바꾸기

리뷰가 지적한 조건이 맞다면 설명만 읽고 바로 코드를 고치지 않습니다. 먼저 같은 문제가 다시 생기면 실패하는 테스트를 추가합니다.

test('rejects a discount over 100 percent', () => {
  assert.throws(() => applyDiscount(100, 120), RangeError);
});

test('does not accept a role that merely contains admin', () => {
  assert.equal(canViewAdmin({ role: 'superadmin-disabled' }), false);
});

test('does not mutate stock when reservation fails', () => {
  const stock = { available: 1 };
  assert.deepEqual(reserveStock(stock, 2), { ok: false, available: 1 });
  assert.equal(stock.available, 1);
});

결함이 남은 상태에서 실제로 실행하니 기존 3건은 통과하고 새 경계 조건 3건은 실패했습니다.

# tests 6
# pass 3
# fail 3

그다음 입력 검증, 정확한 역할 비교, 변경 전 재고 확인 순서로 고칩니다.

export function applyDiscount(total, percent) {
  if (total < 0 || percent < 0 || percent > 100) {
    throw new RangeError('invalid discount input');
  }
  return total - total * (percent / 100);
}

export function canViewAdmin(user) {
  return user?.role === 'admin';
}

export function reserveStock(stock, quantity) {
  if (!Number.isInteger(quantity) || quantity <= 0 || stock.available < quantity) {
    return { ok: false, available: stock.available };
  }
  stock.available -= quantity;
  return { ok: true, available: stock.available };
}

수정 후 같은 명령을 실행하니 기존 정상 경로와 새 경계 조건을 합친 6건이 모두 통과했습니다.

# tests 6
# pass 6
# fail 0

리뷰 문장이 그럴듯한지가 아니라, 실패를 재현한 테스트가 통과하는지 확인하는 단계입니다.

--fix를 바로 쓰지 않는 이유

발견과 수정을 한 번에 처리할 수도 있습니다.

/code-review high --max-findings 2 --fix

하지만 공식 문서에는 중요한 경계가 하나 적혀 있습니다. 기본 백그라운드 리뷰가 --fix로 바꾼 파일은 현재 대화의 체크포인트 밖에서 수정됩니다. 따라서 /rewind가 그 변경을 되돌리지 못하며 Git으로 복구해야 합니다.[1]

처음 사용하는 저장소에서는 다음 순서가 안전합니다.

1. --fix 없이 발견만 받기

2. 각 발견을 코드와 테스트로 재현하기

3. 직접 수정하거나 한 건씩 수정 요청하기

4. git diff와 테스트 확인하기

5. 남은 변경을 다시 /code-review로 검토하기

--fix를 쓴다면 시작 전에 최소한 현재 상태를 확인합니다.

git status --short
npm test

실행 후에는 설명보다 파일 상태를 먼저 봅니다.

git status --short
git diff --check
git diff
npm test

/rewind만 믿고 자동 수정을 넓게 적용하면 원래 변경과 리뷰 수정이 섞일 수 있습니다. 별도 브랜치나 Git Worktree에서 시험하면 원본 작업과 비교하기 쉽습니다.

포그라운드와 비대화형 실행

일반 세션의 리뷰는 백그라운드에서 돌아가므로 다른 작업을 이어 갈 수 있습니다. 다음 경우에는 포그라운드에서 기다립니다.[1]

• 이전 리뷰가 끝나기 전에 /code-review를 다시 실행

• -p 비대화형 모드나 Agent SDK로 실행

• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 설정

자동화에서 텍스트 결과를 받으려면 다음처럼 실행할 수 있습니다.

claude -p '/code-review high --max-findings 2' --output-format text

이 방식은 리뷰가 끝날 때까지 기다린 뒤 결과를 출력합니다. CI에서 바로 --fix까지 붙이기보다 읽기 전용 결과를 아티팩트로 남기고, 테스트와 diff를 별도 단계에서 확인하는 편이 범위를 통제하기 쉽습니다.

--comment와 로컬 검토 구분

로컬에서 결과만 보는 기본 실행과 원격 PR에 쓰는 동작은 분리해야 합니다.

/code-review --comment 123

--comment는 GitHub PR에 인라인 코멘트를 달거나 GitLab MR에 단일 노트를 게시합니다. GitLab 게시에는 glab CLI와 Claude Code 2.1.257 이상이 필요하며, glab이 없으면 원격에 쓰지 않고 결과를 터미널에 출력합니다.[1]

GitLab.com 저장소는 origin이 gitlab.com일 때 bare 번호나 브랜치를 MR로 해석합니다. Self-managed GitLab에서는 MR URL 또는 !123 형식을 사용합니다. 원격 기록을 남기는 쓰기 작업이므로 개인 실습에서는 기본 로컬 검토부터 시작합니다.

관리형 Code Review 서비스도 이름은 같지만 별도 기능입니다. 조직 관리자가 GitHub App을 설치해 PR마다 여러 에이전트를 실행하는 서비스이고, 로컬 /code-review는 현재 Claude Code 세션에서 diff를 검토합니다. 이 글의 명령에는 관리형 서비스 설치가 필요 없습니다.

결과가 이상할 때

검토할 변경이 없다고 나옴

현재 브랜치가 upstream보다 앞서지 않았고 작업 트리도 깨끗한지 확인합니다.

git status --short --branch
git log --oneline @{upstream}..HEAD

다른 브랜치를 검토하려면 범위를 직접 지정합니다.

/code-review main...feature/payment

발견이 계속 두 건만 나옴

이전에 --max-findings 2를 입력했다면 저장된 값이 재사용될 수 있습니다. 일반 제한으로 돌아갑니다.

/code-review --max-findings default

모든 후보를 보고 싶다면 all을 쓰되, 발견 수가 늘어날수록 오탐 확인 비용도 커진다는 점을 감안합니다.

리뷰가 너무 넓거나 오탐이 많음

먼저 대상 파일이나 ref를 좁히고 effort를 낮춥니다.

/code-review medium --max-findings 3 src/orders.js

CLAUDE.md는 로컬 리뷰도 따르지만, 관리형 Code Review 전용 지침 파일인 REVIEW.md는 로컬 /code-review가 읽지 않습니다.[1] 두 기능의 지침 범위를 섞지 않아야 합니다.

자동 수정 뒤 원래 상태로 돌아가고 싶음

백그라운드 --fix는 /rewind가 아니라 Git으로 확인하고 복구합니다.

git status --short
git diff

파일을 되돌리는 명령은 다른 작업까지 지울 수 있으므로 diff를 읽기 전에 실행하지 않습니다. 별도 브랜치나 worktree라면 브랜치 비교로 원래 변경과 리뷰 수정을 나누기 쉽습니다.

커밋 전 검토 순서

/code-review의 가치는 AI가 코드를 대신 승인해 주는 데 있지 않습니다. 테스트가 놓친 조건을 후보로 올리고, 사람이 재현 가능한 테스트와 Git diff로 사실 여부를 확인하게 만드는 데 있습니다.

처음에는 발견 개수를 작게 제한해 중요한 문제부터 처리하세요. 그다음 범위를 넓히고, 마지막에는 저장된 --max-findings를 초기화합니다. --fix는 검토 흐름에 익숙해진 뒤 별도 브랜치에서 사용해야 수정 범위와 되돌리는 방법을 놓치지 않습니다.

참고 자료

[1] https://code.claude.com/docs/en/code-review — Claude Code Code Review, 로컬 /code-review 섹션
[2] https://github.com/anthropics/claude-code/releases/tag/v2.1.288 — Claude Code v2.1.288 release