클로드 코드 리뷰, 사람이 확인할 지점은? REVIEW.md와 7개 리뷰 레이어

클로드 코드 리뷰에서 사람이 먼저 봐야 할 것은 위험한 변경과 그 변경을 뒷받침하는 검증 증거입니다. 클로드 코드 팀은 코드 읽기의 상당 부분을 AI에 맡기고, 사람의 검토는 변경의 위험도에 맞춰 배치해요. 사람은 설계가 적절한지, 테스트가 변경의 영향을 제대로 확인했는지, 문제가 생겼을 때 되돌릴 수 있는지를 판단하는 데 힘을 씁니다.

처음 접할 때 가장 많이 섞이는 것이 운영 절차와 리뷰 지침입니다. 7개 리뷰 레이어는 PR을 만들기 전부터 배포 후 복구까지 이어지는 검증 절차를 말하고, REVIEW.md는 AI 리뷰가 무엇을 문제로 보고할지 정해 두는 파일이에요. 그래서 파일을 잘 쓰는 일과 안전하게 병합·배포하는 체계를 갖추는 일은 따로 챙겨야 합니다.

7개 레이어는 어떻게 위험을 나눠 맡을까

클로드 코드 팀의 공개 글이 소개한 흐름을 정리하면 아래와 같아요. 레이어를 도구 일곱 개로 읽기보다, 변경 하나가 차례로 통과하는 검증·대응 단계로 보는 편이 정확합니다.

내부 운영 사례를 보면 저위험 변경은 조건을 충족할 때 사람 승인 없이 진행되고, 중위험은 1명, 고위험은 2명의 승인을 요구합니다. 여기서 놓치기 쉬운 부분이 있어요. 완화된 경로는 신뢰된 작성자에게만 적용되고, 민감한 경로에는 추가 조건이 붙습니다. "저위험이면 무조건 자동 병합"으로 받아들이면 바로 이 적용 조건이 빠져 버립니다.

변경을 지시한 사람의 책임은 그대로 남습니다.

이 구조를 들여올 때 저는 승인 인원을 몇 명으로 할지보다, 민감한 경로를 건드리는 변경을 먼저 가려내는 쪽을 권해요. 위험 분류부터 모호하면 승인 인원을 아무리 늘려도 정말 중요한 변경에 검토가 모이지 않기 때문입니다.

REVIEW.md, 어느 브랜치의 파일이 읽힐까

공개 Code Review는 PR에 담긴 변경본이 아니라 기준 브랜치나 기본 브랜치에 있는 REVIEW.md를 읽습니다. 그러니 파일을 새로 추가하는 PR에서 그 규칙이 곧바로 적용되리라 기대하면 결과를 잘못 읽게 돼요. 규칙 문구를 다듬기 전에 서비스가 어느 브랜치의 파일을 읽는지부터 확인하는 게 순서입니다.

1. 리뷰 전용 기준을 REVIEW.md에 작성하고, 서비스가 읽는 브랜치에 병합합니다.
2. 브랜치 보호 설정과 하위 디렉터리 파일·포함 파일의 적용 범위를 확인합니다.
3. 이후 리뷰 결과에 의도한 기준이 반영되는지 살펴봅니다.

읽는 파일의 범위는 브랜치 보호 상태에 따라 달라지고, 보호 설정을 확인하지 못하면 파일을 아예 읽지 않는 경우도 있어요. 정확한 적용 조건은 리뷰 맞춤 설정 공식 문서에서 확인하세요.

규칙을 쓸 때는 코드 취향보다 실제 장애로 이어지는 조건을 앞에 두는 편이 좋습니다. 테넌트 범위를 벗어난 조회, 개인정보가 남는 로그, 롤백을 막는 마이그레이션처럼 발생 조건을 구체적으로 적어 두면 리뷰의 초점이 뚜렷해져요. 자동 검사가 이미 잡아 주는 항목은 정리해서 중복 보고를 줄일 수 있습니다. 역할 분담도 단순하게 가져가면 됩니다. 프로젝트 전반의 공통 지침은 CLAUDE.md에, 보고할 문제와 심각도·제외 대상 같은 리뷰 전용 기준은 REVIEW.md에 두는 식이에요.

공개 서비스와 내부 운영은 무엇이 다를까

공개 Code Review는 변경분과 주변 코드를 읽을 뿐, 코드를 빌드하거나 실행하지 않습니다. PR을 스스로 승인하거나 병합을 막지도 않기 때문에 테스트 실행, 필수 승인, 병합 조건은 별도로 구성해야 해요. 내부 팀에서 보안 리뷰가 병합을 차단한다는 설명을 공개 서비스의 기본 기능으로 오해하기 쉬운 지점이니, 둘은 나눠서 보시길 권합니다.

로컬 /code-review도 헷갈리는 부분입니다. 이쪽은 CLAUDE.md를 따르지만 REVIEW.md는 읽지 않아요. 로컬 리뷰와 PR 리뷰 모두에 필요한 지침이라면, 공통 파일에 들어가야 할 내용이 무엇인지부터 가려 두는 게 좋습니다. 공개 서비스의 실행 범위와 병합 관련 동작은 Code Review 공식 문서에서 확인할 수 있습니다.

AI의 수정과 리뷰를 이어 붙인다면 언제 멈출지도 정해 둬야 합니다. 팀은 한 PR이 밤새 50회 넘게 수정과 리뷰를 반복한 일을 겪은 뒤, 3회 이후에는 접근 방식을 재검토하도록 바꾸고 재리뷰 범위도 줄였어요. 같은 지적이 되풀이된다면 수정 횟수를 늘리기보다 요구사항과 해결 방향을 사람이 다시 판단하도록 설계하는 편이 낫습니다.

기능 설명은 2026년 10월 27일 열람 기준입니다.