글을 삭제하시겠습니까?

삭제한 글은 복구할 수 없습니다.

Claude Code 팀은 코드 리뷰를 어떻게 하는가

작성일:2026.11.14|수정일:2026.11.14|조회수:28

Claude Code 팀은 코드 리뷰를 어떻게 하는가

이 포스트는 Google에서 Chrome 개발자 경험을 이끌었으며 현재 Anthropic에서 Claude Code를 개발하고 있는 애디 오스마니(Addy Osmani)가 자신의 트위터에 올린 How the Claude Code team does code review 게시글을 번역한 것이다. 번역하는 과정에서 다소 의역이 있을 수 있으며, 일부 번역에는 사견이 포함되어있기도 하다.

앞서 우리는 Claude Code 코드의 약 90%를 Claude가 작성한다고 언급했다. 그렇다면 이 정도 규모에서 코드 리뷰는 어떻게 할까? 코드는 대체 누가 읽을까? 코드에 문제가 생기면 어떻게 될까?

이 글에서는 Claude Code 팀의 코드 리뷰 프로세스와 그 프로세스를 어떻게 개선해 왔는지 설명한다. 6월부터 9월 사이 Claude Code 코드베이스에 머지된 pull request 수는 두 배 이상 늘었지만, 되돌려야 했던 pull request의 비율은 40% 넘게 줄었다.

코드 리뷰를 그만둔 것은 아니다. 대신 코드를 읽는 작업 대부분을 자동화하고, 사람의 시간과 노력을 최적화하도록 조정했다. 실수를 더 빠르고 간편하게 되돌리는 데도 상당한 투자를 했다.

코드 리뷰의 목표 다시 생각하기

에이전트가 코드를 작성하면 변경 사항의 양이 빠르게 늘어난다. 우리 모노레포에 머지되는 변경 사항은 올해 5월 하루 약 2,500건에서 9월 30,000건 이상으로 늘었다.

Claude Code는 이 모노레포에 들어 있지 않지만, Claude Code에도 상당한 압력이 가해진다. 이처럼 빠르게 움직이면 코드를 한 줄씩 수동으로 리뷰하기가 갈수록 어려워지고, 결국에는 불가능해진다.

코드 리뷰에는 두 가지 목적이 있다.

  1. 출시 전에 버그를 발견하고 수정한다.
  2. 코드베이스에 관한 공통된 이해를 만든다.

이 글은 주로 첫 번째 목적을 다루지만, 두 번째 목적은 글의 뒷부분에서 살펴본다.

우리는 “누군가 코드를 읽었는가?”라는 질문이 “이 변경으로 무엇이 잘못될 수 있으며, 이를 잡아내는 데 알맞은 검사는 자동 검사와 사람의 검사 중 무엇인가?”를 정확하지 않게 측정하는 방식이라고 본다.

이 질문은 코드 리뷰의 시점도 바꿨다. 전통적으로 코드 리뷰는 코드 작성과 PR 등록이 끝난 뒤, 누군가 다른 사람이 살펴보기를 기다리며 사후에 수행하는 검사였다. 우리는 그 대신 코드 리뷰를 워크플로에 통합했다. 글을 쓰는 동안 계속 맞춤법을 검사하는 것에 더 가깝다.

대부분의 변경 사항은 사람이 살펴보기 전에 이미 Claude의 리뷰와 수정을 적어도 한 번 거친다. 이렇게 일상적인 버그 대부분을 잡아내고, 사람의 주의는 더 높은 수준의 고려가 필요한 부분에 남겨 둔다.

사람의 시간과 주의

나머지를 처리할 만큼 충분히 자동화하면서, 사람의 시간과 주의는 사람만 다룰 수 있는 일에 쓰고 싶다. 지금 속도에서도 사람이 해야 할 일은 엄청나게 많고, 우리 팀은 거의 매일 새롭고 낯선 문제를 만난다.

이런 이유로 사람의 시간은 양쪽에서 발생하는 비용이다. 사람이 코드 리뷰에 쓰는 시간뿐 아니라 잘못된 코드가 일으킨 버그를 수정하는 데 쓰는 시간도 계산해야 한다. 첫 번째 시간을 줄이면서 두 번째 시간을 줄이지 못한다면, 사람의 시간을 실제로 절약한 것이 아니다.

따라서 우리의 목표는 Claude Code 저장소(CLI, 데스크톱 및 웹 앱, 모바일 앱)에 올라오는 pull request 대부분을 되돌리기나 인시던트의 증가 없이, 최대 한 사람만 루프에 참여한 상태로 머지하는 것이다. 그 한 사람은 작성자일 수도 있다.

사람이 쓴 시간은 PR당 사람 승인 수의 중앙값(95번째 백분위수도 함께 본다), 사람이 남긴 댓글 수, PR이 사람을 기다린 시간으로 추적한다. 되돌리기와 인시던트 비율은 가드레일로 사용한다. 이 지표가 증가한다면 사람의 시간을 줄인 것이 아니라 다른 곳으로 옮긴 것일 뿐이다.

변경 사항은 어떤 여정을 거치는가?

일반적인 변경 사항은 엔지니어의 노트북에서 시작하든 Slack의 Claude 세션에서 시작하든 여러 겹의 리뷰를 거친다.

FIG A: 변경 사항의 생애

위 그림은 작성자의 환경에서 프로덕션에 이르기까지 Claude Code 변경 사항이 일반적으로 거치는 과정을 보여준다. 이 프로세스 대부분은 자동화되어 있고, 사람의 주의는 위험한 부분에 집중된다.

우리에게는 여섯 겹의 검사와, 그 검사를 통과한 문제를 처리하기 위한 롤백 메커니즘이 있다.

FIG B: 하나의 게이트가 아닌 여러 겹

각 계층은 일부 버그를 잡아내지만 다른 버그는 놓친다. 모든 계층을 빠져나가는 버그는 거의 없으며, 그런 버그가 생기더라도 롤백 메커니즘이 준비되어 있다.

1. PR 전 검증

리뷰 대부분은 PR을 만들기 전에 진행한다. 테스트나 빌드를 실행하거나 스크린샷을 디자인과 비교하는 것처럼, 실제로 실행해 볼 수 있는 일을 Claude에게 요청한다. 작업이 끝났다고 말하는 대신 결과를 보여 달라고 한다. 그런 다음 서브에이전트가 새로운 맥락에서 diff를 리뷰한다. 이 두 전략은 모두 우리의 모범 사례 가이드에 포함되어 있다.

PR을 열기 전에 팀원 다수는 버그 찾기, diff 줄이기, 엔드투엔드 검증, UI 변경 사항이 디자인 가이드라인에 맞는지 확인하기 같은 몇 가지 내부 스킬도 실행한다.

Claude Code를 만든 Boris Cherny에 따르면, Claude에 검증 프로세스를 갖추게 하는 것이 결과물의 품질을 높이는 가장 중요한 열쇠일 가능성이 크다.

그는 검증 프로세스가 Claude 결과물의 품질을 두 배에서 세 배까지 높인다고 추정한다.

각 도메인의 검증 프로세스는 크게 다를 수 있다.

bash 명령 하나를 실행하는 것으로 끝날 때도 있고, 테스트 스위트를 실행할 때도 있다. 브라우저나 휴대전화 시뮬레이터에서 앱을 테스트할 때도 있다.

자동 리뷰어가 같은 문제를 계속 지적한다면, 스킬 자체나 린트 규칙을 고치거나 다음과 같은 문서 파일을 업데이트해 문제의 근원을 바로잡는다.

CLAUDE.md — Claude에 프로젝트의 기술 스택, 규칙, 목표, 목표가 아닌 것 같은 맥락을 제공하는 데 사용하는 프로젝트 설명 파일이다. Claude Code는 모든 리뷰에서 이 파일을 불러오므로, 큰 코드베이스에서는 짧게 유지하고 나머지 문서는 여기에서 참조한다. 코드가 이 파일의 규칙을 어기거나 업데이트로 파일 내용이 낡게 되면 리뷰어가 이를 지적한다.

REVIEW.md — 코드 소유자가 코드베이스에서 자신이 맡은 부분의 무엇이 중요한지 리뷰어에게 알려 주는 파일이다. 리뷰어가 이 가이드라인을 실제로 따르는지도 별도로 검증한다. 좋은 REVIEW.md는 짧으며 다음에 초점을 맞춘다.

2. 모든 pull request에 적용하는 AI 리뷰

모든 PR은 사람이 리뷰하기 전에 Claude의 리뷰를 받는다.

PR 작성자가 명시한 PR의 의도를 바탕으로, 전체 코드베이스와 대조해 diff를 분석한다. 다음을 검사한다.

버그 수정을 리뷰할 때 봇은 근본 원인을 찾으려 한다.

공개 제품인 Code Review for Claude Code는 이제 모든 Team 및 Enterprise 고객이 사용할 수 있다. 로컬에서 사용할 수 있는 더 가벼운 버전인 /code-review도 있다.

연구 프리뷰를 출시한 뒤, 실질적인 리뷰 댓글을 받은 내부 PR의 비율은 16%에서 54%로 늘었다. Code Review는 1,000줄이 넘는 PR 대부분에서 문제를 발견하고, 그보다 작은 PR 대부분에는 문제가 없다는 결과를 반환한다. 관리자는 저장소가 Quick, Standard, Deep 모드를 사용하도록 설정할 수 있다. 버그 하나를 놓치는 비용이 코드 리뷰에 쓰는 시간보다 큰 경우에는 Deep이 유용하다.

사람이 리뷰하기 전에 여러 다른 에이전트가 발견 사항을 검증한다.

남은 발견 사항은 심각도순으로 정렬된 인라인 댓글로 표시되며, 다음과 같이 분류한다.

모든 발견 사항을 처리해야 한다. 문제를 수정하거나, 이유를 남기고 스레드를 해결해야 한다. 많은 경우 에이전트가 밤사이에 문제를 수정하므로, 작성자가 돌아왔을 때 PR은 이미 한 차례 더 리뷰를 마친 상태다.

3. 머지를 막을 수 있는 보안 리뷰

자동 보안 리뷰도 실행한다. 코드 리뷰나 보안 리뷰에서 아직 해결되지 않은 발견 사항이 있으면 어떤 PR도 머지할 수 없다. 작성자는 문제를 수정하거나 짧은 이유를 남기고 스레드를 닫을 수 있다. 후자는 오탐을 처리하는 방법이다.

뒤이은 커밋에서 문제를 해결하면 발견 사항은 자동으로 닫힌다. 오픈 소스 보안 리뷰 GitHub Action이나 /security-review 명령으로 같은 방식을 설정할 수 있다. 설정 방법은 Claude Code의 자동 보안 리뷰 가이드를 참고한다.

4. 머지를 막는 자동 검사

표준 검사에는 린트, 타입 검사, 모든 플랫폼의 테스트, 빌드가 포함된다. CI를 확장한 방법은 이전 글에서 다뤘다. 일반적인 CLI PR 하나에도 누군가가 살펴보기 전에 수십 개의 검사가 실행될 수 있다. PR 템플릿에는 변경 사항을 어떻게 테스트했고 어떻게 되돌릴 것인지 묻는 질문이 있다. Claude가 이 질문에 답할 수 있지만, 그 답을 검토할 책임은 작성자에게 있다.

5. 위험에 따라 확장되는 사람의 승인

어떤 변경 사항은 다른 변경 사항보다 위험하다. 예를 들어 문서 수정과 자동 업데이터 변경의 위험은 다르므로, 서로 다른 수준의 리뷰가 필요하다.

FIG C

등급은 작성자가 아니라 변경 사항에 따라 결정된다. 한 분류기가 변경 사항을 바탕으로 위험 수준을 정한다. 다른 분류기는 등급상 필요하지 않더라도 특정 변경 사항에 실제로 추가 승인이 필요한지 판단한다. 소유자가 민감한 것으로 표시한 모든 항목과 모든 CI 워크플로 파일처럼, 언제나 추가 승인이 필요한 경로도 있다.

완화된 리뷰 요건은 저장소의 신뢰 목록에 있는 작성자에게만 적용되며, 대개 그 저장소를 소유한 팀이 이에 해당한다. 그 밖의 작성자는 모두 두 번째 사람의 승인을 받아야 한다. 에이전트의 승인은 사람의 승인으로 계산하지 않는다. 자동 리뷰는 위험이 낮은 변경 사항을 통과시킬 수 있지만, 사람의 승인이 필요할 때 그 승인을 대신할 수는 없다.

변경 사항의 작성자가 그 변경 사항을 책임진다. 따라서 에이전트가 PR을 작성했다면 에이전트 운영자는 항상 필수 리뷰어 중 한 명으로 계산된다. PR 승인은 커밋 하나에만 유효하다. 신뢰할 수 없는 새 커밋이 들어오면, 예를 들어 에이전트가 무언가를 푸시했거나 누군가가 머지를 수동으로 해결했다면 PR을 다시 승인해야 한다.

6. 머지 큐, 기능 플래그, 단계적 롤아웃

머지 큐는 변경 사항이 적용된 main에서 모든 검사가 실행되도록 보장한다. 성공한 PR 두 개를 머지한 결과 main이 망가지는 일을 막는다. 일반적으로 새 기능은 기능 플래그 뒤에서 롤아웃하며, Anthropic 직원에게 먼저 접근 권한을 준다. 우리가 제품을 폭넓게 사용하기 때문에 사용자보다 먼저 회귀를 알아차리는 경우가 많다.

공개 롤아웃을 시작할 때는 변경 사항을 latest 채널에 먼저 배포하고 stable 채널은 그보다 늦게 따라간다.

7. 빠른 피드백과 롤백

잘못된 머지 중 일부는 필연적으로 모든 방어선을 통과한다. 마지막 방어선은 이런 머지를 가능한 한 빨리 찾아내는 데 초점을 맞춘다. 기능 플래그 뒤에 있는 변경 사항은 배포 없이 비활성화할 수 있다.

Claude Code는 주간 온콜 로테이션을 운영하며, 모든 인시던트 리뷰에서는 어떤 계층이 그 문제를 잡았어야 하는지 되짚어 본다. 되돌리기와 인시던트 대시보드를 모니터링하는 것과 더불어, 잘못된 머지를 발견하는 일은 여전히 작성자와 온콜의 몫이다. 아직 이 지표에 따라 승인 요건을 조정하는 서킷 브레이커 메커니즘은 없지만, 머지에 사람이 덜 개입하는 방향으로 나아가면서 검토하고 있다.

한 팀원은 속도를 늦추고 결과물의 양을 줄이면 실제로 정확도가 높아질 수 있다고 지적했다. 하지만 이는 대부분 전체 작업량이 줄기 때문이다. 우리가 정말 우선하는 것은 문제를 빠르게 발견하고 바로잡는 능력을 높이는 일이다.

리뷰어를 개선하는 방법

우리의 코드 리뷰 프로세스는 계속되는 개선의 순환이다.

인시던트를 평가 지표로 사용한다. 팀은 인시던트를 일으킨 PR과 그에 대한 후속 수정 및 되돌리기를 수집했고, 코드베이스를 이해하는 엔지니어가 각 버그의 위치와 정확성을 검증하도록 했다. 리뷰 시스템은 매일 이 모음을 기준으로 평가된다.

FIG D: 우리의 인시던트가 곧 평가다

모든 인시던트가 이 모음에 추가되고, 리뷰 시스템을 변경할 때마다 전체 모음을 기준으로 평가한다.

노이즈를 측정하기 위해 사람이 리뷰 댓글에 어떻게 반응하는지 관찰한다. 버그가 아닌 것을 많이 보고해도 괜찮다면 버그 발견률을 높이는 것은 어렵지 않으므로, 이를 통제해야 한다. PR 담당자가 각 리뷰 댓글을 어떻게 처리했는지에 따라 분류한다. 문제를 수정했는지, 거부했는지, 의도한 동작이라고 설명했는지, 중요하지 않다고 판단했는지를 본다. 또한 문제가 없다고 알고 있는 PR에도 리뷰 시스템을 실행하고, 시스템의 보고에 따라 수정했다면 오히려 해로운 변경이 되었을 항목을 얼마나 자주 보고하는지 관찰한다.

우리가 명시한 우선순위는 첫째, 실제 버그를 발견하는 것이고 둘째, 리뷰 주기의 횟수를 줄이는 것이다.

작성자가 에이전트라면 리뷰 댓글을 처리하는 비용이 더 크다. 사람은 사소한 지적을 무시하는 데 1초밖에 걸리지 않지만, 에이전트가 이를 처리해야 하면 또 다른 커밋과 또 다른 리뷰 주기가 생긴다.

리뷰 프로세스는 반드시 수렴해야 한다. 에이전트 작성자와 에이전트 리뷰어가 영원히 순환할 수도 있다. CLI 프로젝트의 한 PR에서는 에이전트 작성자와 에이전트 리뷰어가 계속 의견을 주고받느라 밤사이 50회 넘게 순환하는 일이 있었다. 이 순환은 수동으로 멈췄지만, 그러지 않았다면 무한히 계속될 수도 있었다.

리뷰 시스템이 계속 지적한 부분에 git blame을 실행해 보니, 약 59%는 첫 번째 리뷰 때부터 존재했던 코드였다. 사실상 리뷰 시스템은 새 버그를 거의 찾지 못하면서, 주기마다 오래된 버그를 몇 개씩 더 발견하고 있었다.

각 리뷰 주기에서 서로 다른 버그를 찾을 수 있다는 이유로 기본적으로 여러 번의 리뷰를 실행하는 습관이 생겼고, 이 때문에 문제가 더 심해졌다. 위험이 큰 변경 사항에는 여러 번 리뷰를 반복하는 것이 유용할 수 있지만 모든 PR에 필요한 것은 아니다. 우리 팀은 재현율과 함께 통과하기까지 걸린 주기 수를 추적하기 시작했고, 재리뷰 방식을 다음과 같이 바꿨다.

FIG E: 수렴하는 리뷰

Convergence 적용 후 내부 pull request당 평균 리뷰 횟수가 감소했다.

루프 안의 사람

고위 엔지니어가 하던 일을 멈추고 흔한 오류를 리뷰하게 하는 것은 같은 프로세스를 자동화하는 것보다 비용이 크다. 하지만 다음 작업에는 여전히 사람 리뷰어가 꼭 필요하다.

코드 리뷰 병목을 해결했다고 말하는 한 팀도 팀 외부에서 들어온 변경 사항에 대해서는 그것이 정말 만들어야 할 올바른 것인지 확인하기 위해 여전히 사람이 리뷰한다.

팀 맥락

코드 리뷰는 언제나 코드베이스의 변경 사항을 전달하는 두 번째 목적도 맡아 왔다. 보통 사람들은 동료가 만든 변경 사항의 diff를 읽으며 무엇이 바뀌었고 코드베이스가 어떻게 동작하는지 이해한다. 읽는 일 대부분을 기계가 한다면, 코드베이스를 배우는 방법은 무엇이 될까?

이를 위한 공식적인 메커니즘은 없다. 팀원 누구도 Claude Code 전체에 관한 멘탈 모델을 머릿속에 담고 있지 않으며, 그럴 필요가 있다고도 생각하지 않는다. 대신 코드베이스의 일부를 배우고 싶을 때마다 Claude에게 바로 그 부분에 관한 해설을 생성해 달라고 요청한다. 몇 분밖에 걸리지 않고 해설은 언제나 최신 상태다.

FIG F: 읽는 일 대부분을 기계가 한다면, 사람은 코드를 어떻게 배우는가?

우리 중 일부는 한 걸음 더 나아가 Claude가 해당 영역을 시각화하고 자신이 선호하는 방식으로 가르쳐 주는 작은 아티팩트를 생성하도록 한다.

이는 배울 것이 거의 없는 사소한 diff, 예를 들어 한 줄짜리 문구 변경을 한 줄씩 읽는 것보다 사람의 주의를 집중하는 더 나은 방법이다. 변경하려는 모듈의 해설을 만들면 훨씬 많은 것을 배울 수 있다.

게다가 우리는 대체로 기본적으로 공개된 방식으로 일한다. 열린 Slack 채널에서 작업하며 다른 사람이 무언가를 만드는 과정을 지켜본다.

“머지했다면, 책임진다”

작거나 중간 규모의 변경 사항을 머지한 뒤에도 문제가 생긴다면, 일반적으로 자신이 직접 고치기를 기대한다. 이 방식이 통제 불능으로 치닫지 않는 데에는 몇 가지 이유가 있다.

방향 전환

에이전트를 사용하면 새 작업을 시작하는 비용이 낮지만, 시작하지 말아야 할 때도 있다. 보통 채널의 누군가가 이전 결정을 인용하거나 더 나은 경로를 제안하면서, 제안된 변경 사항이 잘못된 방향이라고 지적할 때 이런 일이 생긴다. 그러면 작성자는 PR을 닫거나 구현을 바꾼다.

애초에 코드를 작성하기가 쉬웠기 때문에 PR을 닫아도 손실처럼 느껴지지 않는다. 중요한 것은 완성된 PR에 마지막 순간 차단 댓글을 남길 때까지 기다리지 않고, 스레드 초반에 방향을 전환하는 것이다.

구현 방법

이 접근 방식의 구성 요소 대부분은 이미 여러분의 팀에서도 사용할 수 있다.

Pull request 전

모든 pull request에서

승인

머지 및 머지 후

앞으로 나아갈 방향

Code Review를 발표할 때는 최종 승인 결정을 여전히 사람이 내릴 것이라고 밝혔다. 제품이 하는 일은 발견 사항을 게시하는 것뿐이다. 하지만 우리 저장소에서는 더 나아가고 있다. 소유자가 자동 검사를 통과하면 자동으로 머지할 수 있는 저위험 변경 사항을 정하고 있다. 그리고 이 경계는 계속 달라질 것이다.

따라서 리뷰어가 무언가를 놓칠 때마다 모델의 맥락에 무엇이 없었는지 묻고, 그 답을 CLAUDE.md 파일이나 스킬, 새로운 검사로 만든다. 우리의 목표는 바뀌지 않았다. 되돌리기 비율을 지금보다 높이지 않으면서 변경 사항 하나에 드는 사람의 노력을 줄이는 것이다.

여러분도 에이전트가 pull request를 만들도록 허용하고 있다면, 어떤 검사를 자동화했고 무엇에 사람이 필요하며 우리가 무엇을 잘못 이해하고 있는지 알려 주기 바란다.

기존 글을 다시 쓴 글이며 Pangram으로 확인했다.

댓글

댓글을 삭제하시겠습니까?

삭제한 댓글의 내용은 복구할 수 없습니다.

댓글을 불러오는 중...