Claude Code 팀이 자동화된 검토, 위험 기반 승인, 빠른 롤백을 통해 대규모 코드 검토를 운영하고 개선하는 방법입니다.
앞서 Claude가 Claude Code 코드의 약 90%를 작성한다고 말씀드렸습니다. 그렇다면 이 규모에서 코드 검토는 어떻게 할까요? 어차피 누가 코드를 읽을까요? 코드에 문제가 생기면 어떻게 될까요?
이 글은 Claude Code 팀의 코드 검토 프로세스와 이를 개선해 온 방식을 설명합니다. 6월부터 9월까지 Claude Code 코드베이스에 병합된 풀 리퀘스트 수는 두 배 이상 늘었고, 되돌려야 했던 풀 리퀘스트의 비중은 40% 이상 감소했습니다.
코드 검토를 그만둔 것이 아닙니다. 대신 읽기의 대부분을 자동화하고, 사람의 시간과 노력을 최적화하도록 조정했습니다. 또한 실수를 되돌리는 속도와 편의성을 높이는 데도 상당히 투자했습니다.
에이전트가 코드를 작성하면 변경량은 빠르게 증가합니다. 모노레포에서는 5월에 하루 약 2,500건이 병합되던 변경이 올해 9월에는 하루 30,000건을 넘었습니다.
Claude Code는 모노레포 안에 있지는 않지만, 이 역시 큰 압박을 받고 있습니다. 이 정도로 빠르게 움직이면 코드를 한 줄씩 수동으로 검토하는 일은 점점 더 어려워지고, 결국 불가능해집니다.
코드 검토에는 두 가지 목적이 있습니다.
이 글은 주로 첫 번째 목표에 초점을 맞추지만, 글 마지막 부분에서 두 번째 목표도 다루겠습니다.
우리는 “누군가 코드를 읽었는가?”를 “이 변경에서 무엇이 잘못될 수 있으며, 이를 잡기에 적절한 검사는 자동화 검사인가 사람의 검사인가?”라는 질문의 부정확한 척도로 봅니다.
이 질문은 코드 검토의 시점도 바꾸었습니다. 전통적으로 코드 검토는 코드가 작성되고 PR이 만들어진 뒤 누군가 다른 사람이 봐 주기를 기다리는 사후 검사였습니다. 대신 우리는 코드 검토를 작업 흐름에 통합했습니다. 작성 중에 계속 수행하는 맞춤법 검사에 더 가깝습니다.
대부분의 변경은 사람에게 검토를 요청하기 전에 Claude가 적어도 한 번 검토하고 수정합니다. 이 방식으로 일상적인 버그 대부분을 잡고, 사람의 주의는 더 높은 수준의 고려 사항에 집중시킵니다.
우리는 사람이 처리할 수 있는 일에 사람의 시간과 주의를 남겨 두면서, 나머지를 충분히 포괄할 자동화를 갖추고자 합니다. 현재 속도에서도 사람이 해야 할 일은 여전히 엄청나게 많으며, 팀은 거의 매일 새롭고 낯선 과제에 직면합니다.
이 때문에 사람의 시간은 양면적인 비용입니다. 사람들이 코드 검토에 쓰는 시간뿐 아니라, 나쁜 코드가 유발한 버그를 수정하는 데 쓰는 시간도 셉니다. 첫 번째 시간을 줄이면서 두 번째 시간을 줄이지 못한다면, 실제로 사람의 시간을 절약한 것이 아닙니다.
따라서 우리의 목표는 Claude Code 리포지토리의 풀 리퀘스트 대부분이 되돌림이나 사고 증가 없이, 최대 한 명의 사람이 관여한 상태로 병합되는 것입니다. 그 사람은 작성자일 수도 있습니다. 대상 리포지토리는 CLI, 데스크톱 및 웹 앱, 모바일 앱입니다.
우리는 PR당 사람 승인 수의 중앙값과 95백분위수, 사람의 댓글 수, PR이 사람을 기다리는 시간을 통해 사람의 시간을 추적합니다. 되돌림과 사고 비율은 안전장치로 사용합니다. 이 지표가 늘어난다면 사람의 시간을 줄인 것이 아니라 다른 곳으로 옮겼을 뿐입니다.
엔지니어의 노트북에서 나온 변경이든 Slack의 Claude 세션에서 나온 변경이든, 일반적인 변경은 여러 검토 계층을 거칩니다.
그림 A: 변경의 생애
위 그림은 작성자 환경에서 프로덕션까지 이어지는 전형적인 Claude Code 변경입니다. 이 과정의 대부분은 자동화되어 있고, 사람의 주의는 위험한 부분에 집중됩니다.
우리는 통과한 문제를 처리할 롤백 메커니즘과 함께 여섯 계층의 검사를 운영합니다.
그림 B: 하나의 관문이 아니라 계층
각 계층은 일부 버그를 잡고 다른 버그는 놓칩니다. 모든 계층을 통과하는 버그는 드물며, 그런 버그가 있더라도 롤백 메커니즘이 마련되어 있습니다.
1. PR 전 검증:
검토 대부분은 PR을 만들기 전에 이루어집니다. 우리는 Claude에게 테스트 실행, 빌드 실행, 스크린샷과 디자인 비교처럼 실행 가능한 작업을 하도록 요청합니다. 작업이 끝났다고 말하는 대신 결과를 보여 달라고 요청합니다. 그런 다음 하위 에이전트가 새 맥락에서 diff를 검토합니다. 두 전략 모두 모범 사례 가이드의 일부입니다.
PR을 열기 전에 많은 팀원이 버그 탐색, diff 축소, 엔드투엔드 검증, UI 변경과 디자인 가이드라인 비교 등 몇 가지 내부 스킬도 실행합니다.
Claude Code를 만든 Boris Cherny에 따르면, Claude에 검증 프로세스를 갖추게 하는 것은 더 높은 품질의 결과를 얻는 가장 중요한 열쇠일 가능성이 큽니다.
그는 검증 프로세스가 Claude 출력의 품질을 두세 배 높인다고 추정합니다.
특정 도메인의 검증 프로세스는 매우 다를 수 있습니다.
때로는 bash 명령 하나를 실행하는 것만큼 간단합니다. 때로는 테스트 스위트를 실행합니다. 때로는 브라우저나 휴대폰 시뮬레이터에서 앱을 테스트합니다.
자동 검토기가 같은 문제를 계속 표시한다면, 스킬 자체나 린트 규칙, 또는 다음과 같은 문서 파일을 통해 근본 원인을 수정합니다.
CLAUDE.md -- 프로젝트에 대한 맥락(기술 스택, 관례, 목표, 비목표)을 Claude에게 제공하는 데 쓸 수 있는 프로젝트 설명 파일입니다. Claude Code는 모든 검토에 이 파일을 가져오므로, 큰 코드베이스에서는 짧게 유지하고 나머지 문서를 여기서 참조합니다. 코드가 이 파일의 관례를 어기거나 업데이트로 인해 내용이 오래되면 검토기가 표시합니다.
REVIEW.md -- 코드 소유자가 자신이 담당하는 코드에서 중요한 사항을 검토기에게 알리는 파일입니다. 검토기가 실제로 이 지침을 따르는지도 별도로 검증합니다. 좋은 지침은 짧고 다음에 집중합니다.
프로젝트 실패 정의하기(문서가 거짓말을 해서는 안 됨, 설정이 잘못된 경로로 보내서는 안 됨) 사소한 흠잡기 제한하기 무시할 경로 정의하기 파일명 추측이 아니라 파일과 줄 참조 요구하기 이슈 수와 “문제 없음”이라는 명확한 진술을 포함한 최상위 요약 요구하기
2. 모든 풀 리퀘스트에 대한 AI 검토
모든 PR은 사람의 검토 전에 Claude 검토를 받습니다.
PR 작성자가 밝힌 PR의 의도와 전체 코드베이스를 기준으로 diff를 분석합니다. 다음을 확인합니다. 변경이 실제로 문제를 해결하는지 변경이 더 큰 시스템에 맞는지 변경이 코드베이스의 다른 부분을 망가뜨리지 않는지
버그 수정을 검토할 때 봇은 근본 원인을 찾으려 합니다.
공개 제품인 Claude Code용 코드 검토는 이제 모든 Team 및 Enterprise 고객에게 제공됩니다. 로컬 사용을 위한 더 가벼운 버전인 /code-review도 있습니다.
연구 미리보기를 출시한 뒤, 실질적인 검토 댓글을 받는 내부 PR의 비율은 16%에서 54%로 늘었습니다. 코드 검토는 1,000줄이 넘는 PR 대부분에서 문제를 탐지하고, 더 작은 PR 대부분에는 깨끗한 결과를 반환합니다. 관리자는 리포지토리를 Quick, Standard 또는 Deep 모드로 구성할 수 있습니다. 단 하나의 버그를 놓치는 비용이 코드 검토에 드는 시간보다 큰 경우 Deep이 유용합니다.
사람이 검토하기 전에 여러 다른 에이전트가 발견 사항을 검증합니다.
여러 에이전트가 병렬로 버그를 탐색합니다.
별도의 투표가 발견 사항이 유효한지 오탐인지를 결정하며, 충분한 표를 받은 발견 사항만 확인합니다.
스타일, 진단, 정리 작업에만 관련된 발견 사항은 걸러 냅니다. 이 필터는 배포 전에 자체 PR에서 A/B 테스트했습니다.
남은 발견 사항은 심각도 순서의 인라인 댓글로 제시되며 다음과 같이 표시됩니다.
중요 사소함 기존 항목(따라서 PR이 도입하지 않은 버그 때문에 작성자가 부당한 불이익을 받지 않음)
모든 발견 사항을 처리해야 합니다. 수정하거나 이유를 적어 스레드를 해결해야 합니다. 많은 경우 에이전트가 밤사이에 문제를 수정하므로, 작성자는 이미 한 번 더 검토를 거친 PR로 돌아옵니다.
3. 병합을 막을 수 있는 보안 검토
자동화된 보안 검토도 실행합니다. 코드 검토나 보안 검토에서 열린 발견 사항이 남아 있는 동안에는 어떤 PR도 병합할 수 없습니다. 작성자는 문제를 수정하거나 짧은 이유와 함께 스레드를 닫을 수 있습니다. 이는 오탐을 처리하는 방법입니다.
후속 커밋이 문제를 해결하면 발견 사항은 자동으로 닫힙니다. 오픈 소스 보안 검토 GitHub Action 또는 /security-review 명령으로도 같은 구성을 설정할 수 있습니다. 설정 방법은 Claude Code의 자동화된 보안 검토 가이드를 참고하세요.
4. 병합을 막는 자동 검사
표준 검사: 린트, 타입 검사, 모든 플랫폼의 테스트, 빌드. CI를 확장한 방법은 별도로 소개했습니다. 전형적인 CLI PR에서는 누군가 보기 전에 수십 개의 검사가 실행될 수 있습니다. PR 템플릿에는 변경을 어떻게 테스트했는지와 어떻게 되돌릴지에 대한 질문이 있습니다. Claude가 답할 수 있지만, 이를 검토할 책임은 작성자에게 있습니다.
5. 위험에 따른 사람의 승인
일부 변경은 다른 변경보다 위험합니다. 예를 들어 문서 수정과 자동 업데이터 변경은 다르므로, 서로 다른 수준의 검토가 필요합니다.
그림 C
등급은 작성자가 아니라 변경에 의해 결정됩니다. 분류기가 변경을 기반으로 위험 수준을 정합니다. 또 다른 분류기는 등급상 필요하지 않더라도 특정 변경에 실제로 추가 승인이 필요한지 판단합니다. 소유자가 민감하다고 표시한 모든 항목과 모든 CI 워크플로 파일처럼, 항상 추가 승인이 필요한 경로도 있습니다.
리포지토리의 신뢰 목록에 있는 작성자만 완화된 검토 요건을 받으며, 보통 리포지토리를 소유한 팀이 이에 해당합니다. 나머지는 모두 두 번째 사람의 승인이 필요합니다. 에이전트 승인은 사람 승인으로 계산되지 않습니다. 자동화 검토는 저위험 변경을 통과시킬 수 있지만, 사람이 필요한 경우 사람을 대신할 수는 없습니다.
변경의 작성자가 책임을 지므로, 에이전트가 PR을 작성하면 에이전트 운영자는 항상 필수 검토자 중 한 명으로 계산됩니다. PR 승인은 하나의 커밋에만 유효합니다. 신뢰할 수 없는 새 커밋이 들어오면(예: 에이전트가 무언가를 푸시했거나 누군가 수동으로 병합을 해결한 경우) PR은 다시 승인받아야 합니다.
6. 병합 대기열, 기능 플래그, 단계적 출시
병합 대기열은 변경이 적용된 main에서 모든 검사가 실행되도록 보장합니다. 이는 성공한 두 PR이 병합되어 main이 망가지는 일을 막습니다. 일반적으로 새 기능은 기능 플래그 뒤에서 출시하며, Anthropic 직원이 먼저 접근합니다. 우리는 제품을 광범위하게 사용하므로 사용자보다 먼저 회귀를 발견하는 경우가 많습니다.
공개 출시할 때는 먼저 최신 채널에 변경을 내보내고, 안정 채널은 그 뒤를 따릅니다.
7. 빠른 피드백과 롤백
일부 잘못된 병합은 불가피하게 통과합니다. 이것은 그런 문제를 최대한 빨리 식별하는 데 초점을 둔 최후의 방어선입니다. 기능 플래그 뒤의 변경은 배포 없이 비활성화할 수 있습니다.
Claude Code는 주간 온콜 순환을 운영하며, 모든 사고 검토에는 어떤 계층이 문제를 잡았어야 하는지 되짚어 보는 일이 포함됩니다. 되돌림 및 사고 대시보드를 모니터링하는 것에 더해, 나쁜 병합을 발견하는 일은 여전히 작성자와 온콜 담당자에게 달려 있습니다. 아직 이 지표를 바탕으로 승인 요건을 조정하는 서킷 브레이커 메커니즘은 없지만, 병합에서 사람의 개입을 줄이기 위한 진전을 이루면서 검토하고 있습니다.
한 팀원은 속도를 늦추고 산출량을 줄이면 정확도가 실제로 개선될 수 있다고 언급했습니다. 하지만 이는 주로 전체 작업량이 감소하기 때문입니다. 우리의 우선순위는 문제를 빠르게 식별하고 수정하는 능력을 높이는 데 있습니다.
코드 검토 프로세스는 지속적인 개선의 순환입니다.
사고를 평가 지표로 사용합니다. 팀은 사고를 일으킨 PR, 그에 대한 정방향 수정과 되돌림을 수집하고, 코드베이스를 이해하는 엔지니어에게 각 버그의 위치와 정확성을 검증하게 했습니다. 검토 시스템은 매일 이 모음에 대해 평가됩니다.
그림 D: 사고가 평가 기준이다
모든 사고는 모음에 추가되며, 검토 시스템의 모든 변경은 전체 모음에 대해 평가됩니다.
노이즈를 측정하기 위해 사람의 검토 댓글 반응을 관찰합니다. 버그가 아닌 것을 많이 보고해도 괜찮다면 버그 탐지율은 쉽게 높일 수 있으므로, 이를 규제해야 합니다. 각 검토 댓글을 PR 담당자가 처리한 방식으로 분류합니다. 문제 수정, 거부, 의도된 것임을 명확히 함, 중요하지 않다고 판단함입니다. 또한 깨끗하다고 알고 있는 PR에 검토 시스템을 실행하고, 유해한 변경으로 이어졌을 무언가를 시스템이 얼마나 자주 보고하는지 관찰합니다.
우리가 밝힌 우선순위는 첫째 실제 버그 탐지, 둘째 검토 주기 수 감소입니다.
작성자가 에이전트일 때 검토 댓글을 처리해야 하는 비용은 더 큽니다. 사람이 사소한 지적을 무시하는 데는 1초면 되지만, 에이전트가 이를 처리해야 하면 또 다른 커밋과 또 다른 검토 주기가 발생합니다.
검토 프로세스는 수렴해야 합니다. 에이전트 작성자와 에이전트 검토자가 영원히 순환할 수 있습니다. CLI 프로젝트의 한 PR은 에이전트 작성자와 에이전트 검토자 간의 반복 때문에 밤사이 50회 이상 순환했습니다. 이 순환은 수동으로 멈췄지만, 무기한 계속될 수도 있었습니다.
검토 시스템이 계속 표시한 항목에 git blame을 실행했을 때, 그중 약 59%는 첫 번째 검토 이후 계속 있던 코드였습니다. 본질적으로 검토 시스템은 새 버그를 거의 찾지 못했고, 매 주기마다 이전 버그를 몇 개씩 더 찾았습니다.
각 주기가 다른 버그를 찾을 수 있으므로 기본적으로 여러 검토 주기를 실행하는 습관이 있었고, 이는 문제를 악화했습니다. 고위험 변경에서는 여러 검토 주기를 반복하는 것이 유용할 수 있지만, 모든 PR에 필요하지는 않습니다. 팀은 재현율뿐 아니라 통과까지의 주기 수를 추적하기 시작했고, 재검토를 다음과 같이 업데이트했습니다.
주기 수를 제한합니다. 검토 시스템은 세 주기 후 작성자에게 접근법을 재평가하라고 요청합니다. 초기 주기 후에는 diff만 재검토하도록 제한합니다. 버그 유형을 명시하여 작성자가 한 줄만이 아니라 모두 수정할 수 있게 합니다. 이미 관찰한 문제를 다시 보고하지 않습니다. 검토 에이전트는 밤사이에 현재 코드베이스에서도 실행되어, 과거 버그가 퍼지기 전에 식별하도록 돕습니다.
그림 E: 수렴하는 검토
수렴 도입 이후 내부 풀 리퀘스트당 평균 검토 라운드 수가 감소했습니다.
시니어 엔지니어가 일반적인 오류를 검토하기 위해 작업을 멈추게 하는 일은 그 과정을 자동화하는 것보다 비용이 많이 듭니다. 그래도 사람 검토자는 일부 작업에 필수적입니다.
코드 검토 병목을 해결했다고 주장하는 한 팀도, 올바른 것을 만드는지 확인하기 위해 팀 외부에서 온 변경에는 사람 검토를 수행합니다.
코드 검토는 언제나 코드베이스 변경을 전달하는 이중 목적을 수행했습니다. 동료 변경의 diff를 읽는 것은 사람들이 보통 무엇이 바뀌었는지, 코드베이스가 어떻게 작동하는지를 이해하는 방식입니다. 읽기의 대부분을 기계가 한다면, 코드베이스를 배우는 방식은 무엇이 될까요?
우리는 이를 위한 공식적인 메커니즘이 없습니다. 팀원 누구도 Claude Code 전체의 정신적 모델을 머릿속에 가지고 있지 않으며, 누군가가 그럴 필요가 있다고 생각하지도 않습니다. 대신 누군가 코드베이스의 한 부분을 알고 싶어 하면, Claude에게 바로 그 부분을 설명하는 자료를 생성해 달라고 요청합니다. 몇 분밖에 걸리지 않고 설명 자료는 항상 최신입니다.
그림 F: 기계가 읽기의 대부분을 한다면, 사람은 어떻게 코드를 배우는가?
일부 팀원은 한 단계 더 나아가 Claude에게 이 영역을 시각화하고 선호하는 방식으로 가르치는 작은 결과물을 생성하게 합니다.
이는 사소한 diff를 한 줄씩 읽는 것보다 사람의 주의를 더 잘 집중시키는 방식입니다. 그런 diff는 배우는 것이 매우 적습니다. 예를 들어 한 줄짜리 문구 변경이 그렇습니다. 변경할 모듈에 대한 설명 자료를 만드는 것은 많은 것을 가르쳐 줍니다.
또한 우리는 기본적으로 개방적으로 일하며, 열린 Slack 채널에서 작업하고 다른 사람들이 만드는 것을 만드는 동안 지켜봅니다.
작거나 중간 규모의 변경을 병합한 뒤에도 문제가 생기면, 일반적으로는 직접 수정해야 한다는 기대가 있습니다. 이것이 통제 불능으로 번지지 않는 이유는 몇 가지입니다.
에이전트를 쓰면 새 작업을 시작하는 비용은 낮지만, 때로는 시작하지 말아야 합니다. 이는 보통 채널의 누군가가 제안된 변경이 잘못된 경로라고 지적할 때 발생합니다. 이전 결정을 언급하거나 더 나은 경로를 제안하면, 작성자는 PR을 닫거나 구현을 바꿉니다.
처음부터 코드를 쉽게 작성했기 때문에 PR을 닫아도 손실처럼 느껴지지 않습니다. 핵심은 완성된 PR에 막는 댓글을 남기기 위해 끝까지 기다리는 대신, 스레드 초기에 방향을 전환하는 것입니다.
이 접근법의 구성 요소 대부분은 이미 팀에서 사용할 수 있습니다.
풀 리퀘스트 전
모든 풀 리퀘스트에서
승인
병합 및 병합 후
코드 검토는 최종 승인 결정은 여전히 사람이 내린다는 의도로 발표되었습니다. 제품은 발견 사항을 게시할 뿐입니다. 하지만 자체 리포지토리에서는 더 나아가고 있습니다. 소유자는 자동화 검사가 통과하면 어떤 저위험 변경을 자동으로 병합할 수 있는지 결정합니다. 이 경계는 계속 진화할 것입니다.
그러므로 검토기가 무언가를 놓칠 때마다, 무엇이 모델의 맥락에 없었는지 자문하고 이를 CLAUDE.md 파일, 스킬 또는 새 검사로 바꿉니다. 그리고 목표는 바뀌지 않았습니다. 현재보다 되돌림 비율을 높이지 않으면서 변경당 사람의 노력을 줄이는 것입니다.
에이전트가 풀 리퀘스트를 만들도록 허용하고 계시다면, 어떤 검사를 자동화했는지, 무엇에 사람이 필요한지, 우리가 무엇을 잘못하고 있는지 알려 주세요.
원래 글을 다시 작성하고 Pangram으로 검토했습니다.
