Claude Code 팀은 리뷰를 없애지 않고 옮겼다 — 위험도별 승인, 리뷰 3회 제한, REVIEW.md

Anthropic의 Claude Code 팀이 에이전트가 쏟아내는 PR을 어떻게 리뷰하는지 공개한 글이에요. 결론부터 말하면 리뷰를 없애지는 않았습니다. 사람이 쓰는 시간을 줄이는 쪽으로 리뷰 구조를 다시 짰어요.

• 리뷰 목표가 바뀌었어요. "사람이 코드를 읽었나"를 묻는 대신 "이 변경에서 뭐가 잘못될 수 있고, 그걸 잡을 검사는 무엇인가"를 묻습니다. 대부분의 PR은 사람 한 명(작성자 본인이어도 됨)만 거쳐 머지하는 게 목표예요. 롤백(revert)률과 장애율이 오르지 않는 것이 조건입니다.
• 여러 겹으로 걸러요. PR을 열기 전에 Claude가 테스트를 돌려 스스로 검증합니다. 그다음 AI 리뷰, 보안 리뷰, CI, 위험도에 따른 사람 승인, 머지 큐, 기능 플래그, 단계적 배포, 빠른 롤백이 차례로 붙어요. 위험도는 작성자가 아니라 변경 내용으로 정합니다. 문서 수정은 사람 승인 없이, 결제·자동 업데이트처럼 민감한 코드는 1~2명이 승인해요.
• 리뷰어 AI도 계속 고쳐요. 과거에 장애를 낸 PR들을 평가 세트로 만들어 리뷰어를 매일 돌립니다. 하룻밤 사이 리뷰와 수정이 50번 넘게 오간 PR도 있었대요. 그래서 리뷰 횟수를 3회로 제한하고, 몇 차례 뒤부터는 새로 바뀐 부분만 다시 보게 했습니다. 그 결과 한 번에 통과하는 PR이 65%에서 78%로 늘었어요.

기사에서는 6월부터 9월까지 머지된 PR이 두 배 넘게 늘었는데도 롤백 비율은 40% 넘게 줄었다고 합니다. 모두 Anthropic이 직접 잰 수치예요. 사람이 맡는 일은 "이걸 만들어야 하나" 같은 방향 판단, 위험한 코드, 아키텍처, 그리고 결과에 대한 책임("머지했으면 네가 책임진다")으로 좁혀졌습니다.

출처: How the Claude Code team does code review

에이전트끼리 서로 일감을 계속 만들어 줬기 때문이에요. 기사에서는 작성자도 에이전트, 리뷰어도 에이전트면 끝없이 서로를 바쁘게 할 수 있다고 설명합니다. 그 PR도 밤새 리뷰와 수정을 50번 넘게 주고받다가 작성자가 직접 멈췄대요.

원인은 세 가지로 정리돼요.

• 매번 새 버그가 아니라 묵은 버그를 찾았어요. 리뷰어가 계속 지적한 코드를 git blame으로 추적해 보니 약 59%가 첫 리뷰 때부터 있던 코드였습니다. 매 라운드 오래된 문제를 몇 개씩 더 찾아낸 셈이에요.
• 에이전트는 사소한 지적도 넘기지 않아요. 사람은 사소한 지적(nit)을 몇 초 만에 무시합니다. 에이전트는 그걸 고치고, 그러면 커밋이 하나 더 생기고 리뷰도 한 번 더 돕니다.
• 팀의 습관도 한몫했어요. 리뷰를 돌릴 때마다 뭔가 하나씩 나오니까 여러 번 돌리는 게 기본이 돼 있었대요. 위험한 변경이라면 그럴 만하지만, 모든 PR에 필요한 건 아니었습니다.

그래서 이렇게 바꿨어요. 리뷰를 3번 돌고도 안 끝나면 리뷰어가 접근 방식을 다시 생각해 보라고 권합니다. 몇 번 돈 뒤로는 새로 바뀐 부분만 다시 보고, 이미 단 지적은 반복하지 않아요. 한 줄만 짚는 대신 같은 종류의 버그를 한꺼번에 알려서 전부 고치게 합니다.

그 결과 리뷰를 5번 넘게 도는 PR이 8.9%에서 1.5%로, 통과까지 평균 리뷰 횟수가 2.08회에서 1.32회로 줄었어요. 모두 Anthropic이 사내에서 잰 수치입니다.

출처: How the Claude Code team does code review

기사에서는 "좋은 REVIEW.md는 짧다"는 게 핵심이에요. 코드 오너가 직접 쓰고, 담는 내용은 대략 다섯 가지입니다.

• 이 저장소에서 '실패'가 뭔지. 문서라면 "사실과 다른 내용", 설정이라면 "엉뚱한 곳으로 연결되는 것"처럼 적습니다.
• 사소한 지적(nit) 개수 제한
• 리뷰하지 않을 경로 목록
• 증거 요구. 이름만 보고 짐작하지 말고 파일과 줄 번호를 대라고 적습니다.
• 요약 형식. 지적 개수로 시작하고, 고칠 게 없으면 없다고 분명히 말하게 합니다.

리뷰어가 같은 지적을 반복하면 그 내용을 REVIEW.md로 옮기라고도 해요. CLAUDE.md와는 역할이 나뉩니다. 프로젝트 전반의 규칙은 CLAUDE.md에, 리뷰에서만 쓰는 지시는 REVIEW.md에 둡니다.

공식 문서에는 이런 예시가 있어요.

## 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

## Always check
- New API routes have an integration test

문서에서 짚는 주의점도 있어요.

• REVIEW.md는 저장소 루트에 두고, 하위 폴더에 따로 두면 그 경로만 검사를 추가할 수 있습니다.
• 리뷰는 PR에서 바꾼 REVIEW.md가 아니라 기본 브랜치(또는 PR의 대상 브랜치)에 있는 것을 읽습니다. 지시를 바꾸려면 먼저 머지해야 해요.
• 심각도를 낮추거나, 경로를 빼거나, nit 개수를 제한하는 지시는 기본 브랜치가 보호돼 있어야 적용됩니다.
• 로컬에서 쓰는 /code-review 명령은 REVIEW.md를 읽지 않습니다. 두 곳 모두에 적용할 규칙은 CLAUDE.md에 넣으세요.

출처: 기사, Customize Code Review 문서