Code Review 사용자 지정

REVIEW.md와 CLAUDE.md로 Code Review가 풀 리퀘스트에서 지적하는 항목을 조정합니다. 심각도를 재조정하고, 경로를 건너뛰고, 검사를 추가하고, 어떤 사본이 적용되는지 확인합니다.

저장소에 지침을 커밋하여 Code Review가 해당 저장소에서 지적하는 항목을 변경할 수 있습니다. 이 방법으로 nit 수를 줄이거나, 생성된 파일에 대한 코멘트를 중단하거나, 팀이 중요하게 여기는 규칙을 추가할 수 있습니다. 지침은 다음 두 파일 중 하나에 작성합니다.

• CLAUDE.md: Claude Code가 리뷰를 포함한 모든 작업에서 읽는 프로젝트 지침입니다. Code Review는 이를 프로젝트 컨텍스트로 읽고, 이를 위반하는 변경 사항을 지적합니다.
• REVIEW.md: 리뷰 전용 지침입니다. 팀이 무엇을 지적하기를 원하는지, 어떤 심각도로 지적할지, 무엇을 건너뛸지 명시하는 데 사용합니다.

저장소 루트에 REVIEW.md를 추가하고 병합합니다. 그런 다음 기본 브랜치를 보호합니다.

[!NOTE]

리뷰의 철저함이나 리뷰 실행 시점을 변경하려면 Owner에게 리뷰 수준 또는 Review runs 설정을 변경하도록 요청합니다.

프로젝트 전체 규칙에는 CLAUDE.md 사용

Code Review는 저장소의 CLAUDE.md 파일을 프로젝트 컨텍스트로 읽습니다. 이 파일의 규칙 중 하나를 위반하는 변경 사항은 문제에 맞는 심각도 수준의 발견 사항이 됩니다.

리뷰는 저장소 루트의 CLAUDE.md와 변경된 각 파일의 상위 디렉터리에 있는 CLAUDE.md 파일을 읽습니다. 하위 디렉터리의 CLAUDE.md는 풀 리퀘스트가 해당 경로 아래의 파일을 변경할 때 읽힙니다.

리뷰 전용 규칙에는 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/

하위 디렉터리 파일에 의존하기 전에 기본 브랜치를 보호하고 브랜치 구성별로 리뷰가 읽는 항목을 확인합니다.

[!NOTE]

Code Review 서비스와 로컬 /code-review 명령은 서로 별개의 도구이며, 읽는 파일도 다릅니다. 서비스는 CLAUDE.md와 REVIEW.md를 모두 읽습니다. 사용자의 로컬 머신에서 Claude Code 세션 안에서 실행하는 /code-review 명령은 CLAUDE.md 파일을 읽지만 REVIEW.md는 읽지 않습니다. 두 곳 모두에 적용하려는 지침은 CLAUDE.md에 작성하고, REVIEW.md에는 풀 리퀘스트 리뷰에 특화된 규칙만 둡니다.

REVIEW.md 예시

이 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에 작성할 내용 선택

REVIEW.md는 리뷰가 찾아내고 보고하는 내용을 변경하는 자유 형식 Markdown입니다. 리뷰의 형식은 변경하지 않습니다. 겪고 있는 문제를 찾은 다음 제시된 것과 같은 지침을 추가합니다. 예시는 처음 네 가지를 사용합니다.

• 잘못된 항목이 Important로 표시됨: 저장소에 맞게 🔴 Important의 의미를 재정의합니다. 기본 보정은 프로덕션 코드를 대상으로 하며, 문서 저장소, 구성 저장소 또는 프로토타입에는 훨씬 좁은 정의가 적합할 수 있습니다. 어떤 유형의 발견 사항이 Important이고 어떤 유형이 최대 Nit인지 명시합니다. 예를 들어 모든 CLAUDE.md 위반을 Important로 취급하는 식으로 상향 조정할 수도 있습니다.
• nit이 너무 많음: 단일 리뷰가 게시하는 🟡 Nit 코멘트 수를 제한합니다. "nit은 최대 5개까지만 보고"와 같은 제한을 두면 리뷰를 실행 가능한 상태로 유지할 수 있습니다.
• 생성된 파일이나 CI가 이미 검사하는 항목에 대한 코멘트: Claude가 발견 사항을 건너뛰어야 하는 경로와 발견 사항 범주를 나열합니다. 일반적인 대상은 생성된 코드, lockfile, vendored 의존성이며, 린팅이나 맞춤법 검사처럼 CI가 이미 강제하는 모든 항목도 포함됩니다. 어느 정도 리뷰는 필요하지만 전면적인 검토는 필요하지 않은 경로에는 대신 더 높은 기준을 설정합니다: "scripts/에서는 거의 확실하고 심각한 경우에만 보고."
• 팀 규칙이 검사되지 않음: "새 API 라우트에는 통합 테스트가 있어야 함"처럼 모든 풀 리퀘스트에서 지적하려는 규칙을 추가합니다.
• 잘못된 것으로 판명되는 발견 사항: 특정 유형의 발견 사항을 게시하기 전에 근거를 요구합니다. 예를 들어 "동작에 관한 주장에는 이름에서 추론한 것이 아닌 소스의 file:line 인용이 필요함"과 같은 지침은 작성자에게 불필요한 왕복을 초래할 수 있는 오탐을 줄입니다.

이러한 지침 중 일부는 보호된 기본 브랜치에 루트 파일이 있어야 합니다.

REVIEW.md에는 리뷰 동작을 변경하는 지침만 두고, 일반적인 프로젝트 컨텍스트는 CLAUDE.md에 둡니다.

REVIEW.md에 다른 파일 포함하기

리뷰 지침을 여러 파일로 나누고 루트 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

포함할 파일은 저장소 루트에 REVIEW.md와 나란히 저장합니다.

your-repo/
├── REVIEW.md
├── review-security.md
└── review-api.md

Code Review는 보호된 브랜치에서 REVIEW.md를 읽을 때 파일을 포함하므로, 저장소에서 리뷰가 읽는 브랜치를 확인합니다.

• 보호된 브랜치: Code Review가 @ 줄 자리에 포함된 파일을 넣습니다
• 보호되지 않은 기본 브랜치: @ 줄은 REVIEW.md에 일반 텍스트로 남습니다. 풀 리퀘스트가 해당 줄이 지정하는 파일을 변경하면 그 줄은 제외됩니다.

리뷰가 포함된 파일을 적용하지 않으면 다음 항목을 각각 확인합니다.

• 위치: 파일을 저장소 루트로 옮깁니다. 스킬 파일을 제외하고, @docs/review-rules.md처럼 하위 디렉터리를 가리키는 경로는 포함되지 않습니다.
• 이름: 대소문자를 포함하여 파일 이름을 정확히 일치시키고, 공백이 없는 이름을 사용합니다. 이름이 REVIEW.md 옆의 어떤 파일과도 일치하지 않는 줄은 REVIEW.md에 일반 텍스트로 남으며, check run은 이를 건너뛴 포함 항목으로 보고하지 않습니다.
• 한 단계만: 모든 파일을 루트 REVIEW.md에 나열합니다. 포함된 파일이나 하위 디렉터리 REVIEW.md에 있는 @ 줄은 일반 텍스트로 남으며(스킬 파일은 다릅니다), 다른 파일에 대한 Markdown 링크는 포함으로 처리되지 않습니다.
• 제한: 서로 다른 파일은 최대 8개까지 포함하고, REVIEW.md와 포함된 파일의 합계를 150,000바이트 미만으로 유지합니다. 바이트 제한에 도달하게 되는 파일은 잘리지 않고 통째로 건너뜁니다. check run은 두 제한 중 하나로 인해 건너뛴 포함 줄의 수를 보고합니다.
• 링크: REVIEW.md와 포함된 파일 전체에서 Markdown 링크를 64개 이하로 유지합니다. http, https, mailto 주소 및 # 앵커에 대한 링크는 개수에 포함되지 않으며, 스킬 파일의 링크도 포함되지 않습니다. 이 제한을 넘으면 리뷰는 포함된 파일뿐 아니라 루트 REVIEW.md 전체를 건너뜁니다. 그러면 check run은 지침이 적용되지 않았다고 알립니다.
• 병합된 사본: 포함할 파일을 REVIEW.md를 읽는 브랜치에 병합합니다. 리뷰는 두 파일을 모두 같은 커밋에서 읽으며, 풀 리퀘스트 자체의 변경 사항에서는 절대 읽지 않습니다.

스킬 파일 포함하기

스킬에 보관한 지침을 리뷰가 따르도록 하려면 루트 REVIEW.md에 해당 스킬의 SKILL.md를 포함합니다. Code Review는 스킬을 실행하지 않습니다.

@와 SKILL.md의 경로를 .claude/skills/<folder>/SKILL.md 형식으로 별도의 줄에 추가합니다.

# Review instructions

Report at most five Nits per review.

@.claude/skills/api-review/SKILL.md

Treat any change under `migrations/` as Important.

Code Review는 보호된 브랜치에서 REVIEW.md를 읽을 때만 스킬 파일을 포함하므로, REVIEW.md를 읽는 브랜치를 보호합니다. 스킬 파일은 8개 파일 및 150,000바이트 제한에 포함되며, 자체적으로 30,000바이트 제한이 있습니다.

Code Review가 포함하는 스킬 줄 작성하기

공백이 없는 폴더 이름을 사용합니다. 경로에 공백이 있는 줄은 REVIEW.md에 일반 텍스트로 남으며, check run은 이를 건너뛴 포함 항목으로 보고하지 않습니다.

스킬의 @ 줄이 아래 규칙 중 하나를 위반하면 Code Review는 해당 줄에서 스킬을 포함하지 않습니다.

• 경로: 저장소 루트를 기준으로 .claude/skills/<folder>/SKILL.md 형식으로 경로를 작성하며, 스킬 폴더는 skills/ 바로 아래에 있어야 합니다. 루트의 파일 이름과 달리, 이 형식의 경로가 어떤 파일과도 일치하지 않으면 건너뛰고 개수에 집계됩니다.
• 소스: .claude/ 아래의 다른 파일이나 번들, 개인 또는 플러그인 스킬의 지침은 REVIEW.md 옆의 파일로 복사합니다. 이러한 파일은 직접 포함할 수 없습니다.
• 파일: SKILL.md를 일반 텍스트 파일로 커밋합니다. Code Review는 링크가 파일 자체이든 경로상의 폴더이든 심볼릭 링크를 따라가지 않습니다.
• 크기: frontmatter를 포함하여 SKILL.md를 30,000바이트 이하로 유지합니다
• 개수: 스킬 줄은 최대 8개까지 작성합니다. 반복된 줄도 8개에 다시 집계됩니다.
• REVIEW.md의 블록: @ 줄을 코드 펜스 밖에 둡니다. 그 위에 있는 모든 HTML 주석과 모든 <pre>, <script>, <style>, <textarea> 블록을 닫습니다.

Code Review가 파일, 크기, 개수 또는 블록 규칙 위반으로 스킬 줄을 건너뛰면 check run의 건너뛴 포함 줄에 대한 메시지에 집계됩니다. 이 메시지는 리뷰가 보호된 브랜치의 REVIEW.md를 적용할 때만 표시됩니다.

리뷰가 스킬에서 가져오는 내용 확인하기

스킬이 포함되면 리뷰는 SKILL.md의 본문만 가져오고 스킬의 다른 내용은 가져오지 않으므로, 아래 목록을 기준으로 스킬을 확인합니다.

• Frontmatter: 리뷰에 필요한 frontmatter의 내용을 본문에 반복해서 작성합니다. 예를 들어 description에 명시된 스킬 사용 조건이 이에 해당합니다
• 주입된 명령: ! 명령이 제공할 내용을 직접 작성합니다. Code Review는 명령을 실행하지 않으며, 명령이 있는 줄이나 블록 전체를 플레이스홀더로 대체합니다.
• 치환: $ARGUMENTS 및 기타 치환을 고정된 텍스트로 바꿉니다. 리뷰는 인수를 전달하지 않으며 이를 작성된 그대로 남기기 때문입니다
• 지원 파일: 리뷰에 필요한 내용을 SKILL.md로 복사합니다. Code Review는 스크립트, 링크된 파일 또는 @file 참조를 로드하지 않기 때문입니다
• 제외 및 Nit 제한: 발견 사항을 제외하거나 Nit 수를 제한하는 지침은 스킬이 아닌 REVIEW.md 또는 그 옆의 파일에 작성합니다. Code Review는 스킬의 텍스트를 두 가지 중 어느 것의 근거로도 인정하지 않습니다.
• 저장소 파일에 대한 링크: 링크나 @file 참조가 가리키는 내용을 말로 설명합니다. 리뷰는 경로를 일반 텍스트 또는 플레이스홀더로 봅니다.

스킬의 ! 명령, $ARGUMENTS 또는 링크를 편집하면 Claude Code에서 스킬이 작동하는 방식도 바뀝니다. 팀이 이러한 기능에 의존한다면 지침을 REVIEW.md 옆의 파일로 복사하고 스킬 대신 그 파일을 포함합니다.

Code Review가 스킬 텍스트에서 변경하는 문자

Code Review는 스킬 텍스트의 일부 문자를 변경하므로, 코드 샘플은 아래와 같은 형태로 리뷰에 전달됩니다.

In SKILL.md:       Use `items[0]`, never `List<String>`.
The review reads:  Use ˋitems(0)ˋ, never ˋList< String>ˋ.

In SKILL.md:       Run `ps | grep api` and ask @alice.
The review reads:  Run ˋps ¦ grep apiˋ and ask @ alice.

규칙이 이러한 문자 중 하나에 의존하는 경우 말로도 설명합니다.

REVIEW.md를 읽는 브랜치

Code Review는 풀 리퀘스트의 기본(base) 브랜치 또는 기본(default) 브랜치에서 REVIEW.md를 읽으며, 풀 리퀘스트 자체의 변경 사항에서는 절대 읽지 않습니다. 리뷰 동작을 변경하려면 REVIEW.md 변경 사항을 먼저 병합합니다.

REVIEW.md를 기본 브랜치에 두고 해당 브랜치를 보호합니다. 아래 표의 첫 번째 행처럼 리뷰가 보호된 기본 브랜치의 사본을 읽는 경우, 루트 파일의 다음 지침을 따릅니다.

• 발견 사항의 심각도 낮추기
• 경로, 파일 또는 문제 유형 제외
• nit 코멘트 수 제한

제외 및 Nit 제한은 포함된 스킬이 아닌 REVIEW.md 또는 그 옆의 파일에 작성합니다.

브랜치 보호로 인정되는 항목

Code Review는 다음 설정을 보호로 인정합니다.

• 기본 브랜치: 클래식 브랜치 보호 규칙 또는 ruleset
• 그 외 모든 브랜치: ruleset만 해당

ruleset은 업데이트를 제한하거나 최소 한 번의 승인이 있는 풀 리퀘스트를 요구하는 경우 보호로 인정됩니다. 풀 리퀘스트를 요구하는 경우에는 새 푸시 시 해당 승인을 무효화하거나 마지막 푸시 이후에 승인이 이루어지도록 요구해야 합니다.

브랜치 구성별로 리뷰가 읽는 항목

아래 표의 첫 번째 열에서 저장소의 상황을 찾습니다.

check run에 REVIEW.md가 언급되는 경우 The check run mentions REVIEW.md를 참조합니다.

관련 리소스

• Code Review: 서비스의 개요와 리뷰 실행 방식
• 풀 리퀘스트에서 리뷰 읽기 및 요청: 각 심각도 수준의 의미와 발견 사항이 표시되는 방식
• Code Review 설정: Owner가 설정하는 리뷰 수준과 리뷰 실행 시점
• /code-review로 로컬에서 리뷰: /code-review 명령, 인수 및 effort 수준
• 메모리: Claude Code 전반에서 CLAUDE.md 파일이 작동하는 방식