Claude Code Review 정식 출시 — REVIEW.md 규칙은 병합된 후에만 적용되며, 나머지는 브랜치 보호 설정이 결정합니다 (2026)

정식 출시 발표에서는 세 가지 변화를 설명합니다. 프리뷰 기간보다 리뷰 속도가 빨라졌습니다. 발견된 문제(Findings)는 문제점, 발생 원인, 해결책을 명시하여 더 간결하게 작성됩니다. 또한 관리자는 이제 저장소별로 리뷰 수준을 선택할 수 있습니다. "관리자는 각 저장소에 대해 Quick, Standard(기본값), Deep 중 하나를 선택할 수 있으므로, 일상적인 코드베이스는 빠르게 훑어보고 가장 중요한 코드베이스는 깊이 있게 리뷰할 수 있습니다."

제품의 기본 구조는 동일합니다. 여러 에이전트가 각 변경 사항을 읽고, 검증 단계에서 발견된 문제를 필터링한 후, 인라인 댓글과 Claude Code Review라는 이름의 체크 런(Check run)으로 결과를 전달합니다. 무엇보다 중요한 두 가지 특징은 다음과 같습니다.

• 병합을 승인하거나 차단하지 않습니다. 문서에 따르면 "리뷰는 풀 리퀘스트를 승인하거나 차단하지 않으므로, 병합 결정은 온전히 팀의 몫으로 남습니다."
• 코드를 실행하지 않고 읽기만 합니다. 리뷰는 "코드를 빌드하거나 실행하지 않고, diff와 주변 코드를 읽는 방식으로 작동합니다." 리뷰 프로세스 내에서 "저장소에 대한 액세스는 읽기 전용이며, 리뷰 과정에서 커밋을 푸시하지 않습니다."

따라서 리뷰어의 판단은 지침 파일을 포함하여 읽은 내용에 전적으로 의존합니다.

Code Review는 저장소에 있는 두 가지 종류의 파일로부터 지침을 받습니다.

CLAUDE.md는 Claude Code가 이미 사용하고 있는 프로젝트 지침 파일입니다. Anthropic은 이를 "Claude Code가 리뷰를 포함한 모든 작업에서 읽는 프로젝트 지침입니다. Code Review는 이를 프로젝트 컨텍스트로 읽고, 이를 위반하는 변경 사항을 찾아냅니다"라고 설명합니다. 리뷰가 저장소의 모든 CLAUDE.md를 읽는 것은 아닙니다. "리뷰는 저장소 루트의 CLAUDE.md와 변경된 각 파일의 상위 디렉터리에 있는 CLAUDE.md 파일을 읽습니다. 하위 디렉터리의 CLAUDE.md는 풀 리퀘스트가 해당 경로 아래의 파일을 변경할 때만 읽힙니다."

REVIEW.md는 Code Review 전용 파일입니다. 이는 "리뷰만을 위한 지침입니다. 팀이 어떤 문제를 어떤 심각도로 표시하고 싶어하는지, 그리고 어떤 것을 건너뛰고 싶어하는지 지정하는 데 사용합니다." 저장소 루트에 하나를 두고, 하위 디렉터리에 추가로 배치하여 해당 경로 아래의 변경 사항에 대한 검사를 추가할 수 있습니다. 이 파일의 내용은 리뷰의 모든 단계에 전달됩니다. "문제를 찾는 에이전트와 이를 검증하는 에이전트는 Code Review의 기본 리뷰 지침과 함께 이 파일의 내용을 저장소의 리뷰 지침으로 전달받습니다. 최종 리뷰를 작성하는 단계에서는 심각도를 결정하고 요약을 작성하기 전에 이 파일을 참조합니다."

Anthropic이 권장하는 구분법은 간단합니다. "REVIEW.md에는 리뷰 동작을 변경하는 지침만 유지하고, 일반적인 프로젝트 컨텍스트는 CLAUDE.md에 남겨두세요." 기본적으로 Code Review는 포맷팅이나 테스트 커버리지보다는 프로덕션 환경을 망가뜨릴 수 있는 버그와 같은 '정확성(Correctness)'에 집중합니다. REVIEW.md를 사용하면 저장소에 맞게 이 기준을 조정할 수 있습니다. 무엇을 '중요(Important)'로 간주할지 재정의하고, nit 코멘트의 개수를 제한하고, 건너뛸 경로를 나열하고, 팀이 중요하게 생각하는 검사를 추가하거나, 특정 종류의 발견 사항에 대해 증거로서 파일과 라인을 요구할 수 있습니다.

Claude Code 팀이 코드 리뷰를 수행하는 방법에 대한 포스팅에서 Anthropic은 다음과 같이 밝혔습니다. "CLAUDE.md는 Claude에게 프로젝트가 무엇인지(스택, 컨벤션, 목표 및 비목표)를 알려줍니다. 모든 리뷰에서 이 파일을 로드하므로, 대규모 코드베이스에서는 이 파일을 짧게 유지하고 다른 문서로 링크를 연결합니다." 그리고 "코드 소유자가 작성하는 REVIEW.md는 리뷰어에게 코드의 해당 부분에서 무엇이 중요한지 알려줍니다. 우리는 리뷰어가 실제로 이를 따르는지 별도로 확인합니다."

Anthropic은 이 파일이 무조건 준수된다고 가정하지 않습니다. 아래 규칙들은 여러분이 작성한 규칙이 왜 적용되지 않을 수 있는지 설명합니다.

공식 문서는 명확하게 밝히고 있습니다. "Code Review는 풀 리퀘스트의 베이스 브랜치 또는 기본 브랜치에서 REVIEW.md를 읽으며, 풀 리퀘스트 자체의 변경 사항에서는 절대 읽지 않습니다. 리뷰 동작을 변경하려면 먼저 REVIEW.md 변경 사항을 병합해야 합니다."

실제 개발 과정에서 흔히 발생하는 상황이 있습니다. 개발자가 리뷰어가 자동 생성된 파일을 지적하는 것을 보고, 해당 코멘트를 유발한 동일한 풀 리퀘스트의 REVIEW.md에 건너뛰기 규칙을 추가한 뒤 푸시합니다. 하지만 다음 리뷰는 여전히 새 규칙이 반영되지 않은 베이스 브랜치 또는 기본 브랜치의 REVIEW.md 복사본을 기준으로 실행됩니다. 따라서 변경 사항이 병합될 때까지 코멘트는 계속해서 나타납니다.

마찬가지로, REVIEW.md를 처음 도입하는 풀 리퀘스트 자체는 이 파일 없이 리뷰를 받게 됩니다.

문서에서는 이유를 설명하지 않고 규칙만 제시하고 있습니다. 이 규칙의 효과는 풀 리퀘스트에서 REVIEW.md를 직접 수정하여 발견된 문제의 심각도를 낮추거나 자신이 변경한 파일을 검사에서 제외할 수 없도록 만드는 것입니다. 이 결정 권한은 리뷰가 읽는 브랜치로의 병합을 제어하는 사람에게 유지됩니다.

실제적인 결론은 다음과 같습니다. REVIEW.md 변경 사항은 영향을 미치고자 하는 작업보다 먼저 병합되는 별도의 작은 풀 리퀘스트로 처리하십시오.

REVIEW.md를 병합하는 것이 끝이 아닙니다. Code Review는 읽어오는 브랜치가 보호되고 있는지 확인하며, 그 결과에 따라 읽는 내용과 준수하는 범위가 달라집니다.

Anthropic의 가이드는 "기본 브랜치에 REVIEW.md를 유지하고 해당 브랜치를 보호하십시오"라고 권장합니다. 리뷰가 보호된 기본 브랜치의 복사본을 읽을 때, 루트 파일에서 다음과 같은 세 가지 종류의 지침을 준수합니다.

• 발견된 문제의 심각도 낮추기
• 경로, 파일 또는 특정 범주의 문제 제외하기
• nit 코멘트 개수 제한하기

이 세 가지는 문서에서 애초에 작성하도록 제안하는 다섯 가지 지침 중 세 가지에 해당합니다. 락파일을 무시하고 nit 코멘트를 소수로 제한하라는 REVIEW.md 지침이 효과를 발휘하려면 브랜치 보호 설정이 필수적입니다.

문서에서는 네 가지 상황을 제시합니다.

두 개의 행을 주목할 필요가 있습니다. 세 번째 행에서는 하위 디렉터리의 REVIEW.md 파일을 전혀 읽지 않으므로 디렉터리별 검사가 누락됩니다. 네 번째 행에서는 REVIEW.md를 전혀 읽지 않습니다. 문서에서는 이 경우가 "클래식 규칙만 있는 베이스 브랜치와 보호되지 않은 기본 브랜치"를 포함한다고 명시하고 있습니다.

보호로 인정되는 기준도 구체적입니다. 기본 브랜치의 경우, Code Review는 "클래식 브랜치 보호 규칙 또는 규칙 세트(ruleset)"를 허용합니다. 다른 브랜치의 경우 "규칙 세트만" 인정됩니다. 또한 모든 규칙 세트가 인정되는 것은 아닙니다. "업데이트를 제한하거나 최소 1개 이상의 승인이 있는 풀 리퀘스트를 요구하는 규칙 세트여야 합니다. 풀 리퀘스트를 요구하는 경우, 새로운 푸시가 발생했을 때 해당 승인을 반려하거나 마지막 푸시 이후에 승인이 이루어지도록 요구해야 합니다."

체크 런을 통해 이 상황이 발생하고 있는지 확인할 수 있습니다. 한 메시지에는 "이 리뷰는 직접 푸시로부터 보호되지 않는 기본 브랜치의 저장소 리뷰 지침(REVIEW.md)을 적용했습니다"라고 표시됩니다. 이는 루트 파일만 읽혔음을 의미합니다. 다른 메시지에는 지침이 "이 리뷰에 적용되지 않았습니다: 브랜치 보호 설정을 확인할 수 없습니다"라고 표시되며, 이는 아무것도 적용되지 않았음을 의미합니다.

Code Review에는 자체 세션에서 실행되는 형제 도구가 있습니다. 문서에서는 이 차이점을 직접적으로 언급합니다. "Code Review 서비스와 로컬 /code-review 명령은 서로 다른 두 개의 도구이며, 서로 다른 파일을 읽습니다."

서비스는 CLAUDE.md와 REVIEW.md를 모두 읽습니다. 반면 로컬 명령은 비대화형 -p 실행을 포함하여 CLAUDE.md만 따릅니다. "REVIEW.md는 읽지 않습니다."

이는 규칙을 작성하는 방식에 영향을 미칩니다. REVIEW.md에만 존재하는 검사는 풀 리퀘스트 리뷰에는 나타나지만, 개발자가 풀 리퀘스트를 열기 전에 로컬에서 /code-review를 실행할 때는 나타나지 않습니다. Anthropic의 조언은 다음과 같습니다. "두 곳 모두에 적용하고 싶은 지침은 CLAUDE.md에 넣고, REVIEW.md는 풀 리퀘스트 리뷰에 특화된 규칙을 위해 남겨두세요."

푸시하기 전에 로컬에서 리뷰를 수행하는 개발자는 겹치면서도 서로 다른 지침을 바탕으로 작동하는 두 개의 리뷰어를 보게 될 것입니다.

새로운 REVIEW.md가 푸시되자마자 작동할 것이라고 가정하는 것. 이 파일은 Code Review가 읽는 브랜치에 병합된 후에 작동하며, 해당 브랜치가 보호될 때만 온전히 작동합니다. Our guide to why agents ignore your instruction files에서는 코딩 세션에서 발생하는 유사한 격차를 다룹니다.

답변(Reply)을 통해 리뷰어를 학습시킬 수 있다고 가정하는 것. 발견된 문제에 답변하는 것은 해당 풀 리퀘스트의 다음 리뷰와의 대화일 뿐, 영구적인 규칙이 되지 않습니다. "답변하는 것만으로는 발견된 문제가 해결(dismiss)되지 않습니다." 다음 리뷰는 "이전 발견 사항에 대한 답변을 읽고, 스레드를 해결하거나 하나의 후속 답변을 게시할 수 있습니다." 계속해서 반복되는 발견 사항에 대한 문서의 조언은 "메인테이너에게 REVIEW.md에 규칙을 추가하도록 요청하는 것"입니다.

CLAUDE.md가 코딩 세션만을 위한 것이라고 가정하는 것. Code Review는 이를 프로젝트 컨텍스트로 읽고 위반 사항을 표시합니다. Anthropic 팀은 자체 리뷰어가 "이 파일의 컨벤션을 위반하는 코드와 이 파일의 내용을 구식으로 만드는 변경 사항도 표시한다"고 언급했습니다. 리뷰어가 CLAUDE.md를 읽기 시작하면, 세션뿐만 아니라 리뷰를 위해서도 이 파일을 최신 상태로 유지하는 것이 중요해집니다. Our guide to conflicting CLAUDE.md layers에서 이를 찾아 해결하는 방법을 다룹니다.

1단계: 기본 브랜치 보호 및 읽는 복사본 확인

위의 표를 참고하여 브랜치 보호 설정을 확인하십시오. 기본 브랜치에 클래식 규칙 또는 규칙 세트를 부여하십시오. 풀 리퀘스트가 다른 장기 보존 브랜치를 대상으로 하는 경우, 해당 브랜치들의 REVIEW.md 복사본이 적용되려면 규칙 세트가 필요합니다.

그런 다음 작은 테스트용 풀 리퀘스트를 열고 체크 런을 확인하십시오. 보호되지 않은 브랜치에서 지침을 가져왔거나 적용되지 않았다고 표시되면 이 문제부터 해결하십시오.

2단계: CLAUDE.md와 REVIEW.md 간에 규칙 분리

적용하려는 규칙을 검토하고 다음과 같이 분류하십시오.

• 프로젝트 자체에 대한 규칙은 CLAUDE.md에 넣습니다: 컨벤션, 아키텍처 경계, 변경 사항이 지향하지 않아야 할 비목표 등. 이 규칙들은 코딩 세션, 로컬 리뷰, 풀 리퀘스트 리뷰 모두에 적용됩니다.
• 리뷰에 대한 규칙은 REVIEW.md에 넣습니다: 이 저장소에서 무엇을 '중요'로 간주할지, 몇 개의 nit 코멘트를 게시할지, 어떤 경로를 건너뛸지, 항상 실행할 검사는 무엇인지 등.
• 코드의 특정 영역에 대한 규칙은 하위 디렉터리의 CLAUDE.md 또는 REVIEW.md에 넣습니다. 하위 디렉터리의 REVIEW.md 파일은 브랜치 보호 설정에 의존합니다.

REVIEW.md 변경 사항은 단독으로 병합하십시오. CLAUDE.md 규칙을 처음 작성하는 경우, our guide to making Claude stick to your coding style에서 컨벤션을 준수하도록 표현하는 방법을 다룹니다.

3단계: 반복되는 발견 사항을 병합된 규칙으로 전환하고, 이유 기록하기

Anthropic 자체의 프로세스가 좋은 모델입니다. 팀은 "자동 리뷰어가 계속해서 같은 문제를 지적할 때, 우리는 소스에서 이를 해결합니다"라고 씁니다. 그들이 권장하는 도입 방식은 하나의 저장소에 AI 리뷰어를 추가하고, "몇 주 동안 REVIEW.md를 조정한 다음 대상을 넓히는 것"입니다. 그리고 리뷰가 무언가를 놓쳤을 때는 "모델 앞에 무엇이 없었는지 묻고 CLAUDE.md, 스킬 또는 새로운 검사에 해결책을 넣습니다."

이러한 각 해결책은 하나의 결정입니다. 왜 특정 경로가 제외되었는지, 왜 특정 범주의 발견 사항이 여기서는 '중요'하고 다른 곳에서는 'Nit'인지, 어떤 장애로 인해 검사가 추가되었는지 등입니다. 규칙은 파일에 들어갑니다. 그 이유 역시 보존할 가치가 있습니다. 다음에 REVIEW.md를 수정하는 사람이 해당 규칙이 여전히 유효한지 알아야 하기 때문입니다. Our guide to Claude Code forgetting your corrections에서는 코딩 세션에 대한 동일한 패턴을 다룹니다. 가장 중요한 수정 사항은 팀 전체가 읽을 수 있는 파일에 속해야 합니다.

REVIEW.md는 규칙을 담고 있습니다. 하지만 장애 상황, 토론, 기각된 대안과 같은 규칙 뒤에 숨겨진 히스토리는 풀 리퀘스트 스레드, 채팅, 누군가의 기억 등 해당 논의가 일어난 곳에 남아 있습니다. MemoryLake는 이러한 의사결정 기록을 직접 관리하는 하나의 목록으로 유지하여, Claude Code 및 코드를 작성하는 동안 연결하는 다른 어시스턴트들이 나중에 리뷰어가 읽을 코드를 작성할 때 사용할 수 있도록 돕는 메모리 레이어입니다.

항목은 본인의 언어로 직접 작성합니다. 저장소의 CLAUDE.md 또는 REVIEW.md 파일, 풀 리퀘스트, Code Review의 발견 사항 또는 타사 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. Code Review 서비스는 저장소에 있는 내용만 읽으므로 적용되는 규칙은 여전히 해당 파일에 있어야 합니다. 저장소 외부의 공간에 프로젝트 세부 정보를 저장하기 전에 조직의 정책을 확인하십시오.

1단계: API 키 생성

로그인하고 대시보드에서 키를 생성합니다. 이 키는 MemoryLake 워크스페이스에 속하며 Anthropic 및 GitHub 계정과는 별개입니다.

2단계: 첫 번째 메모리 업로드

리뷰 규칙 뒤에 숨겨진 이유부터 시작하십시오. 왜 특정 경로를 건너뛰는지, 왜 특정 발견 범주가 이 저장소에서 '중요'한지, 어떤 장애로 인해 검사가 추가되었는지 등입니다. 항목당 하나의 결정을 날짜와 함께 기록하고, 그것이 설명하는 규칙을 가리키는 포인터를 포함합니다.

3단계: AI 및 에이전트 연결

Claude Code 및 사용하는 다른 어시스턴트를 연결합니다. 그러면 풀 리퀘스트가 리뷰어에게 도달하기 전에 코드를 작성하는 동안 규칙 뒤에 숨겨진 배경 맥락을 활용할 수 있습니다.

첫 번째 변화는 체크 런에서 예상치 못한 결과가 줄어든다는 점입니다. 브랜치 보호가 확인되면 작성한 제외 규칙과 nit 제한이 적용됩니다. 두 번째는 일관성입니다. 모든 곳에 적용되어야 하는 규칙이 CLAUDE.md에 위치하므로, 로컬 /code-review와 풀 리퀘스트 리뷰가 동일한 기준을 기대하게 됩니다. 세 번째는 목적에 맞게 개선되는 구조로, 반복되는 발견 사항이 이유가 기록된 규칙으로 전환됩니다. Our look at what coding agents actually read에서는 이러한 기록된 컨텍스트가 도구 전반에서 왜 중요한지 다룹니다.

REVIEW.md 변경 사항은 단독으로 병합하십시오. 풀 리퀘스트는 베이스 브랜치의 복사본을 기준으로 리뷰됩니다.

기본 브랜치를 보호하십시오. 심각도 변경, 제외 규칙, nit 제한은 브랜치 보호에 의존합니다.

체크 런 메시지를 읽으십시오. 루트 파일만 읽혔거나 아무것도 읽히지 않았을 때 메시지가 이를 알려줍니다.

공유 규칙은 CLAUDE.md에 넣으십시오. 로컬 명령은 REVIEW.md를 읽지 않습니다.

두 파일 모두 짧게 유지하십시오. 리뷰 파일에 대한 Anthropic 자체의 평가는 다음과 같습니다. "좋은 파일은 짧습니다."

Code Review의 정식 출시(GA)로 모든 풀 리퀘스트에 대한 AI 리뷰가 Team 및 Enterprise 조직의 기본 옵션이 되었습니다. 리뷰의 기준이 되는 것은 여전히 팀의 몫입니다. REVIEW.md는 풀 리퀘스트 자체의 변경 사항이 아닌 베이스 또는 기본 브랜치에서 읽힙니다. 브랜치 보호 설정은 하위 디렉터리 파일의 반영 여부와 심각도 변경, 제외 규칙, nit 제한의 준수 여부를 결정합니다. 보호 설정을 확인할 수 없는 경우 REVIEW.md를 읽지 않습니다. 브랜치를 보호하고, 프로젝트 규칙과 리뷰 규칙을 분리하며, 반복되는 발견 사항을 이유와 함께 병합된 규칙으로 전환하십시오.