Code Review 커스터마이즈 (REVIEW.md)
기준일: 2026-10-23
공식 기준: Customize Code Review
개요
저장소에 지침을 커밋해 Code Review가 지적하는 것을 바꿉니다. nit 양을 줄이거나, 생성 파일에 대한 코멘트를 막거나, 팀이 중요시하는 규칙을 추가할 때 씁니다. 두 파일 중 하나에 둡니다.
CLAUDE.md: Claude Code가 리뷰를 포함한 모든 작업에서 읽는 프로젝트 지침. Code Review는 이를 프로젝트 컨텍스트로 읽고 위반하는 변경을 지적합니다.REVIEW.md: 리뷰 전용 지침. 팀이 무엇을, 어떤 심각도로 지적하길 원하는지, 무엇을 건너뛸지 적습니다.
저장소 루트에 REVIEW.md를 추가해 merge한 뒤 기본 브랜치를 보호하세요. 리뷰의 철저함이나 실행 시점을 바꾸려면 Owner에게 리뷰 수준이나 Review runs 설정 변경을 요청합니다.
핵심 개념
| 파일 | 읽는 쪽 | 용도 |
|---|---|---|
CLAUDE.md |
Code Review 서비스 및 로컬 /code-review |
두 곳 모두에 적용할 지침 |
REVIEW.md |
Code Review 서비스만 (로컬 /code-review는 읽지 않음) |
PR 리뷰 전용 규칙 |
Code Review 서비스와 로컬 /code-review 명령은 별개 도구이며 읽는 파일이 다릅니다. 두 곳에 적용하고 싶은 지침은 CLAUDE.md에 두고 REVIEW.md는 PR 리뷰 전용 규칙에만 쓰세요.
상세
CLAUDE.md로 프로젝트 전체 규칙
Code Review는 저장소의 CLAUDE.md 파일을 프로젝트 컨텍스트로 읽습니다. 규칙을 위반한 변경은 문제에 맞는 심각도의 finding이 됩니다. 리뷰는 저장소 루트의 CLAUDE.md와 변경된 각 파일의 상위 디렉터리에 있는 CLAUDE.md를 읽습니다. 하위 디렉터리의 CLAUDE.md는 PR이 그 경로 아래 파일을 바꿀 때 읽습니다.
REVIEW.md로 리뷰 전용 규칙
REVIEW.md는 저장소 루트에 두는 파일로 Code Review를 저장소에 맞게 조정합니다. 하위 디렉터리에 REVIEW.md를 추가하면 루트 파일 위에 그 경로 아래 변경에 대한 검사가 더해집니다. 문제를 찾는 에이전트와 검증하는 에이전트가 Code Review의 기본 리뷰 지침과 함께 이 내용을 저장소의 리뷰 지침으로 받고, 최종 리뷰를 쓰는 단계도 심각도를 정하고 요약을 쓰기 전에 참조합니다.
your-repo/
├── REVIEW.md # Root file
├── services/
│ └── billing/
│ └── REVIEW.md # Adds checks for changes under services/billing/
└── src/
하위 디렉터리 파일에 의존하기 전에 기본 브랜치를 보호하고 브랜치 설정별로 리뷰가 읽는 것을 확인하세요.
REVIEW.md 예시: 백엔드 서비스의 심각도를 재보정하고, nit 수를 제한하고, 생성 파일을 건너뛰고, 저장소별 검사를 추가합니다.
# Review instructions
## What Important means here
Reserve Important for findings that would break behavior, leak data,
or block a rollback: incorrect logic, unscoped database queries, PII
in logs or error messages, and migrations that aren't backward
compatible. Style, naming, and refactoring suggestions are Nit at
most.
## Cap the nits
Report at most five Nits per review.
## Do not report
- Anything CI already enforces: lint, formatting, type errors
- Generated files under `src/gen/` and any `*.lock` file
- Test-only code that intentionally violates production rules
## Always check
- New API routes have an integration test
- Log lines don't include email addresses, user IDs, or request bodies
- Database queries are scoped to the caller's tenant
REVIEW.md에 무엇을 쓸지: 자유 형식 Markdown이며 리뷰가 찾고 보고하는 것을 바꿀 뿐 리뷰의 형식은 바꾸지 않습니다. 겪는 문제에 맞는 지침을 추가하세요(위 예시는 앞의 네 가지를 사용).
- 엉뚱한 것이 Important로 표시됨: 🔴 Important의 의미를 저장소에 맞게 재정의합니다. 기본 보정은 프로덕션 코드 대상이라 문서/설정 저장소나 프로토타입은 훨씬 좁은 정의가 맞을 수 있습니다. 어떤 종류의 finding이 Important이고 어떤 것이 기껏해야 Nit인지 명시합니다. 예를 들어
CLAUDE.md위반을 모두 Important로 격상할 수도 있습니다. - nit이 너무 많음: 한 리뷰가 게시하는 🟡 Nit 코멘트 수를 제한합니다("report at most five nits").
- 생성 파일이나 CI가 이미 검사하는 것에 코멘트가 달림: Claude가 건너뛸 경로와 finding 카테고리를 나열합니다. 생성 코드, lockfile, vendored 의존성, lint나 spellcheck처럼 CI가 이미 강제하는 것이 흔한 후보입니다. 일부 리뷰는 필요하지만 전면 검토는 아닌 경로는 더 높은 기준을 둡니다: "in
scripts/, only report if near-certain and severe." - 팀 규칙이 검사되지 않음: 모든 PR에서 지적할 규칙을 추가합니다(예: "new API routes must have an integration test").
- 잘못된 finding이 나옴: 특정 종류의 finding을 게시하기 전에 근거를 요구합니다. 예를 들어 "behavior claims need a
file:linecitation in the source, not an inference from naming"은 작성자가 한 번 더 왕복해야 할 오탐을 줄입니다.
이 중 일부 지침은 루트 파일이 보호된 기본 브랜치에 있어야 합니다. REVIEW.md에는 리뷰 동작을 바꾸는 지침만 두고 일반 프로젝트 컨텍스트는 CLAUDE.md에 둡니다.
다른 파일 include: 리뷰 지침을 여러 파일로 나눠 루트 REVIEW.md로 가져올 수 있습니다(REVIEW.md가 길어졌거나 이미 다른 파일에 리뷰 규칙이 있을 때). 루트 REVIEW.md에 @와 파일 이름만 있는 줄을 추가하면 Code Review가 그 줄 자리에 파일 내용을 넣어 REVIEW.md의 일부로 적용합니다.
# Review instructions
Report at most five Nits per review.
@review-security.md
@review-api.md
include되는 파일은 REVIEW.md 옆 저장소 루트에 둡니다.
your-repo/
├── REVIEW.md
├── review-security.md
└── review-api.md
Code Review는 보호된 브랜치에서 REVIEW.md를 읽을 때 파일을 include합니다.
- 보호된 브랜치: include 파일을
@줄 자리에 넣음 - 보호되지 않은 기본 브랜치:
@줄이 일반 텍스트로REVIEW.md에 남음. PR이 그 줄이 가리키는 파일을 변경하면 그 줄은 제외됨
리뷰가 include한 파일을 적용하지 않으면 다음을 확인합니다.
- 위치: 파일을 저장소 루트로 옮김.
@docs/review-rules.md처럼 하위 디렉터리 경로는 include되지 않음 - 이름: 대소문자까지 정확히 일치시키고 공백 없는 이름 사용.
REVIEW.md옆 어느 파일과도 맞지 않는 줄은 일반 텍스트로 남고 check run은 이를 건너뛴 include로 보고하지 않음 - 한 단계: 루트
REVIEW.md에 모든 파일을 나열. include된 파일이나 하위 디렉터리REVIEW.md안의@줄은 일반 텍스트로 남고 다른 파일로의 Markdown 링크는 include가 아님 - 한도: 서로 다른 파일 최대 8개,
REVIEW.md와 include 파일 합계 150,000바이트 미만. 바이트 한도에 도달하는 파일은 일부가 아니라 통째로 건너뜀. check run이 어느 한도로든 건너뛴 include 줄 수를 보고함 - 링크:
REVIEW.md와 include 파일 전체에서 Markdown 링크 64개 이하(http,https,mailto주소와#앵커로의 링크는 미집계). 초과하면 include 파일만이 아니라 루트REVIEW.md전체를 건너뛰며 check run이 지침이 적용되지 않았다고 알림 - merge된 사본: include 파일을
REVIEW.md를 읽는 브랜치에 merge. 리뷰는 둘을 같은 커밋에서 읽으며 PR 자체의 변경에서는 읽지 않음
REVIEW.md를 읽는 브랜치
Code Review는 PR 자체의 변경이 아니라 PR의 base 브랜치 또는 기본 브랜치에서 REVIEW.md를 읽습니다. 리뷰 동작을 바꾸려면 REVIEW.md 변경을 먼저 merge하세요. REVIEW.md는 기본 브랜치에 두고 그 브랜치를 보호합니다. 보호된 기본 브랜치의 사본을 읽을 때(아래 표의 첫 행) 루트 파일에서 다음 지침을 따릅니다: finding 심각도 낮추기, 경로·파일·이슈 종류 제외, nit 코멘트 수 제한.
브랜치 보호로 인정되는 것
- 기본 브랜치: classic branch protection rule 또는 ruleset
- 그 외 브랜치: ruleset만
ruleset은 업데이트를 제한하거나 최소 승인 1개를 요구하는 PR을 요구하면 인정됩니다. PR을 요구한다면 새 push 시 그 승인을 dismiss하거나 마지막 push 이후의 승인을 요구해야 합니다.
브랜치 설정별로 리뷰가 읽는 것
| 브랜치 보호 | 읽는 사본 | 읽는 파일 |
|---|---|---|
| 기본 브랜치가 보호되고 PR이 그것을 대상으로 하거나 어떤 ruleset도 보호하지 않는 브랜치를 대상으로 함 | 기본 브랜치 | 루트 파일, 그것이 include하는 파일, 하위 디렉터리 파일 |
| PR이 ruleset으로 보호되는 다른 브랜치를 대상으로 함 | 그 base 브랜치 | 루트 파일, 그것이 include하는 파일, 하위 디렉터리 파일 |
| 기본 브랜치가 보호되지 않고 base 브랜치에도 어느 종류의 보호 규칙도 없음 | 기본 브랜치 | 루트 파일 |
| Code Review가 보호 설정을 확인할 수 없음(보호되지 않은 기본 브랜치와 classic rule만 있는 base 브랜치 포함) | 없음 | 없음 |
check run이 REVIEW.md를 언급하면 Troubleshoot Code Review의 "The check run mentions REVIEW.md"를 보세요.