사람이 모든 줄을 읽지 않아도 되는 이유 — Claude Code 팀의 코드 리뷰 방식

Claude Code 팀의 코드 리뷰: 읽기는 기계에게, 사람의 시간은 위험한 곳에

Addy Osmani, Morgan Westlee Lunt, Qing Wang이 claude.dev 블로그에 쓴 How the Claude Code team does code review(2026-10-15)를 읽고 정리한 글입니다.

✍️ 한 줄 요약

리뷰를 없앤 게 아니라, 읽기의 대부분을 기계로 옮기고 사람의 시간과 주의력에 최적화했으며, 실수를 빠르고 쉽게 되돌리는 데 크게 투자했습니다. 목표는 "되돌림(revert)·장애를 늘리지 않는 선에서 사람의 리뷰 시간을 최소로" 입니다.

요약

• 배경: Claude Code 코드의 약 90%를 Claude가 씁니다. 6월에서 9월 사이 Claude Code 저장소에 머지된 PR은 두 배 넘게 늘었고, 되돌려야 했던 비율은 40% 넘게 줄었습니다.
• 질문을 바꾸기: "사람이 코드를 읽었는가?"는 부정확한 대리 지표입니다. 진짜 질문은 "이 변경에서 무엇이 잘못될 수 있고, 그걸 잡기에 맞는 검사(자동이든 사람이든)는 무엇인가?" 입니다.
• 리뷰의 시점이 바뀜: 끝에 있는 관문이 아니라 글을 쓰는 동안 도는 맞춤법 검사처럼 계속 돕니다. 사람이 보기 전에 대부분의 변경은 Claude가 최소 한 번 리뷰하고 고친 상태입니다.
• 목표 지표: 대부분의 PR이 사람 최대 1명(작성자 본인일 수 있음) 만 거쳐 머지되면서 되돌림·장애가 늘지 않을 것. 사람 승인 수(중앙값·p95), 사람 코멘트, PR이 사람을 기다리는 시간을 재고, 되돌림·장애율을 가드레일로 둡니다.
• 7개 계층: 사전 검증 → PR마다 AI 리뷰 → 머지를 막는 보안 리뷰 → 막는 자동 체크 → 위험도에 비례한 사람 승인 → 머지 큐·플래그·점진 릴리스 → 빠른 감지·롤백. 각 계층은 서로 다른 곳에 구멍이 있습니다.
• 리뷰어 개선 루프: 과거 장애가 eval이 되고, 리뷰어 변경은 매일 그 세트로 채점됩니다. 노이즈는 사람이 코멘트에 어떻게 반응했는지로 잽니다.
• 리뷰는 수렴해야 한다: 에이전트 작성자와 에이전트 리뷰어는 서로를 무한히 바쁘게 만들 수 있습니다(하룻밤에 50라운드 넘게 돈 PR도 있었음). 라운드 상한·diff만 재리뷰·버그 유형 단위 지적·중복 금지로 1라운드 통과 65%→78% 가 됐습니다.
• 사람이 남는 곳: 만들지 말지 결정, 위험한 코드, 패턴을 정하는 아키텍처, 증거 읽기, 결과에 대한 책임.

아래부터는 상세 내용입니다.

📋 목차

1. 코드 리뷰의 목적을 다시 묻기
2. 희소 자원은 사람의 시간과 주의력
3. 변경 하나가 지나가는 길
4. 계층별로 보기
5. 리뷰어를 더 낫게 만드는 법
6. 사람이 루프에 남는 곳
7. 팀에 맥락을 공유하는 법
8. 머지한 사람이 책임진다
9. 방향을 바꿀 때
10. 우리 팀에 도입하려면
11. 앞으로의 방향
12. 마무리

코드 리뷰의 목적을 다시 묻기

Anthropic은 Claude가 Claude Code 자체 코드의 약 90%를 쓴다고 이미 밝힌 바 있습니다. 그렇다면 그 속도로 만들어지는 코드는 어떻게 리뷰할까요? 아직 누가 코드를 읽기는 할까요? 뭔가 깨지면 누가 잡을까요?

에이전트가 코드를 쓰면 변경의 수가 빠르게 늘어납니다. Anthropic 모노레포에서는 하루에 들어가는 변경이 5월 약 2,500건에서 9월 30,000건 이상으로 늘었습니다. Claude Code는 모노레포와 분리된 별도 저장소에 있지만 같은 압력을 받고 있습니다. 이 속도에서 사람이 한 줄씩 읽는 리뷰는 불가능에 가깝습니다.

코드 리뷰가 하는 일은 두 가지입니다.

1. 배포 전에 문제를 찾아 고친다
2. 팀 전체에 공유된 맥락과 코드베이스 이해를 쌓는다

글은 주로 첫 번째를 다루고, 두 번째는 뒤에서 다시 다룹니다.

저자들은 "사람이 코드를 읽었는가?" 가 다음 질문의 부정확한 대리 지표라고 봅니다.

이 변경에서 무엇이 잘못될 수 있고, 그걸 잡기에 맞는 검사는 — 자동이든 사람이든 — 무엇인가?

이 질문을 던지자 리뷰가 언제 일어나는지도 바뀌었습니다. 예전에는 리뷰가 길 끝의 관문이었습니다. 코드를 쓰고, PR을 열고, 동료를 기다립니다. 지금은 리뷰가 글을 쓰는 동안 도는 맞춤법 검사처럼 계속 돕니다. 사람에게 봐 달라고 요청하기 전에 대부분의 변경은 Claude가 최소 한 번 리뷰하고 고친 상태입니다. 이걸로 일상적인 실수 대부분이 걸러지고, 팀의 주의력은 더 높은 수준의 질문과 검토에 남겨집니다.

희소 자원은 사람의 시간과 주의력

사람의 시간과 주의력은 사람만 풀 수 있는 문제에 쓰고, 나머지는 자동 검사가 잡게 하는 것이 목표입니다. 지금의 변경 속도에서도 사람이 할 일은 여전히 엄청나게 많고, 팀은 거의 매일 새로운 문제를 만납니다.

여기서 "사람의 시간"은 리뷰 비용의 양쪽을 다 포함합니다.

• 사람이 리뷰하는 데 쓰는 시간
• 나쁜 코드가 깨뜨린 것을 고치는 데 쓰는 시간

앞쪽을 줄여도 그 시간이 뒤쪽에서 다시 나타나면 아무 의미가 없습니다.

그래서 목표는 이렇게 정해졌습니다. Claude Code 저장소들(CLI, 데스크톱·웹 앱, 모바일 앱)의 대부분 PR이 사람 최대 1명 — 작성자 본인일 수도 있음 — 만 거쳐 머지되고, 되돌림이나 장애는 늘지 않는다.

가드레일 지표가 오른다면 사람의 시간을 아낀 게 아니라 옮겨 놓았을 뿐이다.

변경 하나가 지나가는 길

엔지니어의 노트북(또는 Slack 안의 Claude 세션)에서 출발한 일반적인 변경은 여러 겹의 코드 리뷰를 지나갑니다.

[PR 이전]   작업 검증 ──────────────────────────────── 작성자 + Claude
[모든 PR]   필수 CI → Claude 코드 리뷰 → 보안 리뷰 ─── 전부 자동
            위험 기반 승인 ─────────────────────────── 사람이 결정
[머지]      머지 큐
[머지 이후] 사내 우선 플래그 → 점진 릴리스 → 관찰 · 포워드 픽스 · 롤백

경로의 대부분은 자동화돼 있고, 사람의 주의력은 위험이 있는 곳으로 갑니다.

계층별로 보기

원문은 이 구조를 스위스 치즈 모델로 그립니다. 검증, 필수 CI, AI 리뷰, 보안 리뷰, 사람 승인, 머지 큐 + 플래그의 여섯 장이 위에서 아래로 겹쳐 있고, 각 장은 서로 다른 위치에 구멍이 나 있습니다. 한 장의 구멍을 통과한 문제는 다음 장에서 걸립니다. 드물게 모든 장의 구멍을 통과하는 문제는 맨 아래의 빠른 롤백이 받아냅니다.

각 계층은 어떤 문제는 잡고 어떤 문제는 놓친다. 전부 통과하는 문제는 드물고, 나머지는 롤백이 처리한다.

1. 다른 사람이 보기 전에 작업이 검증된다

이제 리뷰의 대부분은 PR이 생기기도 전에 일어납니다. 두 가지 습관이 핵심이고, 둘 다 Claude Code 모범 사례 가이드에서 왔습니다.

• Claude에게 실행할 수 있는 무언가를 줍니다 — 테스트, 빌드, 디자인과 비교할 스크린샷 같은 것. 그리고 "다 됐어요"라고 말하는 대신 출력을 보여 달라고 합니다.
• 그다음 새 컨텍스트의 서브에이전트가 diff를 리뷰합니다.

PR을 열기 전에 사내 스킬을 몇 개 돌리는 사람도 많습니다. 하나는 버그를 사냥하고, 하나는 diff를 단순화하고, 하나는 동작을 처음부터 끝까지 확인합니다. UI 변경은 디자인 가이드라인에 대해서도 검사합니다.

Claude Code를 만든 Boris Cherny는 Claude에게 자기 작업을 검증할 수단을 주는 것을 좋은 결과를 얻기 위한 아마도 가장 중요한 일이라고 불렀습니다. 최종 결과가 두세 배 좋아진다고 추정하면서 이렇게 썼습니다.

검증은 도메인마다 모습이 다르다. bash 명령 하나를 돌리는 것일 수도, 테스트 스위트를 돌리는 것일 수도, 브라우저나 휴대폰 시뮬레이터에서 앱을 테스트하는 것일 수도 있다.

(이 주제는 Claude Code 만든 사람의 손버릇에서 자세히 다뤘습니다.)

자동 리뷰어가 같은 걸 계속 지적하면, 원천에서 고칩니다. 스킬 안에서, lint 규칙으로, 또는 지시 파일을 고쳐서요.

좋은 REVIEW.md의 특징도 구체적입니다.

• 짧습니다.
• 그 저장소에서 실패가 어떤 모습인지 말합니다 — 문서라면 "거짓말을 한다", 설정이라면 "잘못 라우팅한다".
• nit(사소한 지적)에 상한을 둡니다.
• 건너뛸 경로를 나열합니다.
• 이름만 보고 추측하지 말고 파일과 줄 번호를 증거로 달라고 합니다.
• 요약은 개수로 시작하고, 고칠 게 없으면 없다고 분명히 말하게 합니다.

2. 모든 PR에 AI 리뷰

모든 PR은 사람이 보기 전에 Claude 리뷰를 받습니다. 리뷰어는 diff를 저장소 전체와 PR이 밝힌 의도에 비춰 읽고 묻습니다. 이 변경이 문제를 해결하는가, 시스템에 맞는가, 다른 걸 깨뜨리지 않는가? 버그 수정이라면 근본 원인을 찾습니다.

공개 버전인 Code Review for Claude Code는 Team·Enterprise 플랜에서 정식 제공되고, /code-review는 더 가벼운 버전을 로컬에서 돌립니다.

리서치 프리뷰를 냈을 때, 실질적인 리뷰 코멘트를 받는 사내 PR 비율은 16%에서 54% 로 올랐습니다. 1,000줄이 넘는 PR은 대부분 발견 사항이 나오고, 작은 PR은 대부분 깨끗하게 돌아옵니다. 관리자는 저장소마다 Quick · Standard · Deep 중 하나를 고르는데, Deep은 버그 하나를 놓치는 비용이 추가 리뷰 시간보다 클 때 값어치를 합니다.

발견 사항은 사람이 보기 전에 다른 에이전트가 검증합니다.

1. 여러 에이전트가 동시에 버그를 찾습니다.
2. 별도의 에이전트 그룹이 각 발견 사항에 투표하고, 충분히 많은 수가 진짜라고 동의해야만 게시됩니다.
3. 스타일·진단·정리에 관한 것뿐인 발견 사항은 버립니다. 이 필터들은 사내 PR로 A/B 테스트한 뒤에 유지했습니다.
4. 남은 것은 심각도순으로 정렬된 인라인 코멘트로 올라가고, 각각 Important · Nit · Pre-existing 태그가 붙습니다. Pre-existing 태그 덕분에 PR이 만들지 않은 버그가 작성자 잘못처럼 보이지 않습니다.

모든 발견 사항에는 답해야 합니다. 고치거나, 이유를 달아 스레드를 닫거나. 에이전트가 밤사이 수정을 집어 가는 경우가 많아서, 작성자가 돌아오면 PR이 이미 한 라운드를 더 돈 상태인 경우가 흔합니다.

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

보안도 자체 자동 리뷰를 받습니다. 버그 리뷰나 보안 리뷰의 발견 사항이 하나라도 열려 있으면 PR은 머지되지 않습니다. 고치거나, 짧은 이유를 달아 스레드를 닫아야 하는데, 오탐(false positive)은 이렇게 처리합니다. 이후 커밋이 문제를 고치면 발견 사항은 저절로 해소됩니다.

같은 구성은 오픈소스 보안 리뷰 GitHub Action이나 /security-review 명령으로 만들 수 있습니다. 설정 방법은 Claude Code의 자동 보안 리뷰에 있습니다.

4. 머지를 막는 자동 체크

lint, 타입 체크, 모든 플랫폼의 테스트, 빌드 — 흔히 아는 그것들입니다. (이 물량에 맞춰 CI를 확장한 이야기는 별도 글에 있습니다.) 일반적인 CLI PR은 누가 보기도 전에 수십 개의 체크를 돕니다.

PR 템플릿은 어떻게 테스트했는지와 어떻게 되돌리는지를 묻습니다. Claude가 채울 수는 있지만, 서명은 변경을 요청한 사람이 합니다.

5. 위험도에 비례하는 사람 승인

문서 수정과 자동 업데이터 변경은 위험이 다르니 다른 리뷰를 받습니다.

이 표를 굴리는 규칙이 네 가지 있습니다.

• 등급은 작성자가 아니라 변경이 정합니다. 분류기 하나가 변경을 읽고 위험 등급을 고릅니다. 두 번째 분류기는 "등급상 필요 없다고 해도 이 변경은 사람이 한 명 더 봐야 하는가?"를 묻습니다. 어떤 경로는 항상 사람이 필요합니다 — 오너가 민감하다고 지정한 것, 그리고 모든 CI 워크플로 파일.
• 가벼운 경로는 신뢰된 작성자만 탑니다. 저장소의 신뢰 목록에 있는 작성자(대개 그 저장소를 소유한 팀)만 가벼운 경로를 쓸 수 있고, 나머지는 두 번째 사람의 승인이 필요합니다. 그리고 에이전트의 승인은 절대 사람의 승인으로 치지 않습니다. 자동 리뷰는 낮은 위험 변경을 통과시킬 수는 있어도, 사람이 필요한 자리를 채울 수는 없습니다.
• 변경을 지시한 사람이 책임집니다. 에이전트가 쓴 PR에서는 에이전트를 지휘한 사람이 필수 리뷰어 중 한 명으로 계산됩니다. 그 코드를 직접 타이핑한 것과 똑같이요.
• 승인은 특정 커밋 하나에 대한 것입니다. 시스템이 보증할 수 없는 새 커밋 — 에이전트의 push나 누군가 손으로 해결한 머지 — 이 들어오면 승인을 다시 받아야 합니다.

6. 머지 큐, 플래그, 점진 릴리스

머지 큐는 변경을 적용한 main에 대해 모든 체크를 다시 돌립니다. 따로는 통과한 PR 두 개가 합쳐져 main을 깨뜨리는 일을 막기 위해서입니다.

새 동작은 보통 플래그 뒤에서 Anthropic 직원에게 먼저 나갑니다. 사내에서 워낙 많이 쓰다 보니 회귀가 사용자보다 먼저 드러나는 경우가 많습니다. 공개 릴리스는 먼저 latest 채널로 가고, stable 채널이 그 뒤를 따라갑니다.

7. 빠른 감지, 빠른 롤백

그래도 어떤 실수는 빠져나갑니다. 그래서 마지막 계층은 빨리 잡는 것에 관한 것입니다.

• 플래그는 배포 없이 끌 수 있습니다.
• Claude Code에는 주간 온콜 로테이션이 있습니다.
• 장애 리뷰는 "어느 계층이 이걸 잡았어야 했나?" 를 묻습니다.

한계도 솔직하게 적혀 있습니다. 나쁜 머지를 알아채는 일은 여전히 작성자와 온콜, 그리고 되돌림·장애 대시보드에 달려 있습니다. 그 숫자가 움직일 때 승인 기준을 자동으로 조이는 서킷 브레이커는 아직 없고, 엔지니어들은 더 많은 코드가 사람 0명 머지로 옮겨 가기 전에 그게 있기를 원합니다.

한 동료는 속도를 늦추면 오류율이 낮아지기는 하지만, 그건 대개 모든 일을 덜 하기 때문이라고 말했다. 우리는 문제를 알아채고 고치는 속도를 높이는 쪽을 택하겠다.

리뷰어를 더 낫게 만드는 법

코드 리뷰 프로세스 자체가 루프 안에서 계속 개선됩니다.

모든 장애가 eval이 됩니다. 팀은 장애를 일으킨 과거 PR을 포워드 픽스·되돌림과 함께 모았고, 그 코드를 잘 아는 엔지니어가 각 버그와 그 위치를 확인했습니다. 리뷰어는 매일 그 세트에 대해 돌아갑니다.

장애 / 되돌림 ──▶ 전문가가 확인한 케이스 ──▶ eval 세트에 추가
                                                  │
리뷰어 변경 ──▶ 매일 eval 실행(모든 케이스로 채점) ◀─┘
                    │
        점수 상승 → 유지 / 아니면 → 폐기 ──▶ 다음 변경으로 반복

eval은 장애가 날 때마다 자라고, 리뷰어에 대한 모든 변경은 그 전체로 채점된다.

노이즈는 사람들이 코멘트로 무엇을 하는지 보고 잽니다. 버그가 아닌 것도 잔뜩 지적해도 괜찮다면 버그는 얼마든지 더 잡을 수 있으니, 이를 견제할 장치가 필요합니다. 리뷰어가 남긴 모든 코멘트를 PR 담당자의 반응으로 분류합니다.

• 고쳤다
• 틀렸다고 했다
• 의도된 동작이라고 했다
• 상관없다고 판단했다

또 깨끗하다고 알려진 PR에도 리뷰어를 돌려서, 누군가를 해로운 변경으로 이끌 만한 보고를 얼마나 자주 하는지 셉니다. 문서로 적어 둔 우선순위는 첫째 진짜 버그를 잡는 것, 둘째 리뷰 라운드를 줄이는 것입니다.

작성자가 에이전트일 때 노이즈는 더 비쌉니다. 사람은 nit 하나를 몇 초 만에 넘깁니다. 에이전트는 그걸 고칩니다. 그러면 커밋이 하나 더 생기고, 리뷰가 한 라운드 더 돕니다.

리뷰는 수렴해야 한다

에이전트 작성자와 에이전트 리뷰어는 서로를 무한히 바쁘게 만들 수 있습니다. 어떤 CLI PR은 작성자가 멈추기 전까지 하룻밤 사이 50라운드 넘게 리뷰와 수정을 반복했습니다.

리뷰어가 계속 지적하던 것에 git blame을 돌려 보니, 약 59% 가 리뷰어의 첫 패스 때부터 이미 있던 코드였습니다. 리뷰어는 새 버그를 찾는 게 아니라, 라운드마다 오래된 버그를 몇 개씩 더 찾고 있었던 것입니다.

스스로 상황을 악화시킨 면도 있었습니다. 패스마다 새로운 걸 잡으니 여러 라운드를 기본으로 돌리는 데 익숙해져 있었던 것이죠. 위험한 변경이라면 그럴 가치가 있지만, 모든 PR에서 그럴 필요는 없습니다. 팀은 이제 재현율(recall)과 함께 통과까지 걸린 라운드 수를 추적하고, 재리뷰 방식을 바꿨습니다.

• 라운드 상한. 3라운드가 지나면 리뷰어가 작성자에게 한발 물러나 접근 방식 자체를 다시 생각해 보라고 요청합니다.
• 처음 몇 패스 이후에는 diff만 재리뷰합니다.
• 버그의 유형(class)을 지적해서, 작성자가 한 줄이 아니라 모든 사례를 고치게 합니다.
• 이미 게시한 발견 사항은 반복하지 않습니다.

리뷰 에이전트는 매일 밤 기존 코드에도 돌아서, 오래된 버그가 다른 곳에서 터지기 전에 잡습니다.

사람이 루프에 남는 곳

일상적인 실수를 잡겠다고 시니어 엔지니어를 깊은 작업에서 끌어내는 비용은 자동 리뷰보다 훨씬 큽니다. 그래도 팀의 사람들이 여전히 책임지는 일이 있습니다.

• 만들지 말지 결정하기. 방향, 취향, 범위. 리뷰 병목을 해결했다고 선언한 어떤 팀도 팀 바깥에서 온 변경에는 사람 리뷰를 남겨 뒀습니다. 누군가는 "이걸 하긴 해야 하나?"라고 물어야 하니까요.
• 위험한 코드 리뷰. 결제, 자동 업데이터, CI 워크플로 같은 것.
• 아키텍처 리뷰. 다른 사람들이 따라 할 패턴을 정하는 변경.
• 증거 읽기. 테스트 출력, 실행한 명령과 그 결과, 스크린샷, 리뷰어의 발견 사항. 체크가 무엇을 놓칠지 말할 수 없다면, 빠른 승인 대신 제대로 된 리뷰를 요청해야 합니다.
• 결과에 대한 책임. 누가 타이핑했든, 배포되는 모든 변경에는 책임지는 사람이 있습니다.

팀에 맥락을 공유하는 법

코드 리뷰의 두 번째 역할은 원래 코드베이스 이해를 퍼뜨리는 것이었습니다. 동료의 diff를 읽으면서 무엇이 바뀌었고 조각들이 어떻게 맞물리는지 배웁니다. 기계가 읽기의 대부분을 한다면, 사람은 어떻게 코드를 배울까요?

여기에는 공식 프로세스가 없다고 저자들은 말합니다. 팀의 누구도 Claude Code의 완전한 멘탈 모델을 머릿속에 들고 있지 않고, 그럴 필요도 없다고 봅니다. 코드베이스의 어떤 부분을 이해하고 싶으면 Claude에게 정확히 그 조각에 대한 설명서(explainer) 를 써 달라고 합니다. 몇 분이면 되고, 오늘 있는 그대로의 코드를 반영합니다. 예를 들어 "Claude Code는 관리형 설정(managed settings)을 어떻게 가져오지?"라고 묻는 식입니다.

한발 더 나아가 Claude에게 그 코드 영역을 시각화하고 본인이 좋아하는 학습 방식으로 가르쳐 주는 작은 아티팩트를 만들게 하는 사람도 있습니다.

사람의 주의력을 잘 쓰는 것이 목표라면, 이게 사소한 diff를 한 줄씩 읽는 것보다 낫습니다.

• 문구 한 줄 변경은 거의 아무것도 가르쳐 주지 않습니다.
• 곧 바꾸려는 모듈의 설명서는 많은 것을 가르쳐 줍니다.

열린 Slack 채널에서 일하는 것을 기본으로 하는 문화도 도움이 됩니다. 다른 사람이 무엇을 만드는지 만드는 동안 볼 수 있기 때문입니다.

머지한 사람이 책임진다

원문의 표현은 "You land it, you own it" 입니다. 작거나 중간 규모의 변경을 머지했는데 문제가 생기면, 보통 머지한 사람이 고치는 것이 팀 규범입니다. 이게 나쁘게 흘러가지 않도록 받쳐 주는 것들이 있습니다.

• 변경이 작습니다. 그래서 리뷰하기도, 디버깅하기도, 되돌리기도 쉽습니다.
• 모든 것이 되돌릴 수 있습니다. 플래그, 되돌림, 단계적 릴리스로 대부분의 실수를 몇 분 안에 되돌립니다.
• 폭발 반경이 기준을 정합니다. 비싼 코드에는 더 많은 사람과 더 많은 체크가 붙습니다.
• 회귀가 빨리 드러납니다. 텔레메트리와 사내 사용 덕분입니다.
• 비난이 아닙니다. 수정을 맡는다는 건 가장 많은 맥락을 가진 사람이라는 뜻이고, 장애 리뷰는 시스템을 봅니다.

소유권은 공유되기도 합니다. 팀의 상당수가 열린 채널에서 일하기 때문에, 누구나 다른 사람이 만드는 것을 보고, 스레드를 이어받거나, 빈틈에 Claude를 붙일 수 있고, 코드 오너가 아닌 사람에게서도 피드백이 옵니다. 모든 줄에 관문을 두지 않고도 품질이 높게 유지되는 큰 이유가 이 개방성입니다.

방향을 바꿀 때

에이전트는 일을 시작하는 비용을 싸게 만들기 때문에, 들어가지 말아야 할 작업도 생깁니다. 보통은 채널의 누군가가 이유를 묻거나, 이전 결정을 가리키거나, 더 단순한 길을 제안하고, 작성자가 PR을 닫거나 다시 빚습니다.

코드를 빨리 썼으니 PR을 닫는 게 손실처럼 느껴지지 않습니다. 요령은 다른 방향을 스레드에서 일찍 꺼내는 것입니다. 다 만든 PR에 막는 코멘트로 다는 게 아니라요.

우리 팀에 도입하려면

이 과정의 조각 대부분은 지금 바로 쓸 수 있습니다.

PR 이전

• 에이전트가 실행할 수 있는 체크를 주고, 짧은 CLAUDE.md에 나열합니다. 포매터·린터를 돌리는 훅도 붙입니다.
• /code-review와 /security-review를 로컬에서 돌리거나, 새 컨텍스트의 서브에이전트에게 리뷰를 맡깁니다.
• REVIEW.md를 추가하고, 반복되는 리뷰 코멘트를 그 안으로 옮깁니다.

모든 PR

• CI를 필수로 하고, PR 템플릿에 "테스트" · "위험" · "되돌리는 방법" 을 추가합니다.
• AI 리뷰어(Code Review for Claude Code, 또는 Claude Code GitHub Action)를 저장소 하나에 붙이고, 몇 주간 REVIEW.md를 다듬은 뒤 넓힙니다.
• 자동 보안 리뷰를 추가하고, 머지 전에 모든 리뷰 스레드가 해결되도록 강제합니다.
• 리뷰 노력을 위험에 맞춥니다. 일상적인 변경엔 빠른 패스, 버그를 놓치면 비싼 곳엔 깊은 패스(Code Review의 Quick · Standard · Deep).
• 리뷰 라운드에 상한을 두고, 처음 몇 번 이후로는 새 diff만 재리뷰합니다.

승인

• 위험 등급을 문서로 적고, 작성자가 아니라 변경으로 정합니다. 엄격하게 시작해서 증거가 쌓이면 풉니다.
• 가벼운 승인 경로는 신뢰하는 작성자에게만 남깁니다.
• CODEOWNERS와 브랜치 보호로 인증, 결제, CI·릴리스 워크플로, 설치 프로그램에는 항상 사람이 필요하게 합니다.
• 봇의 승인이 필수 사람 승인을 대신하게 두지 말고, 새 커밋이 오면 승인을 무효화합니다.

머지와 그 이후

• 머지 큐, 피처 플래그, 사내 우선 사용, 단계적 릴리스, 한 번에 되돌리는 롤백을 씁니다.
• 장애와 되돌림을 eval 세트로 만들고, 리뷰어의 프롬프트·도구·모델이 바뀔 때마다 다시 채점합니다.
• 사람의 시간을 재고, 되돌림·장애율을 가드레일로 둡니다.

앞으로의 방향

Code Review 발표문은 PR 승인은 여전히 사람의 판단이라고 했습니다. 제품은 발견 사항을 게시할 뿐 승인하지 않습니다. 하지만 Claude Code 팀의 저장소는 한발 더 나아가, 어떤 낮은 위험 변경이 자동 체크만으로 머지될지 오너가 정하게 하고 있고, 그 선은 계속 움직이고 있습니다.

리뷰가 무언가를 놓치면 팀은 "모델 앞에 무엇이 없었나?" 를 묻고, 그 답을 CLAUDE.md, 스킬, 또는 새 체크에 넣습니다. 목표는 처음부터 같습니다. 변경당 사람의 시간은 줄이고, 되돌림은 이전보다 늘리지 않는다.

마무리

이 글을 한 문장으로 줄이면 "리뷰의 단위를 '사람이 읽었는가'에서 '이 위험을 잡을 올바른 검사가 있는가'로 바꿨다" 입니다. 사람 0명 머지가 가능한 이유는 리뷰를 건너뛰어서가 아니라, 사전 검증부터 롤백까지 겹겹의 계층이 있고 위험도 판정이 작성자가 아니라 변경 자체에 걸려 있기 때문입니다.

개인적으로 와닿은 지점은 세 가지입니다.

첫째, "노이즈는 에이전트 작성자에게 더 비싸다" 는 관찰입니다. 사람이면 무시하고 넘어갈 nit을 에이전트는 성실하게 고치고, 그게 커밋과 리뷰 라운드를 하나씩 늘립니다. 라운드 상한과 "3라운드 넘으면 접근을 다시 생각하라"는 규칙은 에이전트끼리 리뷰를 돌리는 팀이라면 바로 가져다 쓸 만합니다.

둘째, "승인은 특정 커밋 하나에 대한 것" 이라는 규칙입니다. 승인 이후 에이전트가 push한 커밋이 아무 검토 없이 들어가는 구멍을 정확히 막습니다. GitHub라면 브랜치 보호의 "Dismiss stale pull request approvals when new commits are pushed" 옵션 하나로 켤 수 있으니, 에이전트가 PR에 push하는 팀이라면 지금 켜져 있는지 확인해 볼 만합니다.

셋째, 반복되는 지적을 원천에서 고친다는 원칙입니다. 브라운필드 에이전틱 엔지니어링의 "반복되는 지적은 하네스의 빈 칸"과 같은 이야기이고, 코드 품질은 제약에 있다에서 다룬 "리뷰가 안 되는 규모에서는 제약으로 품질을 지킨다"의 Anthropic 내부 실전판이기도 합니다.

우리 팀 코드 리뷰 점검 체크리스트:

• ✅ PR을 열기 전에 에이전트가 실행한 검증 결과(테스트 출력·스크린샷)를 보여 주는가
• ✅ CLAUDE.md는 짧고, REVIEW.md에 "이 저장소에서 실패란 무엇인가"가 적혀 있는가
• ✅ AI 리뷰의 발견 사항을 다른 에이전트가 검증한 뒤에 게시하는가
• ✅ 열린 리뷰·보안 스레드가 있으면 머지가 막히는가
• ✅ 위험 등급을 작성자가 아니라 변경으로 정하고, CI 워크플로·결제·인증에는 항상 사람이 붙는가
• ✅ 봇 승인이 사람 승인을 대신하지 않고, 새 커밋이 오면 승인이 무효화되는가
• ✅ 리뷰 라운드에 상한이 있고, 재리뷰는 새 diff만 보는가
• ✅ 과거 장애·되돌림이 리뷰어의 eval 세트가 되어 있는가
• ✅ 사람 리뷰 시간을 재면서 되돌림·장애율을 가드레일로 보고 있는가

참고 문서

• Addy Osmani, Morgan Westlee Lunt, Qing Wang, How the Claude Code team does code review (2026-10-15)
• Anthropic, Redesigning source control
• Claude Code Docs, Best practices · Code Review
• Claude Help Center, Automated security reviews in Claude Code
• Anthropic, Code Review 발표 · Agentic coding is straining CI
• 이전 글 — 브라운필드 에이전틱 엔지니어링 · 코드 품질은 제약에 있다 · Claude Code 만든 사람의 손버릇