How the Claude Code team does code review

claude.dev 블로그 원문(Addy Osmani 외, 2026-10-15)을 끝까지 읽고 옮겼어요. 그림은 캡션만 반영했어요.

배경

Claude가 Claude Code 코드의 약 90%를 쓰면서 변경량이 폭증했어요. Anthropic 모노레포의 하루 반영 변경은 5월 약 2,500건에서 9월 3만 건 이상이 됐어요. 그런데 6–9월 Claude Code 병합 PR은 두 배 넘게 늘었는데도 되돌린 비율은 40% 넘게 줄었다고 해요. 리뷰를 없앤 게 아니라 읽는 일 대부분을 기계로 옮기고, 실수를 빨리 되돌리는 데 투자했다는 설명이에요.

목표와 지표

"사람이 코드를 읽었나"는 부정확한 대리 지표라고 봐요. 목표는 대부분의 PR이 사람 최대 1명(작성자 포함)으로 병합되면서 되돌림·장애가 늘지 않는 것이에요. PR당 사람 승인 수(중앙값·95분위), 사람 코멘트, 대기 시간을 재고, 되돌림·장애율을 가드레일로 둬요.

겹겹의 검사

1. PR 전 검증: 테스트·빌드·디자인 스크린샷처럼 실행 가능한 것을 주고 결과를 보이게 해요. 새 컨텍스트의 서브에이전트가 diff를 리뷰해요. 반복 지적은 스킬, 린트 규칙, CLAUDE.md, 코드 오너가 쓰는 REVIEW.md로 원인에서 고쳐요.
2. 모든 PR에 AI 리뷰: 연구 프리뷰 때 실질 코멘트가 달린 PR 비율이 16%에서 54%로 올랐어요. 여러 에이전트가 버그를 찾고 다른 그룹이 투표해 충분히 동의한 지적만 올려요. Important·Nit·Pre-existing 태그를 달고, 모든 지적에 답해야 해요.
3. 차단 가능한 보안 리뷰: 열린 지적이 있으면 병합이 안 돼요.
4. 자동 검사: 린트·타입·전 플랫폼 테스트·빌드. PR 템플릿에 테스트 방법과 되돌리는 법을 적어요.
5. 위험도별 사람 승인: 낮음(문서, 플래그 뒤 추가 변경)은 0명, 보통(캐시·자동 업데이터·시스템 프롬프트 포함)은 1명, 높음은 2명이에요. 등급은 작성자가 아니라 변경을 분류기가 읽고 정해요. 에이전트 승인은 사람 승인을 대신하지 못하고, 새 커밋이 오면 다시 승인해야 해요.
6. 머지 큐·플래그·단계적 배포, 7. 빠른 감지와 롤백(배포 없이 플래그 끄기, 주간 온콜).

리뷰어를 더 낫게

• 과거 장애 PR을 모아 만든 평가셋으로 리뷰어를 매일 돌려요.
• 코멘트에 사람이 어떻게 반응했는지(고침, 틀림, 의도함, 무시)로 노이즈를 재요. 에이전트 작성자는 사소한 지적도 다 고쳐서 노이즈 비용이 더 커요.
• 한 PR이 밤새 50라운드 넘게 리뷰·수정을 반복한 적이 있어요. 반복 지적의 약 59%는 첫 리뷰 때부터 있던 코드였어요. 그래서 3라운드 상한, 이후 diff만 재리뷰, 버그 "유형" 지적, 중복 금지를 도입했어요.

사람이 남는 자리

만들지 말지(방향·취향·범위), 결제·자동 업데이터·CI 같은 위험 코드, 남들이 따라 할 아키텍처, 증거 읽기, 결과에 대한 책임이에요. 코드 이해 공유는 필요한 부분의 설명서를 Claude에게 쓰게 하는 방식으로 대신해요. "반영한 사람이 책임진다"는 원칙은 작은 변경, 모든 것의 되돌릴 수 있음, 비난 없는 장애 리뷰로 받쳐요.

도입 방법(요약)

짧은 CLAUDE.md와 훅, 로컬 /code-review·/security-review, REVIEW.md, PR 템플릿에 Testing·Risk·How to revert, 한 저장소부터 AI 리뷰어, 모든 리뷰 스레드 해결 후 병합, 위험도 등급 문서화, CODEOWNERS·브랜치 보호, 장애를 평가셋으로 만들기를 권해요.