Claude Code 팀의 코드 리뷰 방식: 병합 PR이 2배로 늘 때 되돌림 비율은 40% 넘게 줄인 방법 (feat. Anthropic)

9bow · 10월 30, 2026, 6:00오전

핵심 요약

Anthropic의 Claude Code 팀 코드 리뷰 글에 따르면, 2026년 6월부터 9월까지 Claude Code 저장소의 병합 PR 수는 2배 넘게 늘었고 되돌린(revert) PR의 비율은 상대값으로 40% 넘게 줄었습니다.
이 팀은 사람이 모든 코드를 읽는 대신 사전 검증, AI 리뷰, 보안 리뷰, CI, 위험도별 사람 승인, 병합 큐와 기능 플래그의 6겹 검사를 두고, 그 아래에 빠른 롤백을 둡니다.
위험이 낮은 변경은 신뢰 작성자 목록에 있는 사람이 올렸고 자동 리뷰와 보안 검사가 통과했다면 사람 승인 없이 병합됩니다. CI 워크플로우 파일처럼 항상 사람이 봐야 하는 경로는 예외입니다. 에이전트의 승인은 사람의 승인으로 세지 않습니다.
3회차가 지나면 접근 방식을 다시 생각하라고 요청하는 등 수렴 작업을 한 뒤, 리뷰 1회차에 통과한 내부 PR 비율은 65%에서 78%로 올랐고 5회 이상 걸린 PR은 8.9%에서 1.5%로 줄었습니다.
이 팀이 쓰는 AI 리뷰어의 공개 버전이 Code Review for Claude Code(Team, Enterprise 플랜)이고, 모든 플랜에서 쓸 수 있는 /code-review 는 그 가벼운 로컬 버전입니다. 다만 제품 자체는 PR을 승인하거나 막지 않으므로, 병합 차단은 GitHub 브랜치 보호 규칙으로 직접 설정해야 합니다.

Claude Code 팀의 코드 리뷰 소개

코딩 에이전트가 코드를 쓰기 시작하면 가장 먼저 늘어나는 것은 변경의 수입니다. Anthropic은 Scion 글 ( Anthropic Scion: 하루 3만 건 병합을 감당하려 Git을 대체한 버전 관리 시스템 (및 Mononoke와의 출처 표기 논쟁😵))에서 사내 모노레포에 하루 병합되는 변경이 2026년 5월 약 2,500건에서 9월 30,000건 이상으로 늘었다고 밝혔습니다. 이 정도 속도에서는 사람이 모든 PR을 한 줄씩 읽는 방식이 유지되기 어렵습니다. 그렇다고 리뷰 시간을 줄여도, 그 시간이 장애를 고치는 시간으로 옮겨 가면 의미가 없습니다.

이번에 소개하는 글은 Anthropic의 Addy Osmani, Morgan Westlee Lunt, Qing Wang이 2026년 10월 15일 claude.dev 블로그에 쓴 것입니다. Claude Code 팀이 이 문제를 어떻게 다루는지 설명합니다. Claude Code는 모노레포와 분리된 별도 저장소에 있고, 팀은 Claude가 Claude Code 코드의 약 90%를 작성한다고 이전부터 밝혀 왔습니다. 저자들은 리뷰를 없애지 않았습니다. 대신 읽는 일 대부분을 기계에 맡기고, 사람의 시간과 주의를 기준으로 과정을 다시 설계하고, 실수를 빨리 되돌리는 데 투자했다고 설명합니다.

이 글은 두 종류의 독자에게 유용합니다. 하나는 이미 에이전트가 PR을 여는 팀입니다. 원문에는 위험 등급표, 승인 규칙, 리뷰어 평가 방법처럼 그대로 옮겨 쓸 수 있는 규칙이 많습니다. 다른 하나는 Code Review for Claude Code 도입을 검토하는 팀입니다. 원문은 Claude Code 팀이 자기 저장소에 적용한 운영 방식이고, 제품의 기본 동작과 다른 부분이 있습니다. 이 글의 뒷부분에서 그 차이를 공식 문서와 대조해 정리했습니다.

리뷰의 목표를 사람의 시간으로 다시 정의하기

저자들은 코드 리뷰가 두 가지 일을 한다고 봅니다. 하나는 배포 전에 문제를 찾아 고치는 일이고, 다른 하나는 팀 전체가 코드베이스를 함께 이해하게 만드는 일입니다. 원문은 주로 첫 번째를 다루고, 두 번째는 끝부분에서 따로 다룹니다.

첫 번째 일에 대해 저자들은 "사람이 코드를 읽었는가?"라는 질문이 부정확한 대리 지표라고 말합니다. 대신 물어야 할 것은 이 변경에서 무엇이 잘못될 수 있는지, 그리고 자동이든 사람이든 어떤 검사가 그것을 잡기에 맞는지입니다. 이렇게 질문을 바꾸자 리뷰가 일어나는 시점도 바뀌었습니다. 예전에는 코드를 쓰고 PR을 연 뒤 동료를 기다리는 마지막 관문이었다면, 지금은 글을 쓰는 동안 돌아가는 맞춤법 검사처럼 계속 진행됩니다. 대부분의 변경은 사람에게 리뷰를 요청하기 전에 Claude가 적어도 한 번 리뷰하고 고친 상태입니다. 이 단계가 일상적인 실수 대부분을 잡으므로, 팀의 주의는 더 높은 수준의 질문과 검토에 쓸 수 있습니다.

팀이 세운 목표는 구체적입니다. Claude Code 저장소(CLI, 데스크톱과 웹 앱, 모바일 앱)의 PR 대부분이 사람은 최대 한 명만 관여한 상태로 병합되고, 그 한 명은 작성자 본인이어도 되며, 되돌림과 사고는 늘지 않아야 합니다. 사람의 시간은 PR당 사람 승인 수(중앙값과 95 백분위수), 사람이 남긴 댓글 수, PR이 사람을 기다린 시간으로 잽니다. 되돌림과 사고 비율은 가드레일(Guardrail)입니다. 이 비율이 오르면 사람의 시간을 아낀 것이 아니라 리뷰하는 시간을 장애 대응 시간으로 옮겨 놓았을 뿐이라고 저자들은 설명합니다.

아래 그림은 원문의 그림 A로, 변경 하나가 작성자의 컴퓨터에서 사용자에게 닿기까지 거치는 단계를 보여줍니다. 동그라미 체크는 자동 단계, 주황색 마름모는 위험도에 따라 사람이 결정하는 단계, 화살표 원은 복구 단계입니다.

6겹의 검사와 그 아래의 롤백

원문은 검사를 여러 겹의 판으로 설명합니다. 각 판에는 구멍이 있어서 어떤 문제는 잡고 어떤 문제는 놓칩니다. 모든 판을 통과하는 문제는 드물고, 그래도 통과한 문제는 맨 아래의 빠른 롤백(Rollback)이 처리합니다. 아래 그림(원문 그림 B)에서 주황색 점은 각 판에 걸린 문제이고, 가운데 점선은 모든 판을 통과해 롤백까지 내려간 문제입니다.

1단계: 다른 사람이 보기 전에 작업을 검증합니다

지금은 리뷰의 대부분이 PR이 생기기 전에 일어납니다. 팀은 Claude에게 테스트, 빌드, 디자인과 비교할 스크린샷처럼 실행해 볼 수 있는 것을 주고, "다 됐다"고 말하는 대신 그 출력을 보여 달라고 요청합니다. 그다음 새 컨텍스트(Fresh Context)로 시작한 서브에이전트(Subagent)가 diff를 리뷰합니다. 두 습관 모두 Claude Code의 모범 사례 가이드에 있습니다. 이 가이드는 대화를 보지 않은 서브에이전트가 리뷰하므로 코드를 만든 추론(reasoning)에 휘둘리지 않는다고 설명합니다.

많은 팀원은 PR을 열기 전에 내부 스킬 몇 개를 더 실행합니다. 하나는 버그를 찾고, 하나는 diff를 단순하게 만들고, 하나는 동작을 처음부터 끝까지 확인합니다. UI 변경은 디자인 가이드라인과도 대조합니다. Claude Code를 만든 Boris Cherny는 Claude에게 작업을 검증할 방법을 주는 것이 좋은 결과를 얻는 데 아마 가장 중요한 일이며, 최종 결과를 2~3배 좋게 만든다고 추정했습니다 ( [GN] Claude Code 창시자 Boris Cherny가 Claude Code를 사용하는 방법).

"검증은 분야마다 모습이 다릅니다. bash 명령 하나를 실행하는 것만큼 간단할 수도 있고, 테스트 스위트를 돌리거나 브라우저나 휴대폰 시뮬레이터에서 앱을 테스트하는 것일 수도 있습니다."

"Verification looks different for each domain. It might be as simple as running a bash command, or running a test suite, or testing the app in a browser or phone simulator."

자동 리뷰어가 같은 지적을 반복하면, 팀은 그 지적을 PR마다 처리하지 않고 원인이 되는 곳을 고칩니다. 스킬을 고치거나, 린트(Lint) 규칙을 추가하거나, 아래와 같은 지침 파일을 고칩니다.

CLAUDE.md: 프로젝트가 무엇인지(스택, 컨벤션, 목표와 비목표)를 Claude에게 알려 줍니다. 모든 리뷰가 이 파일을 읽으므로, 큰 코드베이스에서는 짧게 유지하고 나머지는 다른 문서로 연결합니다. 리뷰어는 이 파일의 컨벤션을 어기는 코드와, 이 파일의 한 줄을 낡게 만드는 변경도 지적합니다.
REVIEW.md: 코드 소유자가 작성하며, 자기 영역에서 리뷰어가 무엇을 중요하게 봐야 하는지 적습니다. 팀은 리뷰어가 이 파일을 실제로 따르는지 따로 확인합니다. 저자들이 꼽는 좋은 REVIEW.md 는 짧습니다. 먼저 그 저장소에서 실패가 어떤 모습인지 적습니다. 문서라면 사실과 다른 내용이 실패이고, 설정이라면 요청을 잘못된 곳으로 보내는 것이 실패입니다. 그리고 사소한 지적(Nit)의 수를 제한하고 건너뛸 경로를 나열합니다. 이름만 보고 추측하지 말고 파일과 줄 번호를 근거로 대라고도 요구합니다. 요약은 지적 개수로 시작하고, 고칠 것이 없으면 없다고 분명히 쓰게 합니다.

2단계: 모든 PR에 AI 리뷰를 추가합니다

모든 PR은 사람이 보기 전에 Claude의 리뷰를 받습니다. 리뷰어는 diff를 저장소 전체, 그리고 PR이 밝힌 의도와 함께 읽습니다. 그리고 이 변경이 문제를 해결하는지, 시스템에 맞는지, 다른 곳을 망가뜨리지 않는지 묻습니다. 버그 수정 PR이면 근본 원인을 찾습니다. 이 리뷰어의 공개 버전이 Code Review for Claude Code이고 현재 Team과 Enterprise 플랜에 정식 출시되어 있습니다. 로컬에서는 /code-review 명령이 더 가벼운 버전을 실행합니다(이 명령은 CLAUDE.md 는 따르지만 REVIEW.md 는 읽지 않습니다).

2026년 3월 리서치 프리뷰를 발표했을 때, Anthropic 내부 PR 중 실질적인 리뷰 댓글을 받은 비율은 16%에서 54%로 올랐습니다. 원문에 따르면 1,000줄이 넘는 PR은 대부분 지적 사항(Finding)을 받고, 작은 PR은 대부분 지적 없이 끝납니다. 발표 글에는 더 구체적인 수치가 있습니다. 1,000줄 넘는 PR의 84%가 평균 7.5개의 지적을 받았고, 50줄 미만 PR은 31%가 평균 0.5개를 받았으며, 엔지니어가 틀렸다고 표시한 지적은 1% 미만이었습니다. 관리자는 저장소마다 Quick, Standard, Deep 중 하나를 고릅니다. 저자들은 버그 하나를 놓쳤을 때의 비용이 추가 리뷰 시간보다 큰 곳에서 Deep이 가치가 있다고 말합니다.

지적 사항은 사람이 보기 전에 다른 에이전트가 검증합니다. 여러 에이전트가 동시에 버그를 찾고, 별도의 에이전트 그룹이 지적마다 투표합니다. 충분한 수가 진짜라고 동의한 지적만 게시됩니다. 스타일, 진단, 정리에만 관한 지적은 버립니다. 팀은 이 필터들을 자기 PR에서 A/B 테스트한 뒤에 유지했습니다.

남은 지적은 심각도 순으로 정렬된 인라인 댓글이 되고, 각각 Important, Nit, Pre-existing 중 하나로 표시됩니다. Pre-existing은 이 PR이 만든 것이 아닌 기존 버그라서, 작성자의 잘못처럼 보이지 않게 구분합니다.

모든 지적에는 답해야 합니다. 고치거나, 이유를 적고 스레드를 해결 처리합니다. 에이전트가 밤사이 수정을 맡는 경우가 많아서, 작성자는 이미 한 번 더 리뷰를 거친 PR로 돌아오게 됩니다.

3단계: 병합을 막을 수 있는 보안 리뷰

보안도 별도의 자동 리뷰를 받습니다. 버그 리뷰나 보안 리뷰의 지적이 하나라도 열려 있으면 PR은 병합할 수 없습니다. 고치거나, 짧은 이유를 적고 스레드를 닫아야 하며, 오탐(False Positive)도 이 방법으로 처리합니다. 이후 커밋이 문제를 고치면 지적은 자동으로 해결됩니다.

원문은 같은 구성을 오픈소스 claude-code-security-review GitHub Action ( Claude Code Security Reviewer: 코드 변경을 Claude로 검토하는 보안 리뷰 도구)이나 /security-review 명령으로 만들 수 있다고 안내하고, 설정 방법은 Claude Code 자동 보안 리뷰 도움말에 있습니다. 다만 Action은 PR에 댓글을 남기고 /security-review 는 로컬에서 실행하는 명령이라, 병합 차단은 아래 "Code Review 제품과 Claude Code 팀 운영의 차이" 절에서 설명하는 브랜치 보호 설정으로 따로 만들어야 합니다. 또 이 Action의 README는 프롬프트 주입(Prompt Injection) 공격에 대비되어 있지 않으므로 신뢰할 수 있는 PR에만 쓰라고 경고합니다. README는 외부 기여자의 PR을 받는 공개 저장소에 대해, 유지보수자가 PR을 검토한 뒤에만 워크플로우가 실행되도록 "Require approval for all external contributors" 옵션을 켜라고 권장합니다.

4단계: 병합을 막는 자동 검사

린트, 타입 검사, 모든 플랫폼에서의 테스트, 빌드처럼 흔히 쓰는 검사입니다(그림 A에는 패키징도 들어 있습니다). 일반적인 CLI PR은 사람이 보기 전에 수십 개의 검사를 거칠 수 있습니다. 이 규모의 CI를 어떻게 확장했는지는 테스트 영향 분석(Test Impact Analysis) 글에 따로 정리되어 있습니다. PR 템플릿은 변경을 어떻게 테스트했는지, 어떻게 되돌릴지를 묻습니다. 이 칸은 Claude가 채울 수 있지만, 변경을 요청한 사람이 내용을 확인하고 승인합니다.

5단계: 위험도에 따라 사람 승인 수를 정합니다

문서 수정과 자동 업데이트 기능 변경은 위험이 다르므로 리뷰도 다르게 받습니다. 원문의 위험 등급(Risk Tier)은 다음과 같습니다.

위험도	예시	필요한 사람 승인
낮음	문서, 문구, 내부 전용 기능, 플래그 뒤에 숨긴 추가형 변경	자동 리뷰와 보안 검사가 통과하면 필요 없음
중간	일반 제품 변경, 그리고 캐싱, 자동 업데이트, 시스템 프롬프트처럼 민감한 영역의 변경	1명
높음	가장 위험한 코드, 그리고 항상 2명이 필요한 일부 경로	2명

등급은 작성자가 아니라 변경이 정합니다. 분류기(Classifier)가 변경을 읽고 등급을 고릅니다. 두 번째 분류기는 등급상 필요 없더라도 이 변경에 사람이 한 명 더 필요한지를 따로 묻습니다. 코드 소유자가 민감하다고 지정한 경로와 모든 CI 워크플로우 파일은 항상 사람이 봐야 합니다.

가벼운 경로는 신뢰 작성자만 씁니다. 저장소의 신뢰 작성자 목록(Trusted List)에 있는 사람만 가벼운 경로를 쓸 수 있고, 대개 그 저장소를 소유한 팀입니다. 그 밖의 사람은 두 번째 사람의 승인이 필요합니다. 에이전트의 승인은 사람의 승인으로 세지 않습니다. 자동 리뷰가 위험이 낮은 변경을 통과시킬 수는 있지만, 사람이 필요한 자리를 채울 수는 없습니다.

변경을 지시한 사람이 책임집니다. 에이전트가 작성한 PR에서는 에이전트에게 지시한 사람이 필수 리뷰어 한 명으로 셉니다. 그 사람이 코드를 직접 입력한 경우와 같습니다. 그리고 승인은 특정 커밋 하나에만 유효합니다. 에이전트의 push나 사람이 손으로 해결한 병합 충돌처럼 시스템이 보증할 수 없는 새 커밋이 올라오면 다시 승인을 받아야 합니다.

6단계: 병합 큐, 플래그, 단계적 배포

병합 큐(Merge Queue)는 변경을 적용한 최신 main에서 모든 검사를 다시 실행합니다. 따로따로는 통과한 PR 두 개가 합쳐져 main을 깨뜨리는 일을 막기 위해서입니다. 새 동작은 보통 기능 플래그(Feature Flag) 뒤에 두고 Anthropic 직원에게 먼저 배포하는데, 직원들이 많이 쓰기 때문에 사용자보다 먼저 회귀를 발견하는 경우가 많습니다. 공개 릴리스는 latest 채널에 먼저 나가고, stable 채널이 그 뒤를 따릅니다.

7단계: 빠른 탐지와 빠른 롤백

그래도 빠져나가는 실수가 있으므로, 마지막 층은 실수를 빨리 잡는 데 집중합니다. 플래그는 배포 없이 끌 수 있습니다. Claude Code 팀은 주 단위 온콜(On-call) 당번을 운영하고, 사고 리뷰에서는 어느 층이 이 문제를 잡았어야 했는지를 묻습니다.

저자들은 한계도 밝힙니다. 잘못된 병합을 알아차리는 일은 여전히 작성자, 온콜 담당자, 되돌림과 사고 대시보드에 의존합니다. 이 수치가 움직일 때 승인 기준을 자동으로 강화하는 서킷 브레이커(Circuit Breaker)는 아직 없고, 엔지니어들은 사람 승인 없이 병합하는 코드를 더 늘리기 전에 이 장치를 원한다고 합니다. 한 동료는 속도를 늦추면 오류율이 낮아지기는 하지만, 그 이유는 대부분 모든 일을 덜 하기 때문이라고 말했습니다. 팀은 속도를 늦추는 대신 문제를 더 빨리 알아차리고 고치는 쪽을 택했습니다.

리뷰어 자체를 개선하는 방법: 사고 평가 세트와 수렴

팀은 리뷰 과정 자체도 고리 형태로 계속 개선합니다. 원문은 세 가지 방법을 설명합니다.

모든 사고는 평가 데이터가 됩니다. 팀은 사고를 일으킨 과거 PR을 그 수정 커밋(Fix-forward)과 되돌림 커밋과 함께 모았습니다. 그리고 그 코드를 잘 아는 엔지니어가 사례마다 버그가 무엇이고 어디에 있었는지 확인했습니다. 리뷰어는 매일 이 평가 세트(Eval Set)로 채점됩니다. 리뷰어의 프롬프트, 도구, 모델을 바꿀 때마다 전체 사례에 대해 점수를 매기고, 점수가 오르면 변경을 유지하고 아니면 버립니다.

노이즈는 사람들이 댓글에 어떻게 반응했는지로 잽니다. 버그가 아닌 것까지 많이 지적하면 버그를 더 잡기는 쉽습니다. 그래서 팀은 이를 견제할 지표를 둡니다. 리뷰어가 남긴 댓글마다 PR 작성자가 어떻게 대응했는지 분류합니다. 고쳤는지, 틀렸다고 했는지, 의도된 동작이라고 했는지, 중요하지 않다고 판단했는지입니다. 또 문제가 없다고 알려진 PR에 리뷰어를 실행해, 누군가 해로운 변경을 하게 만들었을 지적을 얼마나 자주 내는지 셉니다. 팀이 문서로 정한 우선순위는 진짜 버그를 잡는 것이 첫째이고 리뷰 회차를 줄이는 것이 둘째입니다.

작성자가 에이전트이면 노이즈의 비용이 더 커집니다. 사람은 사소한 지적을 몇 초 만에 넘깁니다. 에이전트는 그 지적을 고치므로 커밋이 하나 더 생기고, 리뷰도 한 번 더 실행됩니다.

리뷰는 수렴(Convergence)해야 합니다. 에이전트 작성자와 에이전트 리뷰어는 서로를 끝없이 바쁘게 만들 수 있습니다. CLI PR 하나는 밤사이 50번 넘게 리뷰와 수정을 반복한 뒤에야 작성자가 멈췄습니다. 리뷰어가 계속 지적한 코드에 git blame을 실행해 보니 약 59%가 리뷰어의 첫 번째 리뷰 때부터 있던 코드였습니다. 리뷰어는 새 버그를 거의 찾지 못했고, 회차마다 기존 버그를 몇 개씩 더 찾고 있었습니다.

저자들은 모든 PR에서 여러 회차를 기본으로 실행하던 습관이 이 문제를 키웠다고 인정합니다. 위험한 변경이면 여러 회차가 가치가 있지만 모든 PR에 필요하지는 않습니다. 팀은 이제 재현율(Recall)과 함께 통과까지 걸린 회차 수를 추적하고, 재리뷰 방식을 다음과 같이 바꿨습니다.

회차 제한: 3회차가 지나면 리뷰어가 작성자에게 접근 방식 자체를 다시 생각해 보라고 요청합니다.
diff만 재리뷰: 처음 몇 회차 이후에는 새로 바뀐 부분만 리뷰합니다.
버그 유형으로 지적: 한 줄이 아니라 같은 유형의 모든 위치를 작성자가 고치도록 버그의 유형을 지적합니다.
반복 금지: 이미 게시한 지적은 다시 올리지 않습니다.

리뷰 에이전트는 밤마다 기존 코드도 훑어서, 오래된 버그가 다른 곳에서 문제를 일으키기 전에 찾습니다. 아래 그림(원문 그림 D)은 수렴 작업 전후의 내부 PR 수치입니다. 리뷰와 수정 1회차에 통과한 비율은 65%에서 78%로 올랐고, 5회 이상 걸린 비율은 8.9%에서 1.5%로, 통과까지의 평균 리뷰 횟수는 2.08회에서 1.32회로 줄었습니다. 원문은 비교 기간과 PR 수를 밝히지 않았습니다.

사람이 맡는 일과 코드 이해를 나누는 방법

저자들은 일상적인 실수를 잡으려고 시니어 엔지니어를 깊은 작업에서 꺼내는 비용이 자동 리뷰보다 훨씬 크다고 봅니다. 그래서 사람에게 남긴 일은 다음 다섯 가지입니다.

만들지 말지 정하기: 방향, 취향(Taste), 범위입니다. 리뷰 병목을 해결했다고 선언한 한 팀도, 팀 밖에서 온 변경에는 사람 리뷰를 남겨 두고 누군가 "이걸 해야 하는가?"를 묻게 했습니다.
위험한 코드 리뷰: 결제, 자동 업데이트, CI 워크플로우 같은 코드입니다.
아키텍처 리뷰: 다른 사람이 따라 할 패턴을 정하는 설계입니다.
증거 읽기: 테스트 출력, 실행한 명령과 그 결과, 스크린샷, 리뷰어의 지적입니다. 저자들은 검사가 무엇을 놓칠지 말할 수 없다면 빠른 승인 대신 제대로 된 리뷰를 요청하라고 권합니다.
결과에 책임지기: 누가 입력했든, 배포되는 모든 변경에는 책임지는 사람이 있습니다.

리뷰의 두 번째 일인 코드 이해 공유는 어떻게 될까요? 동료의 diff를 읽는 것은 무엇이 바뀌었고 부품들이 어떻게 맞물리는지 배우는 방법이었습니다.

저자들은 이 부분에 공식 절차가 없다고 밝힙니다. 팀원 중 누구도 Claude Code 전체를 머릿속에 담고 있지 않고, 그럴 필요도 없다고 봅니다. 코드의 한 부분을 이해하고 싶으면 정확히 그 부분에 대한 설명 문서를 Claude에게 써 달라고 합니다. 몇 분이면 되고, 오늘의 코드를 그대로 반영합니다. 일부 팀원은 한 걸음 더 나아가, 그 부분을 시각화해 자기가 좋아하는 방식으로 가르쳐 주는 작은 HTML 아티팩트를 Claude에게 만들게 합니다.

저자들은 사람의 주의를 잘 쓰는 것이 목표라면, 사소한 diff를 한 줄씩 읽는 것보다 이 방식이 낫다고 말합니다. 한 줄짜리 문구 변경에서 배울 것은 거의 없지만, 곧 바꿀 모듈의 설명 문서에서는 많이 배웁니다. 공개 Slack 채널에서 일하는 문화도 도움이 됩니다. 다른 사람이 무엇을 만드는지 만드는 도중에 보이기 때문입니다.

"병합한 사람이 책임진다"는 팀 규칙

작거나 중간 규모의 변경을 병합한 뒤 문제가 생기면, 대개 병합한 사람이 고치는 것이 팀 규칙입니다. 저자들은 이 규칙이 무리 없이 운영되는 이유를 다섯 가지로 듭니다.

변경이 작습니다: 그래서 리뷰, 디버깅, 되돌리기가 쉽습니다.
모든 것을 되돌릴 수 있습니다: 플래그, 되돌림, 단계적 배포로 대부분의 실수를 몇 분 안에 되돌립니다.
영향 범위(Blast Radius)가 기준을 정합니다: 비용이 큰 코드일수록 더 많은 사람과 검사를 거칩니다.
회귀가 빨리 드러납니다: 텔레메트리와 내부 사용 덕분입니다.
비난이 아닙니다: 고치는 사람이 맥락을 가장 많이 알고 있기 때문이며, 사고 리뷰는 사람이 아니라 시스템을 봅니다.

소유권은 공유되기도 합니다. 팀의 상당수는 Claude in Slack을 쓰는 공개 Slack 채널에서 일합니다. 그래서 누구나 다른 사람이 만드는 것을 보고 작업을 이어받거나, 빈 곳에 Claude를 투입할 수 있습니다. 코드 소유자가 아닌 사람의 피드백도 여기서 나옵니다. 저자들은 이 개방성이 모든 줄마다 관문을 두지 않고도 품질을 높게 유지하는 큰 이유라고 말합니다.

방향을 바꾸는 일도 같은 채널에서 일어납니다. 에이전트 덕분에 일을 시작하는 비용이 낮아져서, 병합하지 말아야 할 작업도 생깁니다. 보통 채널의 누군가가 이유를 묻거나, 이전 결정을 짚거나, 더 단순한 방법을 제안합니다. 그러면 작성자는 PR을 닫거나 다시 구성합니다. 코드를 빨리 썼기 때문에 PR을 닫는 것이 손실로 느껴지지 않습니다. 저자들은 다른 방향을 제안하려면 완성된 PR에 차단 댓글을 다는 대신 스레드에서 일찍 꺼내야 한다고 말합니다.

Code Review 제품과 Claude Code 팀 운영의 차이

원문이 설명하는 것은 Claude Code 팀이 자기 저장소(CLI, 데스크톱과 웹 앱, 모바일 앱)에 적용한 운영 방식입니다. 같은 구성을 Code Review for Claude Code로 따라 하려면 아래 차이를 알고 시작해야 합니다. 아래 내용은 원문이 아니라 Claude Code 공식 문서와 발표 글을 대조해 정리한 것입니다.

항목	원문의 Claude Code 팀 운영	Code Review 제품의 기본 동작
병합 차단	버그 리뷰, 보안 리뷰의 지적이 열려 있으면 병합 불가	리뷰는 PR을 승인하거나 막지 않으며, check run은 실패로 끝나지 않음
승인	소유자가 정한 저위험 변경은 자동 검사만으로 병합	승인은 사람의 몫이며 제품은 지적만 게시
지적 처리	모든 지적에 수정 또는 사유를 남기고 해결 처리	응답 없이 병합 가능. 저장소 규칙이 요구할 때만 해결 필요
재리뷰	3회차 이후 접근 방식 재검토 요청, 이후 diff만 재리뷰	문서에 회차 제한 설정은 없음. push 뒤 자동 리뷰는 바뀐 부분에 집중하고 Nit과 Pre-existing 지적을 덜 게시
실행 검증	PR 전에 Claude가 테스트, 빌드, 스크린샷으로 검증	리뷰는 코드를 빌드하거나 실행하지 않고 diff와 주변 코드만 읽음

병합 차단은 GitHub 설정으로 만듭니다. PR 리뷰 문서에 따르면, 저장소의 브랜치 보호 규칙이 병합 전 대화 해결 요구(Require Conversation Resolution)를 켜 두었을 때만 지적 스레드를 해결해야 병합할 수 있습니다. 원문처럼 모든 지적에 답해야 병합되게 하려면 이 설정이 필요합니다. 심각도별 개수로 병합을 막고 싶다면, PR 리뷰 문서의 안내대로 check run의 Details 마지막 줄에 있는 JSON을 gh 와 jq 로 읽어 자체 CI에서 판정할 수 있습니다.

REVIEW.md 의 일부 지시는 보호된 기본 브랜치에서만 적용됩니다. 사용자 지정 문서에 따르면 Code Review는 REVIEW.md 를 PR의 기준 브랜치나 기본 브랜치에서 읽고, PR이 바꾼 내용에서는 읽지 않습니다. 심각도 낮추기, 경로나 파일, 이슈 유형 제외, Nit 개수 제한 세 가지 지시는 기본 브랜치가 보호되어 있을 때만 적용되고, 보호 설정을 확인할 수 없는 구성에서는 REVIEW.md 자체를 읽지 않습니다. 그러니 REVIEW.md 를 고친 뒤에는 그 변경을 먼저 병합하고, 기본 브랜치에 보호 규칙을 걸어야 합니다. 원문이 권한 지시, 곧 이름으로 추측하지 말고 파일과 줄 번호를 근거로 대라는 지시는 이 문서에도 오탐을 줄이는 예시로 실려 있습니다.

비용은 리뷰 1건의 비용과 리뷰 횟수의 곱입니다. 비용 문서에 따르면 Code Review는 정액이 아니라 토큰 사용량으로 과금되고, 플랜에 포함된 사용량과 별도로 조직의 사용 크레딧에서 차감됩니다. 리뷰 1건의 비용은 리뷰 수준, 변경 크기, 주변 코드의 복잡도, 검증할 후보 지적의 수에 따라 달라집니다. 2026년 3월 리서치 프리뷰 발표 글은 PR 크기와 복잡도에 따라 다르지만 리뷰 1건당 평균 15~25달러라고 밝혔습니다. 관리 페이지에서 저장소를 추가하면 기본값이 After every push라서, push 횟수만큼 비용이 늘어납니다. 변경 없는 push 뒤에는 이전 결과를 유지하고 리뷰를 건너뛰기도 합니다. 문서는 넓게 도입하기 전에 월 사용 한도를 걸고 Once after PR creation이나 Manual 모드로 몇 개 저장소에서 시범 운영해 평균 비용을 재 보라고 안내합니다.

쓸 수 없는 조직도 있습니다. Code Review 문서에 따르면 GitHub(GitHub Enterprise Server 포함) 저장소만 지원합니다. Zero Data Retention이나 HIPAA 구성을 켠 조직, 고객 관리 암호화 키(CMEK)를 쓰는 조직도 쓸 수 없습니다. 같은 문서는 다른 선택지로 /code-review, 그리고 Claude Code GitHub Actions나 GitLab CI/CD로 자체 CI 러너에서 Claude를 실행하는 방법을 소개합니다. 이 선택지들이 위 조직 조건에서도 쓸 수 있는지는 Anthropic이 문서에서 따로 밝히지 않았습니다.

우리 팀에 적용하는 순서

원문 마지막 절은 같은 과정을 도입하는 순서를 단계별로 정리합니다. 대부분은 지금 있는 도구로 만들 수 있다고 저자들은 말합니다.

PR을 열기 전

에이전트가 실행할 수 있는 검사를 짧은 CLAUDE.md 에 적고, 포매터와 린터를 실행하는 훅(Hook)을 추가합니다.
로컬에서 /code-review 와 /security-review 를 실행하거나, 새 컨텍스트로 시작한 서브에이전트에게 리뷰를 맡깁니다.
REVIEW.md 를 추가하고, 반복되는 리뷰 댓글을 그 파일로 옮깁니다.

모든 PR에서

CI를 필수로 두고, PR 템플릿에 "Testing", "Risk", "How to revert" 항목을 추가합니다.
저장소 하나에 AI 리뷰어(Code Review 또는 Claude Code GitHub Action)를 추가하고, 몇 주 동안 REVIEW.md 를 조정한 뒤 범위를 넓힙니다.
자동 보안 리뷰를 추가하고, 병합 전에 모든 리뷰 스레드를 해결하도록 요구합니다.
리뷰 강도를 위험에 맞춥니다. 일상적인 변경은 빠르게, 버그를 놓치면 비싼 곳은 깊게 봅니다(Code Review의 Quick, Standard, Deep).
리뷰 회차를 제한하고, 처음 몇 회차 이후에는 새 diff만 재리뷰합니다.

승인 단계에서

위험 등급을 문서로 정하고, 작성자가 아니라 변경을 기준으로 등급을 매깁니다. 처음에는 엄격하게 시작하고 근거가 쌓이면 완화합니다.
가벼운 승인 경로는 신뢰하는 작성자에게만 엽니다.
CODEOWNERS와 브랜치 보호로 인증, 결제, CI와 릴리스 워크플로우, 설치 프로그램은 항상 사람이 보게 합니다.
봇의 승인이 필수 사람 승인을 대신하지 않게 하고, 새 커밋이 올라오면 기존 승인을 무효화합니다.

병합과 그 이후

병합 큐, 기능 플래그, 내부 우선 사용, 단계적 배포, 한 번에 되돌리는 롤백을 갖춥니다.
사고와 되돌림을 평가 세트로 만들고, 리뷰어의 프롬프트, 도구, 모델이 바뀔 때마다 다시 채점합니다.
사람의 시간을 측정하고, 되돌림과 사고 비율을 가드레일로 둡니다.

남은 과제와 수치를 읽을 때의 범위

저자들은 이 과정이 끝난 상태라고 말하지 않습니다. Code Review 발표 글은 PR 승인이 여전히 사람의 판단이라고 했고 제품도 승인이 아닌 지적만 게시합니다. 반면 Claude Code 팀의 저장소는 저위험 변경을 자동 검사만으로 병합할지 코드 소유자가 정하게 했고, 저자들은 그 경계가 계속 움직이고 있다고 밝힙니다. 리뷰가 무언가를 놓치면 팀은 모델 앞에 무엇이 없었는지 묻고, 그 답을 CLAUDE.md, 스킬, 새 검사로 반영합니다. 목표는 변경당 사람의 시간을 줄이면서 되돌림은 이전보다 늘리지 않는 것입니다.

원문 수치를 읽을 때 확인할 범위도 있습니다. 병합 PR이 2배 넘게 늘고 되돌림 비율이 상대값으로 40% 넘게 줄었다는 수치는 Claude Code 저장소의 6월부터 9월까지 결과이고, 원문은 PR의 절대 수와 되돌림 비율의 원래 값을 밝히지 않았습니다. 또 이 수치들은 여러 변화가 함께 일어난 기간의 결과라서, 원문은 개별 장치가 각각 얼마나 기여했는지 나누어 보여 주지 않습니다.

글의 끝에서 저자들은 에이전트가 PR을 여는 팀에게 어떤 검사를 자동화했는지, 어떤 검사에 여전히 사람이 필요한지, Anthropic이 무엇을 잘못 보고 있다고 생각하는지 들려 달라고 요청합니다. 에이전트 PR을 받고 있다면, 어느 단계까지 사람 승인을 줄였는지 댓글로 나눠 주셔도 좋습니다.

How the Claude Code team does code review 원문 블로그

Code Review for Claude Code 공식 문서

Bringing Code Review to Claude Code 발표 글

Claude Code Security Reviewer GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임은 이런 글들을 한국어로 정리해 나누고 있습니다. 회원으로 가입하시면 주요 글들을 이메일로 보내드리고, 텔레그램(Telegram)과 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 다음 글을 정리하는 데 힘이 됩니다~