에이전트가 코드를 쏟아내는 팀은 리뷰를 어떻게 할까: Claude Code 팀의 여섯 겹 검사

에이전트에게 코드를 맡기기 시작하면 PR이 사람 손으로 다 읽을 수 없는 속도로 늘어납니다. 꼼꼼히 읽으려 들면 리뷰 대기열이 병목이 되고 대충 넘기면 무엇을 놓쳤는지 알 수 없게 됩니다. Claude Code 팀이 이 문제를 어떻게 풀었는지, 사람의 시간을 어디에 쓰기로 했는지 정리합니다.

한눈에 보기

• Claude Code 코드의 약 90%를 Claude가 씁니다. 6월부터 9월 사이 병합된 PR은 두 배 넘게 늘었는데 되돌린(revert) PR의 비율은 40% 넘게 줄었습니다.
• 리뷰를 없애지 않고, 읽는 일을 대부분 기계로 옮겼습니다. PR이 생기기 전 검증부터 머지 후 롤백까지 여러 겹의 검사가 각자 일부 문제를 잡습니다.
• 사람 승인 인원은 누가 썼느냐와 상관없이 변경 내용의 위험도로 정합니다. 위험이 낮으면 사람 승인 없이, 보통이면 한 명, 높으면 두 명입니다.
• 에이전트끼리 리뷰와 수정을 끝없이 주고받지 않도록 리뷰 횟수 상한 같은 규칙을 넣었습니다. 한 번 만에 통과하는 내부 PR 비율이 65%에서 78%로 올랐습니다.

원문은 어떤 글인가

Addy Osmani, Morgan Westlee Lunt, Qing Wang이 2026년 10월 15일에 쓴 글이고 읽는 데 14분쯤 걸립니다. Claude Code 팀이 실제로 쓰는 리뷰 흐름을 층별로 설명합니다. 리뷰 에이전트를 어떻게 개선하는지, 사람은 어디에 남는지, 다른 팀은 무엇부터 따라 하면 되는지도 다룹니다. 에이전트가 PR을 여는 팀에서 리뷰 규칙을 다시 짜야 하는 개발 리드에게 맞습니다. 원문: How the Claude Code team does code review

리뷰의 목적부터 다시 정했다

물량부터 봅시다. Anthropic 모노레포에 하루에 들어가는 변경은 올해 5월 약 2,500건에서 9월 30,000건 이상으로 늘었습니다. Claude Code는 모노레포와 별도 저장소인데, 여기도 압력이 크기는 마찬가지입니다. 이 속도면 사람이 한 줄씩 읽는 리뷰는 거의 불가능합니다.

원문은 리뷰가 하는 일을 두 가지로 봅니다. 출시 전에 문제를 찾아 고치는 일, 그리고 팀이 코드베이스를 함께 이해하게 만드는 일입니다. 글은 주로 첫 번째를 다룹니다. 저자들은 “사람이 코드를 읽었나"를 따지는 대신, 이 변경에서 무엇이 잘못될 수 있고 그걸 잡을 검사가 자동이어야 하는지 사람이어야 하는지를 묻자고 합니다. 질문이 바뀌니 리뷰 시점도 달라졌습니다. 예전에는 PR을 열고 동료를 기다리는 마지막 관문이었다면, 지금은 글을 쓰는 동안 계속 도는 맞춤법 검사처럼 작업 내내 돕니다. 사람에게 요청이 가기 전에 대부분의 변경은 Claude가 이미 한 번 이상 리뷰하고 고친 상태입니다.

목표도 구체적으로 정했습니다. CLI, 데스크톱·웹 앱, 모바일 앱까지 Claude Code 저장소의 PR 대부분이 사람 최대 한 명만 거쳐 병합되게 하는 것입니다. 그 한 명은 작성자여도 되고 되돌림과 장애가 늘면 안 됩니다. 사람의 시간은 세 가지로 잽니다. PR당 사람 승인 수(중앙값과 95번째 백분위수), 사람 댓글 수, 그리고 PR이 사람을 기다린 시간입니다. 되돌림과 장애 비율은 가드레일입니다. 리뷰에서 아낀 시간이 수습하는 시간으로 옮겨 갔을 뿐이라면 이 비율이 올라가서 바로 드러납니다.

변경 하나가 거치는 길

아래 그림은 변경 하나가 작성자의 노트북에서 사용자에게 가기까지 거치는 단계입니다. 동그라미는 자동 검사, 주황 마름모는 사람이 위험도에 맞춰 결정하는 곳, 마지막 회전 화살표는 복구 단계입니다.

그림 1. 위에서 아래로 BEFORE THE PULL REQUEST(PR 전), ON EVERY PULL REQUEST(모든 PR), MERGING(병합), AFTER THE MERGE(병합 후) 단계입니다. 사람이 결정하는 곳은 Risk-based approval 하나뿐입니다. 출처: 원문 .

각 단계를 짧게 풀면 이렇습니다.

• PR 전 검증: Claude에게 테스트나 빌드, 디자인과 비교할 스크린샷처럼 직접 돌려 볼 수단을 쥐여 주고, 끝났다는 말 대신 실행 결과를 내놓게 합니다. 이어서 새 컨텍스트로 띄운 서브에이전트가 diff를 다시 봅니다. Claude Code를 만든 Boris Cherny는 이런 검증 수단이 최종 결과를 두세 배 좋게 만든다고 추정합니다.
• 설명 파일: 자동 리뷰가 같은 지적을 반복하면 스킬이나 린트 규칙, 설명 파일을 고칩니다. CLAUDE.md는 프로젝트가 무엇인지 알려 주고, 코드 소유자가 쓰는 REVIEW.md는 그 영역에서 무엇이 중요한지 알려 줍니다. 원문이 꼽는 좋은 REVIEW.md는 짧습니다. 그 저장소에서 실패가 어떤 모습인지(문서라면 사실과 다른 내용, 설정이라면 엉뚱한 곳으로 보내는 것) 적고, 사소한 지적의 개수를 제한하고 근거로 파일과 줄 번호를 요구합니다.
• 모든 PR에 AI 리뷰: 공개 버전인 Code Review for Claude Code는 Team, Enterprise 요금제에서 정식 제공되고 /code-review 는 가벼운 버전을 로컬에서 돌립니다. 연구 프리뷰를 내놨을 때 의미 있는 리뷰 댓글이 달린 내부 PR은 16%에서 54%로 늘었습니다. 리뷰 강도는 저장소마다 Quick, Standard, Deep 중에서 고릅니다.
• 지적의 검증: 버그 찾기는 에이전트 여러 개가 동시에 하고 다른 에이전트 묶음이 지적마다 진짜인지 투표합니다. 충분히 동의를 얻은 것만 올라가고, 스타일이나 정리 수준의 지적은 걸러집니다. 남은 지적에는 Important, Nit, Pre-existing 꼬리표가 붙어 심각도 순으로 달립니다. Pre-existing은 이 PR이 만든 버그가 아니라는 표시입니다. 작성자는 지적마다 고치거나, 이유를 적고 스레드를 닫아야 합니다.
• 보안 리뷰와 필수 검사: 보안 리뷰도 따로 돌고, 버그 리뷰나 보안 리뷰의 지적이 하나라도 열려 있으면 병합되지 않습니다. 린트, 타입 검사, 모든 플랫폼 테스트, 빌드도 필수입니다. PR 템플릿에는 어떻게 테스트했는지와 어떻게 되돌리는지를 적는 칸이 있습니다.

지금까지의 층을 한 그림으로 모으면 이렇습니다. 각 층은 일부 문제를 잡고 일부를 놓칩니다.

그림 2. 판 하나가 검사 한 층이고 주황 점이 문제, 흰 구멍이 그 층이 놓치는 자리입니다. 모든 층을 통과한 문제는 드물고, 그런 문제는 맨 아래 fast rollback(빠른 롤백)이 받습니다. 출처: 원문 .

위험도가 승인 인원을 정한다

문서 오타 수정과 자동 업데이터 수정을 같은 강도로 리뷰할 이유는 없습니다. 원문의 기준을 표로 옮기면 이렇습니다.

등급은 분류기가 변경 내용을 읽고 매기고, 두 번째 분류기가 등급과 별개로 사람이 한 명 더 필요한지 한 번 더 따집니다. 소유자가 민감하다고 지정한 경로와 CI 워크플로 파일은 등급과 관계없이 사람이 봅니다.

가벼운 경로에도 조건이 붙습니다. 저장소의 신뢰 목록에 든 작성자만 이 길을 쓸 수 있고, 에이전트의 승인은 사람 승인 칸을 채우지 못합니다. 에이전트가 쓴 PR이라면 그 에이전트에게 일을 시킨 사람이 필수 리뷰어 한 명으로 잡힙니다. 승인은 특정 커밋 기준이라, 에이전트가 새로 푸시하거나 누가 손으로 충돌을 풀어 병합 커밋을 만들면 승인을 다시 받아야 합니다.

병합 뒤에도 겹은 이어집니다. 머지 큐는 main에 변경을 얹은 상태로 검사를 다시 돌려, 따로는 통과한 PR 두 개가 합쳐져 main을 깨뜨리지 않게 막습니다. 새 기능은 대개 플래그 뒤에 숨겨 Anthropic 직원이 먼저 쓰고, 공개 배포는 latest 채널에 먼저 나간 뒤 stable 채널이 따라갑니다. 플래그는 배포 없이 끌 수 있고, 매주 돌아가는 당번(on-call)이 있습니다. 다만 되돌림이나 장애 수치가 움직일 때 자동으로 승인을 조이는 회로 차단기는 아직 없다고 원문은 밝힙니다.

리뷰가 끝나지 않는 문제

작성자와 리뷰어가 둘 다 에이전트면 리뷰와 수정이 끝없이 오갈 수 있습니다. CLI PR 하나는 밤새 쉰 번 넘게 리뷰와 수정을 주고받았고 작성자가 직접 멈추고 나서야 끝났습니다. 리뷰어가 계속 짚은 코드에 git blame을 돌려 보니 약 59%가 첫 리뷰 때 이미 있던 코드였습니다. 새 버그는 거의 찾지 못하고 매 라운드 놓쳤던 버그를 몇 개씩 더 꺼낸 셈입니다. 사람이면 사소한 지적은 몇 초 만에 넘기는데 에이전트는 그걸 다 고치느라 커밋 하나와 리뷰 한 바퀴를 더 씁니다.

그래서 재리뷰 규칙을 바꿨습니다. 원문은 네 규칙을 목록으로만 제시하는데 이해하기 쉽게 흐름으로 옮기면 이렇습니다.

flowchart TD
  A["AI 리뷰"] --> B{"새 지적 있음"}
  B -->|"아니오"| C["통과"]
  B -->|"예"| D["버그 유형 단위로<br/>모든 사례 수정"]
  D --> E{"3번째 리뷰<br/>지났나"}
  E -->|"아니오"| F["재리뷰 - 몇 번 뒤엔 새 diff만<br/>이미 단 지적은 반복 안 함"]
  F --> B
  E -->|"예"| G["작성자에게<br/>접근 방식 재검토 요청"]

기존 코드에 숨은 옛 버그는 밤마다 따로 도는 리뷰 에이전트 몫으로 넘겼습니다. 아래 차트는 이 변경 전후의 내부 PR 수치입니다.

그림 3. 회색이 before(변경 전), 주황이 after the convergence work(수렴 작업 후)입니다. 위에서부터 한 번의 리뷰·수정 라운드로 통과한 PR 비율, 다섯 번 이상 걸린 PR 비율, 통과까지 평균 리뷰 횟수입니다. 출처: 원문 .

리뷰어의 성능도 꾸준히 잽니다. 팀은 과거에 장애를 낸 PR을 모으고, 그 코드를 잘 아는 엔지니어에게 버그와 위치를 확인받아 평가 세트로 만들었습니다. 리뷰어는 이 세트로 매일 채점됩니다. 소음은 사람들의 반응으로 셉니다. 지적을 받고 고쳤는지, 틀렸다고 했는지, 의도한 동작이라고 했는지, 상관없다고 넘겼는지를 나눕니다. 깨끗하다고 알려진 PR에 리뷰어를 돌려, 괜히 해로운 수정을 부를 만한 지적이 얼마나 나오는지도 봅니다. 팀이 적어 둔 우선순위는 진짜 버그 잡기가 먼저, 리뷰 라운드 줄이기가 그다음입니다.

사람은 어디에 남나

원문이 사람 몫으로 남긴 일은 다섯 가지입니다. 이걸 만들어야 하는지 정하는 방향·취향(taste)·범위의 판단, 결제·자동 업데이터·CI 워크플로처럼 위험한 코드, 다른 사람이 따라 할 패턴이 되는 아키텍처가 먼저 꼽힙니다. 테스트 출력과 스크린샷 같은 증거를 읽는 일, 그리고 결과에 책임지는 일도 사람에게 남습니다. 증거를 보고도 검사가 무엇을 놓칠지 말할 수 없다면 빠른 승인 대신 제대로 된 리뷰를 요청하라고 합니다.

리뷰의 두 번째 역할인 코드 이해의 공유는 방식이 바뀌었습니다. 팀 안에 Claude Code 전체 구조를 머릿속에 들고 있는 사람은 없고, 저자들은 그럴 필요도 없다고 봅니다. 어떤 부분이 궁금하면 그 부분만 설명하는 글을 Claude에게 부탁합니다. 몇 분이면 나오고 오늘 코드 기준이라 낡지도 않습니다. 한 줄짜리 문구 수정 diff를 읽어서는 배울 게 거의 없고, 곧 고칠 모듈의 설명을 읽는 편이 훨씬 남는다는 이유입니다.

작거나 중간 크기의 변경을 병합한 사람이 그 뒤 생긴 문제도 대개 직접 고친다는 팀 관행도 있습니다. 변경이 작고, 대부분의 실수를 몇 분 안에 되돌릴 수 있어서 돌아가는 관행입니다. 누구 탓인지 따지려는 게 아니고, 맥락을 가장 많이 아는 사람이 고친다는 뜻입니다.

인사이트

여기서부터는 원문이 아니라 이 블로그의 해석입니다.

1. 가장 쓸모 있는 아이디어는 “사람의 시간"을 지표로 두고 되돌림·장애 비율을 가드레일로 묶은 점입니다. 데이터 파이프라인 리뷰도 사람이 SQL을 다 읽었는지 따지기보다, 검증 쿼리와 데이터 품질 검사가 무엇을 잡고 무엇을 놓치는지 층별로 적어 보면 사람이 꼭 봐야 할 변경이 훨씬 좁아집니다.

2. 첫 리뷰 때 이미 있던 코드에 대한 지적이 59%였다는 숫자는 에이전트 리뷰 루프를 설계할 때 바로 써먹을 만합니다. 에이전트에게 에이전트를 리뷰시킨다면 라운드 상한과 새 diff만 보는 규칙을 처음부터 넣는 편이 낫습니다. 그러지 않으면 토큰과 시간이 첫 라운드에 놓친 문제를 조금씩 캐내는 데 계속 들어갑니다.

3. 장애 이력을 리뷰어의 평가 세트로 쓰는 방식은 사내 에이전트에도 그대로 옮길 수 있습니다. 운영에서 실제로 터진 사례를 모아 두고 프롬프트, 도구, 모델을 바꿀 때마다 다시 채점하면, 새 버전이 더 나은지를 우리 사고 기록에 비춰 판단할 수 있습니다.

바로 해볼 것

• 저장소에 REVIEW.md를 만들고, 최근 PR에서 반복해서 단 리뷰 댓글을 옮겨 적습니다. 문서·설정처럼 영역별로 실패가 어떤 모습인지도 한 줄씩 씁니다.
• PR 템플릿에 테스트 방법, 위험도, 되돌리는 방법 칸을 추가합니다.
• 에이전트 리뷰를 쓰고 있다면 지난 몇 주간 PR별 리뷰 라운드 수를 세어 보고, 세 번을 넘은 PR이 얼마나 되는지 확인합니다.

원문: How the Claude Code team does code review