AI가 코드를 빠르게 작성하면 코드 리뷰 대기열도 빠르게 쌓입니다. 리뷰어를 더 붙이는 방법만으로는 생성 속도를 따라가기 어렵습니다. 그렇다고 사람이 읽는 단계를 없애면 결함 처리와 장애 복구에 더 많은 시간을 쓸 수 있습니다.
Anthropic이 공개한 Claude Code 팀의 코드 리뷰 방식 ↗은 이 문제를 검증·승인·복구로 나눕니다. 기계는 반복적인 코드 읽기와 결함 탐지를 맡습니다. 사람은 변경의 방향, 위험, 검증 증거와 결과에 책임을 집니다.
이 글은 내부 운영 사례와 공개 Code Review 제품의 차이를 구분하고, 팀이 먼저 도입할 검증 규칙과 승인 경계를 정리합니다.
기준: 2026-10-18 확인. Anthropic의 운영 사례와 Claude Code 공식 문서를 기준으로 합니다. 내부 성과는 공급자 자체 관찰이며 다른 팀에서 같은 결과를 보장하지 않습니다.
줄 단위 검토보다 사람의 총시간을 줄입니다
Anthropic에 따르면 6월부터 9월 사이 Claude Code 코드베이스의 병합 PR 수는 두 배 이상으로 늘었습니다. 같은 기간 되돌려야 했던 PR의 비율은 40% 넘게 낮아졌습니다. 이는 되돌리기 건수가 40% 줄었다는 뜻이 아닙니다. 병합량이 늘었으므로 비율과 건수를 구분해야 합니다.
또 다른 수치인 하루 변경 2,500건에서 30,000건 이상으로의 증가는 Anthropic 모노레포에 관한 설명입니다. Claude Code는 별도 저장소이므로 두 범위를 같은 지표로 묶으면 안 됩니다. (원문 ↗)
팀이 줄이려는 비용은 리뷰어가 코드를 읽는 시간만이 아닙니다. 잘못된 코드가 만든 문제를 고치는 시간도 포함합니다. 이를 위해 PR당 사람 승인 수의 중앙값과 95백분위수, 사람 댓글 수, 사람을 기다리는 시간을 봅니다. 되돌리기와 사고 비율은 품질이 나빠지지 않았는지 확인하는 경계 지표입니다.
리뷰 시간이 짧아져도 장애 대응 시간이 늘면 개선으로 보지 않습니다. 이 기준은 자동 리뷰 제품을 도입하지 않는 팀에도 그대로 적용할 수 있습니다.
변경 하나를 여러 검증 계층에 통과시킵니다
Anthropic의 흐름은 PR 마지막에 AI 리뷰 하나를 추가하는 방식보다 넓습니다.
- PR 이전 검증: 테스트·빌드·화면 같은 실행 가능한 확인 수단을 에이전트에 줍니다. 완료했다는 말 대신 결과를 요구하고, 새 문맥의 하위 에이전트가 diff를 검토합니다.
- PR AI 리뷰: 여러 에이전트가 변경과 주변 코드를 읽습니다. 별도 검증 에이전트들이 후보 지적을 확인한 뒤 중복과 잡음을 걸러냅니다.
- 보안 리뷰: 보안 지적도 별도로 확인합니다. 내부에서는 버그·보안 리뷰의 열린 지적이 남으면 병합하지 못합니다. 수정하거나 근거를 남겨 스레드를 닫습니다.
- 결정적인 자동 검사: lint, 타입 검사, 플랫폼별 테스트와 빌드를 수행합니다. AI 리뷰가 이 검사를 대체하지 않습니다.
- 위험 기반 사람 승인: 문구 변경과 자동 업데이트 변경에 같은 승인 수를 요구하지 않습니다.
- 병합·점진 배포: 병합 큐에서 main과 합친 상태를 재검사합니다. 기능 플래그, 사내 사용, latest와 stable 채널을 통해 노출을 나눕니다.
- 탐지·복구: 플래그를 끄거나 변경을 되돌리고, 사고가 어느 계층을 통과했는지 분석합니다.
각 계층은 다른 실패를 잡습니다. 타입 검사는 제품 의도를 판정하지 못하고, AI 리뷰의 지적 검증은 실제 테스트 실행과 다릅니다. 사람이 승인했다고 두 PR을 합친 결과까지 검증되는 것도 아닙니다.
내부 자동 병합과 공개 Code Review는 다릅니다
공개 Code Review 문서 ↗는 제품이 PR을 승인하거나 차단하지 않는다고 명시합니다. 제품은 인라인 지적, 요약, check run을 남깁니다. check run도 실패 상태로 끝나지 않습니다. 병합 여부는 팀의 정책이 결정합니다.
반면 Anthropic 내부 저장소에는 위험 분류, 신뢰된 작성자 목록, 미해결 스레드 차단과 승인 정책이 추가돼 있습니다. 내부 사례의 자동 병합을 제품 기본 기능으로 읽으면 안 됩니다.
| 내부 위험 구분 | 사례 | 사람 승인 정책 |
|---|---|---|
| 낮음 | 문서·문구, 내부 기능, 플래그 뒤의 추가 변경 | 자동 검사가 통과하면 필수 승인 없음 |
| 중간 | 일반 제품 변경, 캐시·자동 업데이트·시스템 프롬프트 같은 민감 영역 변경 | 한 사람 |
| 높음 | 가장 위험한 코드와 두 사람 승인이 고정된 경로 | 두 사람 |
이 완화 경로는 신뢰된 작성자에게만 적용됩니다. 그 밖의 작성자는 두 번째 사람의 승인이 필요합니다. 위험 등급 외에도 별도 분류기가 추가 검토 필요성을 판단하고, 민감 경로와 CI 워크플로에는 사람을 남깁니다. 에이전트의 승인은 필수 사람 승인 수를 채우지 못합니다.
에이전트에 변경을 지시한 사람도 책임자입니다. 승인은 특정 커밋에 묶이며, 시스템이 신뢰를 보장할 수 없는 후속 커밋이 들어오면 다시 승인해야 합니다. (내부 승인 설명 ↗)
작은 팀이라면 처음부터 무인 병합을 목표로 잡지 않습니다. 인증·결제·CI·설치·배포 경로를 사람 검토 대상으로 고정한 뒤, 낮은 위험의 변경에서 검증 증거를 쌓습니다.
AI 리뷰는 많이 반복하는 것보다 수렴해야 합니다
원문에는 한 CLI PR이 하룻밤 동안 50회 넘게 리뷰와 수정을 반복한 사례가 나옵니다. 지적된 코드를 추적하자 약 59%는 첫 리뷰 때부터 있던 코드였습니다. 새 수정이 만든 버그만 찾는 대신 기존 문제를 매번 조금씩 추가 발견한 셈입니다.
사람은 사소한 제안을 무시할 수 있지만 에이전트는 이를 고치고 새 커밋을 만듭니다. 새 커밋이 리뷰를 부르고, 리뷰가 다시 수정을 부릅니다. 그래서 지적의 정확도뿐 아니라 통과까지 걸린 반복 횟수도 측정합니다.
Anthropic이 적용한 수렴 규칙은 다음과 같습니다.
- 세 차례 뒤에는 작성자에게 접근 자체를 재검토하도록 요청합니다.
- 초기 몇 번 이후에는 새 diff를 중심으로 다시 리뷰합니다.
- 한 줄 대신 버그 유형을 지적해 같은 문제를 한 번에 고치게 합니다.
- 이미 올린 지적을 반복하지 않습니다.
세 번이라는 숫자는 모든 저장소의 정답이 아닙니다. 고위험 변경에는 더 깊은 검토가 필요할 수 있습니다. 다만 자동 수정 루프에는 반복 예산과 사람에게 넘길 종료 조건이 있어야 합니다.
REVIEW.md는 프로젝트 소개보다 실패 조건을 적습니다
리뷰 맞춤 설정 문서 ↗는 파일의 역할을 구분합니다. CLAUDE.md는 프로젝트 전반의 문맥과 규칙을, REVIEW.md는 리뷰가 지적할 문제와 심각도·제외 범위를 담습니다.
다음은 프론트엔드 팀을 위한 작성자 구성 예시입니다. 공식 기본 설정이 아니라, 반복되는 리뷰 댓글을 규칙으로 옮기는 방법을 보여 줍니다.
# 리뷰 기준
## 우선 확인할 실패
- 권한 없는 사용자가 보호된 데이터나 동작에 접근한다.
- 키보드로 주요 동작을 완료할 수 없다.
- 요청 실패 뒤에도 성공 화면을 표시한다.
- 기능 플래그를 꺼도 이전 동작으로 돌아가지 않는다.
## 근거
- 동작 오류는 파일·줄과 실패 조건을 함께 제시한다.
- 이름만 보고 추측하지 말고 호출부와 상태 전이를 확인한다.
## 잡음 제한
- CI가 강제하는 포맷·타입 오류는 중복 지적하지 않는다.
- 생성 코드와 잠금 파일의 문체를 리뷰하지 않는다.
- 새로운 근거 없이 이미 해결된 지적을 반복하지 않는다.서비스는 PR이 바꾼 REVIEW.md를 그대로 믿지 않습니다. base 또는 default 브랜치의 파일을 읽으며, 제외 규칙과 심각도 완화 등에는 브랜치 보호 조건이 적용됩니다. 리뷰 규칙 변경은 먼저 병합하고 기본 브랜치를 보호해야 합니다.
또한 로컬 명령과 서비스의 입력이 다릅니다. 문서 기준으로 로컬 /code-review는 CLAUDE.md를 읽지만 REVIEW.md는 읽지 않습니다. 두 경로에 공통으로 적용할 규칙은 CLAUDE.md에 둡니다.
사고는 다음 리뷰어의 평가 데이터가 됩니다
Anthropic은 사고를 일으킨 과거 PR과 수정·되돌리기를 모읍니다. 해당 코드를 아는 엔지니어가 버그와 위치를 확인한 뒤, 리뷰어를 매일 이 사례군에 실행합니다. 모델·프롬프트·도구를 바꿀 때도 같은 사례군으로 점검합니다.
오탐은 댓글에 대한 반응으로 나눠 봅니다. 실제 수정했는지, 지적이 틀렸는지, 의도한 동작인지, 중요하지 않은 문제인지 구분합니다. 깨끗한 PR에도 리뷰어를 실행해 불필요하거나 해로운 수정을 유도하는지 살핍니다.
리뷰어가 지적을 많이 남기는 것과 품질을 높이는 것은 다릅니다. 팀에 적용할 때는 다음 세 묶음을 함께 기록합니다.
- 탐지: 알려진 결함을 찾았는가, 실제 결함을 놓쳤는가.
- 잡음: 잘못된 지적과 불필요한 수정이 얼마나 생겼는가.
- 운영: 통과까지 몇 회 반복했고, 사람 시간과 배포 후 사고가 어떻게 변했는가.
원문도 미완성인 부분을 공개합니다. 되돌리기나 사고 지표가 나빠질 때 승인 요건을 자동으로 강화하는 circuit breaker는 아직 없다고 설명합니다. 이 사례를 완결된 무인 개발 체계로 해석하지 않는 이유입니다.
코드를 덜 읽으면 팀의 이해는 어떻게 유지할까요
코드 리뷰는 결함 탐지 외에도 지식을 공유합니다. Anthropic은 이 두 번째 역할에 아직 정형화된 프로세스는 없다고 밝힙니다. 대신 변경하려는 모듈을 Claude가 설명하게 하고, 필요하면 해당 부분을 시각화한 작은 학습용 산출물을 만듭니다.
공식 도식 보기: 필요한 코드 영역을 설명문·시각화로 학습하기 ↗
출처: Anthropic 원문, 팀 문맥 공유 절 ↗. 도식은 모든 코드를 외우기보다 지금 바꿀 부분의 설명과 시각화를 요청하는 흐름을 보여 줍니다.
이 방식에도 검증은 필요합니다. 설명이 현재 코드와 맞는지 확인하고, 설계의 이유와 과거 결정은 사람이 보완해야 합니다. 생성된 설명만으로 팀의 아키텍처 이해가 유지된다고 보장할 수는 없습니다.
팀에서는 리뷰어보다 검증 증거부터 도입합니다
공개 Code Review 서비스는 Team·Enterprise 조직의 GitHub 저장소를 대상으로 합니다. 조직 Owner의 설정이 필요하며, ZDR·HIPAA 구성·고객 관리 암호화 키 등에는 제공 제한이 있습니다. 코드는 Anthropic 인프라에서 읽고 검토하며 빌드하거나 실행하지 않습니다. (제공 조건 ↗)
유료 서비스를 바로 도입하지 않아도 원문의 운영 원칙은 적용할 수 있습니다.
- PR 양식에 테스트·위험·복구 방법을 적습니다. 실행 명령과 결과, 화면 변경이면 캡처를 남깁니다.
- 기존 CI와 사람 승인부터 유지합니다. AI 리뷰는 우선 보조 의견으로 붙이고 실제 결함·오탐을 관찰합니다.
- 반복 지적을 규칙으로 옮깁니다. 기계적으로 판정할 수 있으면 lint·테스트로, 문맥이 필요하면 리뷰 지침으로 만듭니다.
- 반복 상한과 에스컬레이션을 정합니다. 리뷰와 수정이 수렴하지 않으면 사람이 범위와 접근을 다시 판단합니다.
- 병합 후 책임자를 남깁니다. 작은 변경, 기능 플래그, 되돌리기 절차와 사고 회고가 있어야 승인 완화를 검토할 수 있습니다.
Anthropic의 사례에서 옮겨올 것은 사람 승인 수 자체보다 그 수를 줄일 수 있게 만든 검증·복구 조건입니다. 그 조건을 갖추기 전에 승인만 줄이면 리뷰 대기열이 장애 대응 대기열로 옮겨갈 수 있습니다.
참고 자료
- How the Claude Code team does code review ↗ — 내부 검증 계층, 승인, 리뷰 수렴과 사고 평가
- Code Review 공식 문서 ↗ — 제품의 제공 범위, 검토 방식과 승인·차단 경계
- Customize Code Review ↗ — CLAUDE.md·REVIEW.md의 역할과 브랜치 보호 조건