Claude Code 팀의 코드 리뷰 방식: 일곱 단계, 서킷 브레이커 없음

2026년 10월 15일, Claude Code 팀은 자사가 코드를 검토하는 방식을 직접 설명한 글을 발표했다. Addy Osmani, Morgan Westlee Lunt, Qing Wang의 이름으로 올라온 14분 분량의 엔지니어링 글이다. 누군가 이 글을 검색하는 이유를 설명해 주는 문장은 글 초반에 등장한다. Claude는 Claude Code 자체 코드의 약 90퍼센트를 작성한다. 이 글은 그 수치를 옹호하는 글이 아니라, 그 수치가 감당 가능해지기 전에 그 밑에 존재해야 했던 장치들을 설명하는 글이다. 그리고 자세히 읽을 가치가 있는 부분은 아직 빠져 있는 부분들이다.

대부분의 요약은 두 가지 핵심 수치에서 멈춘다. 2026년 6월과 9월 사이 Claude Code 코드베이스에 병합된 풀 리퀘스트는 두 배 이상 늘었고, 되돌려야 했던 비율은 40퍼센트 넘게 줄었다. 둘 다 팀 자체에서 나온 수치이며, 둘 다 여러 가지 다른 방식으로도 나올 수 있다. 사람들이 흔히 가정하는 방식, 즉 리뷰가 조용히 사라졌다는 경우도 포함해서다. 글은 그렇지 않다고 말한다. 팀은 읽기 작업 대부분을 기계로 옮기고, 사람의 시간과 주의력에 맞춰 최적화했으며, 실수를 빠르고 쉽게 되돌릴 수 있게 하는 데 투자했다. 나머지는 그 방법에 관한 세부 사항일 뿐이다.

왜 검토가 애초에 병목이 되었는가

그 압박은 정책 결정에서 비롯된 것이 아니었다. 그것은 물량에서 비롯되었다. 그 글에 따르면 Anthropic의 모노레포에서는 하루에 반영되는 변경 사항이 2026년 5월 약 2,500건에서 2026년 9월 30,000건 이상으로 늘었다. Claude Code는 그 모노레포와 별도로 자체 저장소에 있지만, 더 작은 규모로 같은 압박을 받고 있다.

그런 식이라면, 그 게시물은 수작업으로 한 줄 한 줄 검토하는 것이 불가능하지는 않더라도 믿을 수 없을 만큼 어렵다고 인정한다. 그곳에서 누구도 모든 diff를 사람이 읽는 것이 불필요하다고 주장하지는 않는다. 그들은 모든 diff를 읽는 것이 더 이상 확장되지 않는다고 주장하며, “사람이 코드를 읽었는가”는 항상 중요한 질문, 즉 이 변경으로 무엇이 잘못될 수 있으며, 자동이든 사람이든 어떤 검사가 그것을 잡아내기에 적합한 검사인가에 대한 부정확한 대리 지표였다고 말한다.

그렇게 표현하면 관문이 움직인다. 리뷰는 길 끝에 있는 문이기를 멈추고 연속적인 과정이 되어, 글을 쓰는 동안의 맞춤법 검사에 더 가까워진다. 대부분의 변경 사항은 사람이 보기 전에 Claude가 읽고 수정한다.

그들이 무엇을 위해 최적화했는지, 그리고 무엇이 실패로 간주되는지

명시된 목표는 Claude Code 저장소들—게시글에서는 CLI, 데스크톱 및 웹 앱, 모바일 앱이라고 설명한다—의 대부분의 풀 리퀘스트가 루프에 참여하는 사람을 최대 한 명, 작성자일 수 있는 사람으로 두고, 되돌리기나 인시던트의 증가 없이 병합되는 것이다. 세 번째 조건이 이것을 비용 절감 작업이 아니라 진짜 목표로 만든다.

그들은 장부의 양쪽에서 사람의 시간을 측정한다. 사람들이 리뷰에 쓰는 시간과 나쁜 코드가 망가뜨린 것을 고치는 데 쓰는 시간이다. 첫 번째를 줄여도 그 비용이 두 번째에서 다시 나타난다면 도움이 되지 않으며, 팀은 그렇게 직접 말한다. 그래서 추적하는 수치는 풀 리퀘스트당 사람 승인 건수로, 중앙값과 95번째 백분위수로 보고되며, 사람이 남긴 댓글 수, 그리고 풀 리퀘스트가 사람을 기다리는 시간이다. 되돌리기와 인시던트 비율은 그 모든 것 아래에 가드레일로 자리한다. 그것들이 상승하면 사람의 시간은 절약된 것이 아니라 옮겨진 것뿐이다.

리뷰 비용 지표는 단독으로는 쉽게 조작될 수 있습니다. 모든 것을 승인하는 리뷰어는 멋진 승인 시간 차트를 만들어냅니다. 차트가 거짓말을 하지 못하게 막는 것은 바로 가드레일입니다.

일곱 단계이지, 하나의 관문이 아니다

이 글은 일반적인 변경이 거치는 경로를 일곱 개의 번호가 매겨진 단계로 설명한다. 각 계층은 일부 문제를 잡아내고 다른 문제는 놓치며, 더 저렴한 검사가 더 비싼 검사보다 먼저 실행된다.

• 풀 리퀘스트가 존재하기 전에 수행하는 검증. Claude는 테스트, 빌드, 린터를 실행하고, 두 번째 에이전트가 새로운 컨텍스트에서 diff를 리뷰합니다. 많은 엔지니어는 내부 스킬도 실행합니다. 하나는 버그를 찾고, 하나는 diff를 단순화하고, 하나는 동작을 엔드투엔드로 확인합니다. Claude Code를 만든 Boris Cherny는 Claude가 자신의 작업을 검증할 방법을 주는 것이 아마 좋은 결과를 위한 가장 중요한 일이라고 말했으며, 그것이 최종 결과를 두세 배 더 좋게 만든다고 추정합니다.

• 모든 풀 리퀘스트에 대한 AI 리뷰. Claude 리뷰는 전체 저장소와 풀 리퀘스트에 명시된 의도를 기준으로 diff를 읽습니다. 여러 에이전트가 병렬로 버그를 찾고, 별도의 그룹이 각 발견 사항에 투표하여 충분히 실제라고 동의한 경우에만 게시됩니다. 스타일, 진단 또는 정리에 관한 발견 사항은 제외됩니다. 살아남은 항목은 Important, Nit 또는 Pre-existing 태그가 붙은 인라인 댓글로 표시됩니다. 리서치 프리뷰가 출시되었을 때, 실질적인 리뷰 댓글을 받는 내부 풀 리퀘스트의 비율은 16퍼센트에서 54퍼센트로 증가했습니다. 관리자는 각 저장소를 Quick, Standard 또는 Deep으로 설정합니다.

• 보안 검토. 별도의 자동화된 검토 과정입니다. 두 검토 중 하나에서 발견된 사항이 열려 있는 동안에는 풀 리퀘스트를 병합할 수 없습니다. 해당 사항을 수정하거나 짧은 사유를 남기고 스레드를 닫아야 합니다. 동일한 검사는 오픈 소스 보안 검토 GitHub Action 또는 /security-review 명령으로 공개되어 있습니다.

• 차단하는 자동 검사. 린트, 타입 검사, 모든 플랫폼에서의 테스트, 그리고 빌드.

• 인간 승인, 위험에 따라 조정. 분류기가 변경 사항을 읽고 작성자가 등급을 설정하는 대신 등급을 설정합니다. 이 단계는 가장 흥미로운 설계가 대부분 담겨 있기 때문에 아래에서 별도 섹션으로 다룹니다.

• 병합 대기열, 플래그 및 점진적 릴리스. 대기열은 변경 사항을 적용한 상태로 main에 대해 모든 검사를 다시 실행하므로, 각각 통과한 두 풀 리퀘스트가 결합되어 깨진 main이 될 수 없습니다. 새로운 동작은 플래그 뒤에서 먼저 Anthropic 직원에게 제공되고, 그다음 최신 채널에 제공되며, 안정 채널이 뒤따릅니다.

• 빠른 감지와 롤백. 플래그는 배포 없이 끌 수 있고, 주간 온콜 순번제가 있으며, 사고 리뷰에서는 어느 계층이 문제를 잡았어야 했는지 질문합니다. 일부 실수는 여전히 통과할 것이므로, 마지막 계층은 이를 방지하는 것보다 빨리 알아차리는 데 중점을 둡니다.

변경 사항은 작성자가 아니라 등급을 설정합니다.

문서 수정과 자동 업데이터 변경은 위험도가 같지 않으므로 같은 검토를 받지 않습니다. 해당 글의 표에는 세 가지 등급이 있으며, 각 등급은 한 가지 질문에 답합니다. 즉, 병합 전에 이 변경을 승인해야 하는 사람이 몇 명인지(있다면)입니다.

낮음은 문서, 카피, 내부 전용 기능, 그리고 플래그 뒤의 추가 변경을 포함하며, 자동 검토와 보안 검사가 통과되면 사람이 필요하지 않습니다. 중간은 일반 제품 변경과 캐싱, 자동 업데이터, 시스템 프롬프트 같은 민감 영역을 포함하며 한 사람이 필요합니다. 높음은 가장 위험도가 높은 코드와 항상 두 사람이 필요한 소수의 경로를 포함합니다.

분류기는 설계의 절반일 뿐입니다. 두 번째 분류기는 해당 등급이 필요 없다고 말하더라도 이 특정 변경에 다른 사람이 필요한지 묻습니다. 일부 경로는 등급과 관계없이 항상 사람이 필요합니다. 소유자가 민감하다고 지정한 모든 항목과 모든 CI 워크플로 파일이 그렇습니다. 저장소의 신뢰 목록에 있는 작성자, 주로 소유 팀만 더 가벼운 경로를 이용할 수 있고, 그 외 모두에게는 두 번째 사람이 필요합니다. 에이전트의 승인은 결코 사람의 승인으로 간주되지 않으므로, 자동 검토는 저위험 변경을 통과시킬 수는 있어도 사람이 필요한 자리를 채울 수는 없습니다. 변경을 요청한 사람이 그 변경에 대한 책임을 집니다. 또한 승인은 특정 커밋 하나를 대상으로 하므로, 새 커밋 — 에이전트의 푸시나 수동으로 해결한 병합 포함 — 에는 승인이 다시 필요합니다.

분류기를 절대 만들지 않더라도 훔칠 만한 두 가지 세부 사항이 있습니다. 등급은 작성자가 아니라 변경사항에서 나오며, 신뢰는 그 위에 얹히는 별도의 더 좁은 관문입니다. 그리고 승인은 풀 리퀘스트가 아니라 커밋에 묶이므로, 리뷰 시스템에서 가장 흔한 구멍, 즉 브랜치 초기에 얻은 초록색 체크 표시가 아무도 살펴보지 않은 코드에 쓰이는 문제를 막아 줍니다.

검토자는 자신의 인시던트를 기준으로 훈련됩니다

이것이 대부분의 글이 건너뛰는 부분이며, 왜 이 구조가 흐트러지지 않고 계속 작동하는지를 설명해 줍니다.

팀은 장애를 일으켰던 과거 풀 리퀘스트를 해당 픽스포워드 및 리버트와 함께 수집했고, 그 코드를 아는 엔지니어들에게 각 버그와 버그가 있던 위치를 확인하게 했다. 그 수집물은 이제 평가(eval)다. 리뷰어는 매일 그것을 대상으로 실행된다. 프롬프트, 도구 또는 모델이 바뀌면 그 변경은 전체 세트를 통과해야 한다. 점수가 오르면 유지하고, 아니면 버린다. 그들의 실패는 그 실패를 잡아내야 하는 것의 테스트 스위트가 되었다.

그것은 고정된 규칙 집합에 비추어 평가되는 린터를 튜닝하는 것과는 다른 입장이다. 이 리뷰어는 이 코드베이스가 이미 깨졌던 구체적인 방식들에 비추어 평가되므로, 무언가 잘못될 때마다 평가가 확장된다. 우리가 읽은 Anthropic의 어떤 발표물에도 이에 대한 점수는 나오지 않으며, 그 게시물은 리뷰어가 완성되었다고 주장하지 않는다.

아직 구축되지 않은 레이어

이것이 이 글을 신뢰할 수 있게 만드는 인정입니다. 위의 모든 내용은 실수를 잡아내고 되돌리는 시스템을 설명할 뿐, 자체 오류율이 변하고 있다는 것을 인지하는 시스템을 설명하지는 않습니다. 이 팀에는 아직 되돌림이나 인시던트 수치가 움직일 때 승인을 자동으로 더 엄격하게 조이는 서킷 브레이커가 없으며, 그곳 엔지니어들은 더 많은 코드가 사람 개입 없는 병합으로 넘어가기 전에 그것들을 원합니다.

대신 존재하는 것은 사람이 알아차리는 일입니다. 플래그는 배포 없이 꺼지고, 주간 온콜 순번이 지켜보며, 인시던트 리뷰에서는 어느 계층이 문제를 잡았어야 했는지 묻습니다. 비슷한 롤아웃을 계획하는 누구에게나 가장 유용한 문장은 한 동료의 말입니다. 속도를 늦추면 오류율이 낮아지긴 하지만, 그건 대개 모든 일을 덜 하고 있기 때문입니다. 팀은 문제를 만들어내는 속도를 늦추기보다 문제를 알아차리고 고치는 속도를 높이고 싶어 합니다.

그 점을 염두에 두고 일곱 단계를 다시 읽어 보라. 여섯 단계는 변경이 진행될지 여부를 결정한다. 일곱 번째는 그 뒤에 알아차리기 위한 일련의 습관이다. 결과에서 다시 게이트로 연결되는 피드백 루프는 없으며, 그 시스템을 만든 사람들도 그렇게 말한다.

게시물이 대부분 제쳐두는 리뷰의 두 번째 역할

이 글은 코드 리뷰가 두 가지 일을 한다고 분명히 밝힙니다. 출시 전에 문제를 찾아 수정하는 일과 팀 전체에 공유된 맥락을 구축하는 일입니다. 글은 첫 번째에 초점을 맞춘 뒤, 두 번째로 돌아와 유난히 솔직한 답을 내놓습니다. 그것을 위한 공식적인 프로세스는 없고, 누구도 Claude Code에 대한 완전한 멘탈 모델을 머릿속에 유지하지 않으며, 그럴 필요가 있다고 생각하지도 않는다는 것입니다. 코드베이스의 일부를 이해하고 싶나요? 바로 그 부분에 대한 설명을 Claude에게 요청하세요.

두 개의 지침 파일이 예전에는 리뷰어들의 머릿속에 있던 맥락을 담고 있습니다. CLAUDE.md는 Claude에게 프로젝트가 무엇인지, 기술 스택, 컨벤션, 목표와 비목표를 알려 주며, 의도적으로 짧게 유지됩니다. REVIEW.md는 코드 소유자가 작성하며, 자신이 담당하는 코드 부분에서 실패가 어떤 모습인지, 어떤 경로를 건너뛰어야 하는지를 설명하고, 추측 대신 파일과 줄을 요구합니다.

책임에는 별도의 원칙이 있습니다. 즉, 직접 반영한 변경은 직접 책임져야 합니다. 작거나 중간 규모의 변경을 병합한 뒤 문제가 생기면, 그 문제를 직접 수정하는 것이 규범입니다. 이는 변경 규모가 작고, 플래그와 되돌리기로 대부분의 실수를 몇 분 안에 취소할 수 있으며, 영향 범위가 변경에 필요한 검사 횟수의 기준을 정하기 때문에 가능합니다. 이는 승인 규칙 위에 층을 이루는 규범이며, 승인 규칙을 대체하는 것은 아닙니다.

라우터가 적합한 경우와 그렇지 않은 경우

위의 파이프라인은 모델 호출 파이프라인입니다. 전체 저장소를 기준으로 diff를 읽는 리뷰 에이전트, 병렬로 동작하는 여러 버그 탐색 에이전트, 각 발견 사항에 대해 투표하는 그룹, 보안 점검 단계, 그리고 계속 커지는 eval을 대상으로 매일 다시 실행되는 리뷰어로 구성됩니다. 이는 리뷰 문제라기보다 먼저 라우팅 문제입니다. 한 제공업체가 잠시 상태가 나빠졌다고 해서 병합 큐가 멈춰서는 안 되기 때문입니다.

OrcaRouter는 하나의 키로 200개 이상의 모델을 사용할 수 있는 단일 OpenAI 호환 엔드포인트이며, 제공업체 간 자동 페일오버와 제로 마크업, 즉 제공업체 정가를 그대로 전달하는 방식을 제공합니다. 이 파이프라인의 자체 버전을 운영하는 팀은 하나의 청구 관계와, 리뷰어의 품질 평가가 달라질 때 모델을 전환할 수 있는 단일 지점을 얻게 되며, 이는 바로 일일 평가가 탐지하도록 설계된 부분입니다.

경계가 중요합니다. 우리는 모델을 호스팅합니다. 우리는 Claude Code를 호스팅하지 않고, Claude Code용 Code Review를 실행하지 않으며, 이 글에서 다루는 파이프라인에 접근할 수 없습니다. Claude Code용 Code Review는 Anthropic의 제품으로 Team 및 Enterprise 플랜에서 일반적으로 제공되며, 더 가벼운 버전은 /code-review로 로컬에서 사용할 수 있습니다. 원하는 것이 그 파이프라인이라면, 그것이 있는 곳은 바로 거기입니다. 자신의 팀이 사용하는 해당 버전에서는 라우터가 리뷰 결정이라기보다는 배관(plumbing) 결정입니다.

더 작은 팀이 실제로 따라 할 수 있는 것

리뷰어가 읽을 수 있는 곳에 리뷰 규칙을 적어 두세요. 프로젝트를 위한 짧은 CLAUDE.md와, 영역별로 실패가 어떤 모습인지 명시하고 추측 대신 파일과 줄을 요구하는 REVIEW.md를 두세요. 위험 등급을 문서로 남기고, 등급을 작성자가 아니라 변경 자체의 속성으로 만들고, 엄격하게 시작해 증거가 있을 때만 완화하세요. 자동화된 리뷰가 승인할 수 있는 범위에 상한을 두고, 에이전트의 승인이 사람의 승인으로 계산되는 일은 결코 없게 하세요. 승인을 커밋에 결부시키세요. 머지 큐를 운영하세요. 인시던트와 리버트를 테스트 케이스로 전환하고, 리뷰어를 변경할 때마다 다시 점수를 매기세요. 측정되지 않는 리뷰어는 마케팅만 잘한 린터일 뿐이니까요.

그렇다면 승인 시간이 아니라 가드레일을 보세요. 팀이 스스로 제시한 틀은 여러분이 고려 중인 모든 리뷰 변경에 대한 테스트를 제공합니다. 되돌림과 인시던트 비율이 유지되었는가, 아니면 시간이 리뷰어에서 나중에 수습하는 사람에게로 단순히 옮겨갔는가? 이 질문은 대부분의 팀이 이미 가진 데이터로 답할 수 있으며, 더 빨라진 프로세스와 한 분기 동안만 더 빨라 보이는 프로세스를 구분해 줍니다.