에이전트가 쏟아내는 코드를 어떻게 다 리뷰할 수 있을까요? Claude Code 팀은 높은 커버리지와 깊이 있는 리뷰 체계를 갖춘 뒤, 리버트나 장애가 늘지 않는 선에서 사람이 리뷰에 쓰는 시간을 최소화하는 방향으로 최적화를 시작했습니다.
앞서 Claude Code 코드의 약 90%를 Claude가 직접 작성한다고 말씀드린 적이 있습니다. 그렇다면 이렇게 쏟아지는 코드를 어떻게 리뷰할까요? 요즘도 코드를 직접 읽는 사람이 있을까요? 그리고 뭔가 깨지면 누가 잡아낼까요?
이 글에서는 Claude Code 팀의 코드 리뷰 흐름과 그 변화 과정을 소개합니다. 6월부터 9월까지 Claude Code 코드베이스에 머지된 풀 리퀘스트(PR)는 두 배 넘게 늘었고, 그중 리버트된 비율은 40% 넘게 줄었습니다.
리뷰를 없앤 것은 아닙니다. 대신 읽는 일의 대부분을 기계에 넘기고, 사람의 시간과 주의력을 아끼는 쪽으로 최적화했습니다. 그리고 실수를 빠르고 쉽게 되돌릴 수 있도록 많은 투자를 했습니다.
에이전트가 코드를 쓰기 시작하면 변경 건수가 빠르게 늘어납니다. Anthropic 모노레포에서는 하루에 반영되는 변경이 올해 5월 약 2,500건에서 9월 3만 건 이상으로 늘었습니다.
Claude Code는 모노레포와 별도의 저장소에서 관리되지만, 이곳 역시 상당한 부담을 받고 있습니다. 이런 속도로 배포하는 상황에서는 한 줄 한 줄 수동으로 리뷰하는 것이 불가능하다고 해도 과언이 아닙니다.
코드 리뷰에는 두 가지 역할이 있습니다.
이 글은 주로 첫 번째 역할인 문제 발견과 수정을 다루고, 두 번째 역할은 후반부에서 다시 이야기하겠습니다.
저희는 "사람이 코드를 읽었는가?"라는 질문이 사실은 정확한 기준이 아니라고 생각합니다. 진짜 물어야 할 것은 "이 변경에서 무엇이 잘못될 수 있고, 그것을 잡아내기에 가장 적합한 검증은 자동화된 것인가, 사람이 하는 것인가?"입니다.
이 질문을 던지자 리뷰가 이루어지는 시점도 달라졌습니다. 예전의 리뷰는 길 끝에 있는 관문이었습니다. 코드를 쓰고, PR을 열고, 동료가 봐주기를 기다리는 식이었죠.
지금의 리뷰는 글을 쓰는 동안 맞춤법을 검사해 주듯 계속 진행됩니다. 대부분의 변경은 사람에게 리뷰를 요청하기 전에 Claude가 최소 한 번은 리뷰하고 수정을 마친 상태입니다. 덕분에 일상적인 실수는 대부분 걸러지고, 팀은 더 높은 수준의 질문과 검토에 집중할 수 있습니다.
사람의 시간과 주의력은 사람만 풀 수 있는 문제에 쓰고, 나머지는 자동화된 검사가 잡도록 하는 것이 저희의 목표입니다. 지금 같은 변경 속도에서도 사람이 해야 할 일은 여전히 엄청나게 많고, 팀은 거의 매일 새롭고 낯선 과제와 마주합니다.
여기서 사람의 시간이란 리뷰 비용의 양쪽을 모두 뜻합니다. 사람이 리뷰하는 데 쓰는 시간, 그리고 잘못된 코드가 일으킨 문제를 고치는 데 쓰는 시간입니다. 앞쪽을 줄여도 그만큼이 뒤쪽에서 나타난다면 의미가 없습니다.
그래서 목표는 Claude Code 저장소(CLI, 데스크톱·웹 앱, 모바일 앱)의 대부분의 PR이 리버트나 장애 증가 없이, 작성자 본인을 포함해 사람 한 명만 거치고 머지되도록 하는 것입니다. 사람의 시간은 PR당 사람 승인 횟수(중앙값과 95번째 백분위수), 사람이 단 코멘트 수, PR이 사람을 기다리는 시간으로 측정합니다. 리버트율과 장애율은 안전장치입니다. 이 수치가 오르면 사람의 시간을 아낀 것이 아니라 다른 곳으로 옮겼을 뿐입니다.
엔지니어의 노트북(또는 Slack의 Claude 세션)에서 시작된 일반적인 변경은 여러 겹의 코드 리뷰 계층을 거칩니다.


이제 리뷰의 대부분은 PR이 만들어지기 전에 이루어집니다. Claude에게 테스트, 빌드, 디자인과 비교할 스크린샷처럼 직접 실행해 볼 수 있는 수단을 주고, "끝났다"고 말하는 대신 실행 결과를 보여 달라고 요청합니다. 그다음에는 서브에이전트가 새로운 컨텍스트에서 diff를 리뷰합니다. 두 습관 모두 저희 모범 사례 가이드에서 나온 것입니다.
PR을 열기 전에 내부 스킬을 몇 가지 돌리는 사람도 많습니다. 버그를 찾는 스킬, diff를 단순화하는 스킬, 동작을 처음부터 끝까지 확인하는 스킬이 있습니다. UI 변경은 디자인 가이드라인과도 대조합니다.
Claude Code를 만든 Boris Cherny는 Claude가 스스로 작업을 검증할 방법을 주는 것이 좋은 결과를 얻는 데 아마도 가장 중요한 일이라고 말해 왔습니다. 최종 결과물이 두세 배 좋아진다고 보며, 이렇게 적었습니다. "검증 방법은 분야마다 다릅니다. bash 명령어를 실행하거나 테스트 스위트를 돌리는 것처럼 간단할 수도 있고, 브라우저나 휴대폰 시뮬레이터에서 앱을 테스트하는 것일 수도 있습니다."
자동 리뷰어가 같은 지적을 계속 반복하면 근본 원인을 고칩니다. 스킬이나 린트 규칙을 손보거나, 다음과 같은 지침 파일을 업데이트하는 식입니다.
CLAUDE.md은 프로젝트가 무엇인지 Claude에게 알려 줍니다. 기술 스택, 컨벤션, 목표와 목표가 아닌 것이 담겨 있습니다. 모든 리뷰에서 이 파일을 불러오기 때문에 큰 코드베이스에서는 짧게 유지하고 자세한 내용은 다른 문서로 연결합니다. 리뷰어는 이 파일에 적힌 컨벤션을 어기는 코드와, 이 파일의 내용을 낡게 만드는 변경도 짚어 냅니다.REVIEW.md는 코드 오너가 작성하며, 담당 영역에서 무엇이 중요한지 리뷰어에게 알려 줍니다. 리뷰어가 이 내용을 실제로 따르는지는 따로 확인합니다. 잘 쓴 파일은 짧습니다. 해당 저장소에서 실패가 어떤 모습인지 적고(문서는 "거짓말을 하는 것", 설정은 "엉뚱한 곳으로 보내는 것"), 사소한 지적(nit)의 수를 제한하며, 건너뛸 경로를 나열하고, 이름만 보고 짐작하지 말고 파일과 줄 번호를 근거로 제시하라고 요구합니다. 또 요약은 건수로 시작하고, 고칠 것이 없으면 그렇게 분명히 말하라고 요구합니다.모든 PR은 사람이 보기 전에 Claude의 리뷰를 먼저 받습니다. Claude는 저장소 전체와 PR에 적힌 의도를 기준으로 diff를 읽고 이렇게 묻습니다. 이 변경이 문제를 제대로 해결하는가, 시스템과 어울리는가, 다른 곳을 망가뜨리지는 않는가?
버그 수정이라면 근본 원인을 찾습니다. 공개 버전인 Code Review for Claude Code는 Team과 Enterprise 요금제에서 정식 출시되었고, /code-review는 로컬에서 더 가벼운 버전으로 실행됩니다.
리서치 프리뷰를 공개한 뒤, 의미 있는 리뷰 코멘트를 받은 내부 PR의 비율은 16%에서 54%로 늘었습니다. 1,000줄이 넘는 PR은 대부분 지적을 받고, 작은 PR은 대부분 문제없이 통과합니다. 관리자는 저장소마다 Quick, Standard, Deep 중 하나를 설정합니다. Deep은 버그 하나를 놓쳤을 때의 비용이 추가 리뷰 시간보다 큰 곳에서 가치가 있습니다.
발견된 문제는 사람이 보기 전에 다른 에이전트들이 검증합니다. 여러 에이전트가 동시에 버그를 찾고, 별도의 에이전트 그룹이 각 발견 사항에 투표해서 충분한 수가 실제 문제라고 동의해야만 게시됩니다. 스타일, 진단, 정리에 관한 지적만 있는 것은 걸러 냅니다. 이 필터들은 저희 PR에서 A/B 테스트를 거친 뒤 채택했습니다. 남은 지적은 심각도순으로 정렬된 인라인 코멘트로 표시됩니다. 각 코멘트에는 Important, Nit, Pre-existing 중 하나가 붙어서, PR이 만들지 않은 버그가 작성자의 잘못처럼 보이지 않게 합니다.
모든 지적에는 응답해야 합니다. 고치거나, 이유를 적고 스레드를 해결 처리해야 합니다. 밤사이 에이전트가 수정을 반영해 두는 경우도 많아서, 작성자가 돌아오면 PR이 이미 한 차례 더 리뷰를 거친 상태일 때도 있습니다.
보안도 별도의 자동 리뷰를 거칩니다. 버그 리뷰나 보안 리뷰에서 나온 지적이 하나라도 열려 있으면 PR을 머지할 수 없습니다. 고치거나, 짧은 이유를 적어 스레드를 닫아야 합니다. 오탐은 이렇게 해소합니다.
이후 커밋에서 문제가 해결되면 지적은 자동으로 닫힙니다. 오픈소스 보안 리뷰 GitHub Action이나 /security-review 명령어로도 같은 구성을 만들 수 있습니다. 설정 방법은 Claude Code의 자동 보안 리뷰에서 확인하세요.
흔히 쓰는 것들입니다. 린트, 타입 검사, 전 플랫폼 테스트, 빌드가 있습니다. (이런 규모에 맞춰 CI를 확장한 이야기는 여기에 썼습니다.) 일반적인 CLI 풀 리퀘스트는 사람이 보기 전에 수십 개의 검사를 거치기도 합니다. PR 템플릿에는 변경을 어떻게 테스트했는지, 어떻게 되돌리는지를 묻는 항목이 있습니다. Claude가 채울 수는 있지만, 변경을 요청한 사람이 그 내용을 최종 승인합니다.
문서 수정과 자동 업데이터 변경은 위험도가 다르므로 리뷰 방식도 다릅니다.
| 위험도 | 예시 | 사람 승인 |
|---|---|---|
| 낮음 | 문서, 카피, 내부 전용 기능, 플래그 뒤에 있는 추가형 변경 | 자동 리뷰와 보안 검사를 통과하면 필요 없음 |
| 중간 | 일반적인 제품 변경, 그리고 캐싱, 자동 업데이터, 시스템 프롬프트처럼 민감한 영역의 변경 | 1명 |
| 높음 | 위험도가 가장 높은 코드, 그리고 항상 두 사람이 필요한 일부 경로 | 2명 |
등급은 작성자가 아니라 변경 내용이 정합니다. 분류기가 변경을 읽고 위험 등급을 고릅니다. 두 번째 분류기는 등급상 필요 없더라도 이번 변경에는 다른 사람이 필요한지를 따로 판단합니다. 오너가 민감하다고 지정한 경로와 모든 CI 워크플로 파일처럼 항상 사람이 필요한 경로도 있습니다.
가벼운 경로는 신뢰할 수 있는 작성자에게만 열려 있습니다. 저장소의 신뢰 목록에 있는 작성자, 대부분 해당 저장소를 맡은 팀만 가벼운 경로를 쓸 수 있습니다. 그 외에는 두 번째 사람의 승인이 필요합니다. 에이전트의 승인은 사람의 승인으로 인정하지 않습니다. 자동 리뷰는 위험도가 낮은 변경을 통과시킬 수는 있어도, 사람이 필요한 자리를 대신 채울 수는 없습니다.
변경을 지시한 사람이 책임집니다. 에이전트가 작성한 PR에서는 에이전트를 지시한 사람이, 직접 코드를 입력했을 때와 똑같이 필수 리뷰어 한 명으로 계산됩니다.
승인은 특정 커밋 하나에만 유효합니다. 에이전트의 푸시나 사람이 수동으로 해결한 머지처럼 시스템이 보증할 수 없는 새 커밋이 올라오면 승인을 다시 받아야 합니다.
머지 큐는 변경을 적용한 상태의 main에 대해 모든 검사를 다시 실행합니다. 따로 보면 통과하는 두 PR이 합쳐져 main을 망가뜨리는 일을 막기 위해서입니다. 새 동작은 보통 플래그 뒤에 두고 Anthropic 직원에게 먼저 배포하는데, 저희가 워낙 많이 쓰다 보니 사용자보다 먼저 회귀를 발견하는 경우가 많습니다. 공개 릴리스는 latest 채널에 먼저 나가고, stable 채널은 그 뒤를 따릅니다.
그래도 일부 실수는 빠져나가기 마련이라, 마지막 계층의 목표는 이를 빨리 잡아내는 것입니다. 플래그는 배포 없이 끌 수 있습니다. Claude Code는 매주 온콜 당번을 돌아가며 맡고, 장애 리뷰에서는 어느 계층이 이 문제를 잡았어야 했는지 묻습니다.
잘못된 머지를 알아채는 일은 리버트·장애 대시보드뿐 아니라 작성자와 온콜 담당자에게도 달려 있습니다. 이 수치가 움직일 때 승인 기준을 자동으로 강화하는 서킷 브레이커는 아직 없습니다. 사람 없이 머지되는 코드를 더 늘리기 전에 이것부터 갖추기를 엔지니어들도 바랍니다.
한 동료는 속도를 늦추면 오류율이 실제로 내려가지만, 그건 대체로 모든 일을 덜 하기 때문이라고 말했습니다. 저희는 차라리 문제를 더 빨리 알아채고 고치는 쪽을 택하겠습니다.
저희 코드 리뷰 프로세스는 하나의 순환 구조 안에서 끊임없이 개선됩니다.
이제 모든 장애는 평가(eval) 데이터가 됩니다. 팀은 장애를 일으킨 과거 PR을 후속 수정(fix-forward), 리버트와 함께 모으고, 해당 코드를 잘 아는 엔지니어가 각 버그와 그 위치를 확인했습니다. 리뷰어는 이 데이터셋을 대상으로 매일 실행됩니다.

노이즈는 사람들이 코멘트에 어떻게 반응하는지 보고 측정합니다. 버그가 아닌 것까지 마구 지적해도 된다면 더 많은 버그를 잡기는 쉽습니다. 그래서 이를 견제할 장치가 필요합니다. 리뷰어가 남긴 모든 코멘트를 PR 담당자의 반응에 따라 분류합니다. 고쳤는지, 틀린 지적이라고 했는지, 의도한 동작이라고 했는지, 중요하지 않다고 판단했는지입니다. 문제가 없다고 알려진 PR에 리뷰어를 돌려서, 누군가 해로운 변경을 하게 만들 만한 내용을 얼마나 자주 보고하는지도 셉니다. 저희가 문서로 정해 둔 우선순위는 실제 버그를 잡는 것이 먼저이고, 리뷰 라운드를 줄이는 것이 그다음입니다.
작성자가 에이전트일 때는 노이즈의 비용이 더 큽니다. 사람은 사소한 지적을 몇 초 만에 넘길 수 있지만, 에이전트는 그것을 고치고, 그러면 커밋이 하나 더 생기고 리뷰도 한 라운드 더 돕니다.
리뷰는 수렴해야 합니다. 에이전트 작성자와 에이전트 리뷰어는 서로를 끝없이 바쁘게 만들 수 있습니다. 한 CLI PR은 작성자가 멈추기 전까지 밤새 50라운드가 넘는 리뷰와 수정을 거쳤습니다.
리뷰어가 계속 지적한 코드에 git blame을 돌려 보니, 약 59%는 리뷰어의 첫 검토 때부터 이미 있던 코드였습니다. 리뷰어는 새 버그를 거의 찾지 못했고, 라운드마다 오래된 버그를 조금씩 더 찾아내고 있었습니다.
이 상황은 저희 스스로 악화시켰습니다. 매번 새로운 것이 걸리니 기본적으로 여러 라운드를 돌리는 데 익숙해졌던 것입니다. 위험한 변경에는 그럴 가치가 있을 수 있지만 모든 PR에 필요하지는 않습니다. 이제 팀은 재현율(recall)과 함께 통과까지 걸린 라운드 수를 추적하고, 재리뷰 방식을 이렇게 바꿨습니다.
리뷰 에이전트는 기존 코드를 대상으로 매일 밤에도 실행되어, 오래된 버그가 다른 곳에서 터지기 전에 잡아내도록 돕습니다.

일상적인 실수를 잡자고 시니어 엔지니어를 깊은 몰입에서 끌어내는 비용은 자동 리뷰보다 훨씬 큽니다. Anthropic에서 저희의 역할은 모든 diff를 읽는 일에서, 기계가 서툰 판단을 내리는 일로 옮겨 갔습니다.

코드 리뷰의 두 번째 역할은 늘 코드베이스에 대한 이해를 퍼뜨리는 것이었습니다. 동료의 diff를 읽으면서 무엇이 바뀌었고 각 부분이 어떻게 맞물리는지 배우니까요. 그런데 읽는 일을 대부분 기계가 한다면 코드는 어떻게 익힐까요?
이를 위한 공식 프로세스는 없습니다. 팀에서 Claude Code 전체를 머릿속에 온전히 담고 있는 사람은 없고, 그럴 필요도 없다고 생각합니다. 코드베이스의 특정 부분을 이해하고 싶으면 Claude에게 바로 그 부분만 설명하는 문서를 써 달라고 합니다. 몇 분이면 되고, 지금 시점의 코드를 그대로 반영합니다.

한 걸음 더 나아가, Claude에게 그 코드 영역을 시각화하고 그 사람이 좋아하는 방식으로 가르쳐 주는 작은 결과물을 만들게 하는 사람도 있습니다.
사람의 주의력을 잘 쓰는 것이 목표라면, 사소한 diff를 한 줄씩 읽는 것보다 이 방법이 낫습니다. 한 줄짜리 카피 수정에서는 거의 배울 게 없습니다. 반면 곧 수정할 모듈의 설명 문서에서는 많이 배웁니다. 열린 Slack 채널에서 일하는 것을 기본으로 삼는 문화도 도움이 됩니다. 다른 사람들이 무언가를 만드는 과정을 바로 볼 수 있기 때문입니다.
작은 변경이나 중간 규모 변경을 반영했는데 문제가 생기면 보통 올린 사람이 고치는 것이 팀의 규범입니다. 이것이 나쁜 방향으로 흐르지 않게 하는 장치가 몇 가지 있습니다.
책임은 함께 지기도 합니다. 팀 대부분이 열린 채널에서 일하기 때문에, 누구나 다른 사람이 무엇을 만드는지 보고 이어받거나 Claude에게 빈틈을 메우게 할 수 있습니다. 코드를 맡지 않은 사람에게서도 피드백이 옵니다. 모든 줄에 관문을 두지 않고도 품질을 높게 유지하는 데에는 이런 개방성이 크게 기여합니다.
에이전트 덕분에 작업을 시작하는 비용이 낮아져서, 반영하지 말아야 할 작업도 생깁니다. 보통은 채널의 누군가가 이유를 묻거나, 이전 결정을 짚거나, 더 단순한 방법을 제안하고, 작성자가 PR을 닫거나 방향을 바꿉니다.
코드를 빠르게 썼기 때문에 PR을 닫아도 손해를 본 기분이 들지 않습니다. 요령은 다른 방향을 완성된 PR에 달린 차단성 코멘트가 아니라 스레드에서 일찍 제안하는 것입니다.
팀에서 이를 실현하는 데 필요한 요소는 대부분 지금 이미 있습니다.
CLAUDE.md에 적어 주고, 포매터와 린터를 실행하는 훅도 추가하세요./code-review와 /security-review를 로컬에서 실행하거나, 새 컨텍스트의 서브에이전트 리뷰를 돌리세요.REVIEW.md을 추가하고, 반복되는 리뷰 코멘트를 그 안으로 옮기세요.REVIEW.md을 튜닝한 뒤 범위를 넓히세요.Code Review 출시 발표에서는 풀 리퀘스트를 승인하는 일은 여전히 사람이 판단할 몫이라고 밝혔습니다. 이 제품은 승인이 아니라 지적 사항만 게시합니다. 저희 저장소에서는 한발 더 나아가, 위험도가 낮은 변경 중 어떤 것을 자동 검사만으로 머지할지를 오너가 정하게 하고 있으며, 그 기준선은 계속 움직이고 있습니다.
리뷰가 무언가를 놓치면 모델 앞에 무엇이 없었는지 따져 보고, 그 해법을 CLAUDE.md, 스킬, 또는 새로운 검사에 반영합니다. 목표는 처음부터 같았습니다. 변경당 사람이 쓰는 시간은 줄이되, 리버트는 이전보다 늘지 않게 하는 것입니다.
팀에서 에이전트가 풀 리퀘스트를 열게 하고 있다면, 어떤 검사를 자동화했고 어떤 검사에는 아직 사람이 필요한지, 그리고 저희가 잘못 생각하고 있는 부분은 무엇인지 들려주세요.
리뷰해 주신 Emma Webb, Michael Segner, Amie Rotherham에게 감사드립니다.