Claude Code 팀의 코드 리뷰 방식: '사람이 읽었는가'를 질문하는 것을 멈추다

원문 기사: How the Claude Code team does code review (claude.dev Blog)

저자: Addy Osmani, Morgan Westlee Lunt, Qing Wang (Anthropic)

공개일: 2026-10-15

TL;DR

Claude Code는 코드의 약 9할을 Claude 자신이 작성하고 있다. 6월부터 9월까지 병합(merged)된 PR은 2배 이상 증가했다. 그럼에도 불구하고, 되돌려진(revert) 비율은 40% 이상 감소했다.

리뷰를 포기한 것은 아니다. 읽는 작업의 대부분을 기계에 맡기고, 사람의 시간을 '최소화해야 할 비용'으로 측정하도록 바꿨다. 가드레일은 되돌려진 비율과 인시던트율 두 가지이다. 인간의 승인은 작성자가 아니라 **변경 내용에서 결정되는 위험 계층(risk layer)**을 통해 0명에서 2명에게 배분된다.

가장 실용적인 것은 에이전트 간 리뷰가 수렴하지 않는 문제에 대한 처방이다. 최대 3라운드까지 진행하고, 두 번째 라운드부터는 차이점만 보고, 같은 지적을 반복하지 않도록 한다. 이를 통해 1라운드로 통과하는 PR이 65%에서 78%로 증가했다.

'사람이 읽었는가'는 모호한 질문이었다

Anthropic의 모노레포(monorepo)에서는 하루에 발생하는 변경량이 5월 약 2,500건에서 9월에는 30,000건을 초과했다. 12배 증가한 것이다. 한 줄씩 사람이 읽는 방식으로는 이 양 앞에서 더 이상 유지될 수 없다.

그렇다면 사람이 읽지 않게 되면 품질은 누가 책임지는가? 기사의 답은 질문 자체를 대체하는 것이었다.

We think "did a human read the code?" is an imprecise proxy for "what could go wrong with this change, and which check—automated or human—is the right one to catch it?"

'사람이 읽었는가?'는 '이 변경으로 무엇이 잘못될 수 있으며, 그것을 어떤 검사(자동화 또는 인간)로 포착하는 것이 올바른가?'에 대한 부정확한 대용 지표에 불과하다는 주장이다. 사람이 읽는 것은 하나의 검사 수단으로 격하되었다.

목적 함수도 명확하게 정의되어 있다. 최소화하는 것은 사람의 시간이다. 여기에는 리뷰에 소요되는 시간과, 나쁜 코드가 망가뜨린 것을 고치는 시간이 모두 포함된다. 한쪽을 줄여서 그만큼이 다른 쪽으로 이동한다면 의미가 없다. 그래서 되돌려진 비율(revert rate)과 인시던트율(incident rate)을 가드레일로 설정했다. 이것들이 올라간다는 것은 사람의 시간을 절약한 것이 아니라, 다른 곳으로 옮겼다는 것만 의미한다.

측정하는 지표는 4가지가 있다.

• PR당 인간 승인 횟수 (중앙값 및 95 퍼센타일)
• 인간 댓글 수
• PR이 사람을 기다리는 시간
• 되돌려진 비율과 인시던트율 (가드레일)

목표는 '대부분의 PR이 작성자 본인을 포함하여 인간 1명 이하로 병합되고, 되돌림도 인시던트도 증가하지 않는 것'이다.

하나의 변경이 통과하는 과정

그림 1 변경의 라이프사이클. 사람이 판단에 개입하는 곳은 마름모꼴의 단 한 지점이며, 그곳에서도 위험도에 따라 인원수가 달라진다.

그림 1에서 가장 눈에 띄는 것은 인간의 개입이 적다는 점이다. 총 9단계 중, 사람이 판단을 내리는 것은 승인(approval) 단계의 단 하나뿐이다. 게다가 그 단계는 변경 내용에 따라 0명으로 통과할 수도 있다.

대신 기계 검사들이 여러 겹으로 쌓여있다. 이 배치에는 의도가 담겨있다.

관문이 아니라, 레이어(Layer)

그림 2 어떤 레이어도 일부를 포착하고, 일부는 놓친다. 모든 레이어를 통과하는 것은 적고, 빠진 부분은 롤백을 받는다.

완벽한 하나의 관문을 만드는 대신, 구멍의 위치가 다른 레이어들을 쌓는다. 이른바 스위스 치즈 모델(Swiss Cheese Model)의 개념이다. 인간의 승인은 이 중 단 한 장에 불과하다. 가장 아래에는 롤백이라는 바닥이 있기 때문에, 위의 레이어가 완벽할 필요는 없다.

PR 이전: '되었습니다'가 아니라 출력을 보여주게 하기

리뷰의 대부분은 PR이 생성되기 전에 끝난다. Claude에게 실행 가능한 것(테스트, 빌드, 디자인과 비교하는 스크린샷)을 전달하고, '완료되었다'고 말하게 하는 대신 그 출력을 보여주도록 한다. 그 후, 새로운 맥락의 서브 에이전트에게 차이점(diff)을 보여준다.

Claude Code의 작성자인 Boris Cherny는 Claude에게 자신의 작업을 검증할 수 있는 수단을 제공하면 최종 결과가 2~3배 좋아진다고 추정한다.

같은 지적이 반복되면, 그 자리에서 고치지 않고 **발생원(source)**을 고친다. 스킬, lint 규칙, 그리고 두 개의 지시 파일이다.

REVIEW.md에 대해서는, 리뷰어가 실제로 그것을 따르고 있는지 별도로 검사하고 있다고 간결하게 쓰여 있다. 지시 파일은 작성한다고 해서 효력이 발생하는 것이 아니라는 전제가 느껴지는 문장이다.

AI 리뷰: 투표로 살아남은 지적만 내보내기

그림 3 지적이 사람에게 도달하기까지. 버릴 수 있는 단계가 2개 있다

연구 프리뷰를 시작했을 때, 실질적인 리뷰 코멘트가 달리는 사내 PR의 비율은 16%에서 54%로 증가했다. 1,000행이 넘는 PR은 대부분 지적이 붙고, 작은 PR은 대부분 아무것도 나오지 않는다.

태그 Pre-existing

이 세밀하다. PR이 가져오지 않은 기존의 버그를, 작성자의 과실로 보이지 않게 하기 위한 라벨이다. 이 구분이 나중에 수렴 문제(convergence problem)를 해결하는 열쇠가 된다.

지적에는 반드시 응답한다. 수정하거나, 이유를 적어 스레드를 닫는다. 보안 리뷰도 마찬가지로, 어느 쪽의 지적이 열려 있는 동안은 병합할 수 없다. 오탐지를 제거하는 방법은 '짧은 이유를 적고 닫기'이며, 이것 또한 기록으로 남는다.

승인 인원은 '누가 작성했는지'에 따라 결정하지 않는다

문서 수정과 자동 업데이트 변경에서는 파괴되었을 때의 피해가 다르다. 그래서 승인 인원수도 바꾼다.

그림 4 주변에는, 세밀하지만 효과적인 규칙들이 여러 개 붙어 있다.

에이전트의 승인은 인간의 승인으로 간주하지 않는다. 자동 리뷰로 낮은 위험의 변경은 통과시킬 수 있어도, 사람이 필요한 자리는 채울 수 없다 -
변경을 지시한 사람이 책임을 진다. 에이전트가 작성한 PR에서는, 에이전트에게 지시한 사람이 필수 리뷰어 1인으로 계산된다. 자신이 직접 한 것과 같은 취급이다 -
승인은 특정 커밋에 대해서만 유효하다. 에이전트의 push나 수동으로 해결한 병합 등, 시스템이 보장할 수 없는 새로운 커밋이 올라오면 승인은 재실시해야 한다. PR 템플릿에는 '어떻게 테스트했는지', '어떻게 되돌릴지' 칸이 있다. Claude가 채워도 좋지만, 서명하는 것은 변경을 요청한 사람이다

사람들이 차이점(diff) 앞에서 모이는 시점을, Anthropic은 모든 PR에서 위험도가 높은 PR에만 남겨두고 있다. 그리고 남긴 승인에는, '누가 책임을 지는지'를 명시하는 규칙을 세밀하게 붙이고 있다. 합의 자체를 없앤 것이 아니다. 합의가 필요한 장소를 좁힌 것이다.

하루 30,000건 규모에서는, '사람들끼리 이야기하면 모인다'는 전제로는 불가능하다. 작성자와 승인자, 지시자를 커밋 단위로 기록에 남기는 시스템이 필요하다. CI 워크플로우나 자동 업데이트는, 고장 나면 모든 사용자에게 영향을 미친다. PR은 읽기 위한 장소로 가벼워졌지만, '책임의 원장(ledger)'으로서의 역할은 오히려 무거워지고 있다.

리뷰어 자신을 어떻게 개선할 것인가

리뷰하는 AI는, 그 자체로 개선되어 가는 제품으로 취급되고 있다.

그림 5 인시던트가 그대로 평가가 된다. 평가 세트는 사고가 발생할 때마다 자라난다

버그를 많이 찾는 것은 쉽다. 버그가 아닌 것도 신경 쓰지 않고 지적하면 된다. 그래서 잡음(noise)도 측정하고 있다. 측정 방식은, 사람이 그 코멘트에 어떻게 반응했는지에 따라 분류하는 것이다. 수정했다, 틀렸다고 말했다, 의도된 동작이라고 말했다, 신경 쓰지 않았다,의 4가지. 여기에 더해, 깨끗하다고 알려진 PR에 리뷰어를 돌려보내, 누군가에게 유해한 변경을 시킬 수 있는 지적을 얼마나 내놓는지를 센다.

잡음에는, 작성자가 에이전트일 경우 발생하는 비용(cost)이 붙는다.

Noise costs more when the author is an agent. A person can wave off a nit in seconds. An agent fixes it, which means another commit and another round of review.

인간이라면 수 초 만에 넘어갈 사소한 지적을 에이전트는 꼼꼼하게 고친다. 고치면 커밋(commit)이 늘어나고, 커밋이 늘어나면 또 다른 리뷰 라운드가 발생한다.

에이전트 간의 리뷰는 방치하면 끝나지 않는다

한 CLI의 PR은 하룻밤 사이에 50라운드 이상의 리뷰와 수정을 거쳤고, 작성자가 이를 인지하고 중단시켰다.

리뷰어가 반복적으로 지적했던 부분에 git blame을 적용해 본 결과, 약 59%는 리뷰어가 처음 봤을 때부터 그 자리에 있던 코드였다. 새로운 버그를 발견한 것이 아니었다. 오래된 버그를 라운드별로 조금씩 많이 발견했을 뿐이다.

게다가 원인의 일부는 자신들의 습관이었다. 매번 무언가 새로운 것을 발견하기 때문에, 몇 라운드를 돌리는 것이 당연하게 여겨지고 있었다. 리스크가 높은 변경이라면 그것도 가치가 있다. 하지만 모든 PR에서 할 필요는 없다.

해결책은 4가지다.

• 라운드 상한선 설정. 3라운드를 초과하면, 리뷰어는 작성자에게 한발 물러나 방식 자체를 다시 생각하도록 요청하고, 처음 몇 번의 라운드가 지난 후에는 차이점(diff)만 재검토한다.
• 버그의 '종류' 지적. 1줄이 아니라 같은 종류의 모든 부분을 고치게 한다. 이미 제시한 지적을 반복하지 않는다.

여기에 더해, 기존 코드에 야간 리뷰 에이전트를 돌려 오래된 버그를 PR 외부에서 포착하도록 했다. 이를 통해 59%의 기존 버그를 PR 리뷰 과정에서 분리시킨 것이다.

지표를 측정하는 방식도 바뀌었다. 재현율(recall)과 나란히 통과까지 걸리는 라운드 수를 추적하게 되었다. 우선순위는 문서로 명시되어 있으며, 1순위가 실제 버그 포착이고, 2순위가 리뷰 왕복 횟수 감소이다.

인간에게 남은 5가지 판단

자동 체크가 한 바퀴 돌고 나면, 사람의 역할은 '모든 차이점을 읽는 것'에서 기계가 취약한 5가지 판단으로 이동했다.

네 번째 '증거를 읽기' 항목의 한 문장이 까다롭다. 체크가 무엇을 놓칠 수 있는지 말할 수 없다면, 대충 승인하지 말고 제대로 된 리뷰를 요청하라. 승인하는 사람에게 요구되는 것은 코드를 읽는 능력보다 체크의 허점을 지적할 수 있는 힘이다.

첫 번째 항목에는 원문 기사에서 가장 시사적인 사례가 붙어 있다. 리뷰의 병목 현상은 해결되었다고 선언한 팀이, 팀 외부로부터의 변경에만 인간의 리뷰를 남겼다. 누군가가 '애초에 이것을 할 필요가 있는지' 질문하기 위해서이다. 기계는 버그를 찾을 수는 있어도, 만들지 말아야 할 것을 막는 것은 서툴다.

읽지 않는다면, 어떻게 코드를 익히는가

리뷰의 또 다른 역할은 코드베이스에 대한 이해도를 팀 전체에 확산시키는 것이었다. 기계가 읽는다면, 사람은 어디서 배울까?

기사의 답은 솔직하다. 정식 프로세스는 없다. Claude Code 전체의 머릿속 모델을 가진 사람도 없고, 가질 필요도 없다고 생각한다. 이해하고 싶은 부분이 생기면, 그 부분만에 대한 설명을 Claude에게 작성하게 한다. 몇 분이면 충분하며, 오늘 코드를 반영하고 있다. 어떤 사람은 그 부분을 시각화하여 자신이 좋아하는 학습 방식으로 설명하는 작은 아티팩트까지 만들게 한다.

1줄의 문구 수정만 읽어서는 거의 아무것도 배울 수 없다. 앞으로 다룰 모듈에 대한 설명을 읽는 편이 훨씬 많은 것을 배울 수 있다. 돌이켜보면, 리뷰를 통해 지식이 확산되는 것은 원래 효율적이지 못한 부산물이었다.

'넣은 사람이 가진 것'을 가능하게 하는 것

소~중규모의 변경으로 인해 무언가 고장 나면, 대부분 넣은 사람이 고친다. 이것이 팀의 규범이 되었다. 하지만 규범만으로는 돌아가지 않는다. 5가지 하부 구조가 있다.

• 변경 사항이 작다. 리뷰도, 디버깅도, 되돌리기(revert)도 쉽다.
• 모든 것이 복구 가능하다. 플래그(flag), 되돌리기, 단계적 출시를 통해 대부분의 실패는 몇 분 안에 취소할 수 있다.
• 피해 범위가 기준을 정한다. 비용이 많이 드는 코드일수록 사람과 검토가 늘어난다.
• 원격 측정(telemetry) 및 사내 사용으로 성능 저하가 즉시 드러난다.
• 비난하는 시스템이 아니다. 고치는 사람이 가장 많은 맥락을 가지고 있기 때문에 고친다. 인시던트 리뷰는 시스템 자체를 본다.

방향 전환의 처리도 같은 전제 위에 있다. 에이전트로 시작하는 것이 저렴해진 만큼, 들어갈 필요가 없는 작업도 생겨난다. 누군가가 채널에서 '왜?'라고 물으며 이전 결정을 지적하고 더 쉬운 길을 제시한다. 작성하는 속도가 빨랐기 때문에 PR(Pull Request)를 닫아도 손해 본 느낌이 들지 않는다. 요령은 완성된 PR에 코멘트를 다는 것이 아니라, 스레드의 초기에 다른 방향을 제안하는 것이다.

내일부터 따라 하려면

원문 기사 마지막에는 도입 절차가 단계별로 나열되어 있다. 전부를 한 번에 할 필요는 없다. 단계별로 효과적인 것 2~3가지로 추릴 수 있다.

읽는 사람이 사라진 것은 아니다

서두의 질문으로 돌아가 보자. 사람들이 안 본다면, 품질은 누가 책임지는가?

답변은 두 가지로 나뉘었다. 발견하는 일은 계층에 분배되었다. PR 전 검증, AI 리뷰, 보안, CI(지속적 통합), 머지 큐(merge queue), 그리고 최후의 방어선으로서의 롤백이다. 책임을 지는 일은 사람에게 남겨졌다. 지시한 사람, 위험도가 높은 변경을 승인하는 사람, 증거를 읽고 검토의 허점을 말할 수 있는 사람이다.

코드를 한 줄씩 읽는 사람은 줄었다. 하지만 어떤 검사가 무엇을 놓칠지 읽는 사람은 오히려 전보다 더 필요해지고 있다. 원문 기사 마지막은 우리 자신들의 어디가 잘못되었다고 생각하는지 알려달라는 요청으로 끝난다. 제로인 머지(zero-man merge) 라인이 얼마나 작동할지는 아직 아무도 모른다.

참고

• How the Claude Code team does code review (claude.dev Blog, 2026-10-15)

Discussion