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

목차

1. 배경 — 리뷰가 병목이 된 이유
2. 질문을 바꾸다 — ‘누가 읽었나’에서 ‘무엇을 누가 잡아야 하나’로
3. 변경 하나가 거치는 6단계 검사
4. 위험도에 따른 사람 승인
5. 리뷰어를 개선하는 방법
6. 사람에게 남는 일
7. 우리 팀에 적용한다면
8. 요약

이 글은 Anthropic 블로그의 How the Claude Code team does code review (Addy Osmani, Morgan Westlee Lunt, Qing Wang, 2026-10-15)를 읽고 핵심만 내 방식대로 정리한 것이다. 원문 전체 번역이 아니므로 세부 내용은 원문을 함께 보는 편이 좋다.

글에 나오는 수치(16%→54%, revert 40% 이상 감소 등)는 모두 Anthropic 내부 지표이고, 원문에 외부 검증 근거는 없다.

1. 배경 — 리뷰가 병목이 된 이유

Claude Code 코드의 약 90%는 Claude가 작성한다. 에이전트가 코드를 쓰기 시작하면서 변경량이 폭증했다.

• Anthropic 모노레포에 하루에 머지되는 변경 수: 5월 약 2,500건 → 9월 30,000건 이상
• Claude Code 레포의 머지된 PR 수: 6월 → 9월 사이 2배 이상

사람이 모든 diff를 일일이 읽기에는 너무 많은 양이다. 그런데 같은 기간 revert가 필요한 PR 비율은 오히려 40% 이상 줄었다. 리뷰를 없앤 게 아니라, 읽는 일 대부분을 자동화하고 사람은 꼭 필요한 판단에만 시간을 쓰도록 절차를 바꾼 결과라고 한다.

2. 질문을 바꾸다 — ‘누가 읽었나’에서 ‘무엇을 누가 잡아야 하나’로

원문은 코드 리뷰가 하는 일을 둘로 나눈다.

1. 배포 전에 문제를 찾아 고치기
2. 팀이 코드베이스를 함께 이해하기

그리고 첫 번째 일에서 던지는 질문을 바꾼다. 핵심 질문은 “사람이 읽었는가?”가 아니라 “무엇이 잘못될 수 있고, 자동 검사와 사람 중 어느 쪽이 그걸 잡아야 하는가?” 다.

이 관점에서 리뷰는 마지막에 한 번 통과하는 관문이 아니라, 코드를 쓰는 동안 계속 피드백을 주는 맞춤법 검사기에 가까워진다. 대부분의 변경은 사람에게 가기 전에 Claude가 이미 한 번 이상 리뷰하고 고친 상태다.

목표도 숫자로 정했다.

• 목표: 대부분의 PR이 사람 한 명 이하만 거쳐 머지되는 것. 작성자 본인도 이 한 명에 들어간다.
• 측정: PR당 사람 승인 수, 사람 코멘트 수, 사람의 리뷰나 승인을 기다린 시간
• 안전장치: revert율과 장애율. 두 지표가 오르면 리뷰 시간을 줄인 게 아니라 그 부담을 장애 대응으로 미룬 셈이다.

마지막 항목이 핵심이라고 느꼈다. 리뷰 시간을 줄였다고 끝이 아니라, 그 시간이 장애 대응으로 돌아오지 않는지까지 함께 봐야 한다.

3. 변경 하나가 거치는 6단계 검사

검사 한 번에 모든 걸 맡기지 않고 여러 단계를 둔다. 단계마다 잡는 문제와 놓치는 문제가 다르다.

그리고 이 모든 단계 아래에 빠른 롤백이 깔려 있다.

작성자 측 검증이 먼저다

Boris Cherny(Claude Code 개발자)는 Claude에게 검증 수단을 주는 것이 가장 중요하다고 말한다. 그렇게 하면 결과물 품질이 2~3배 좋아진다고 추정한다. “끝났다”는 말 대신 테스트 출력이나 스크린샷을 보여 달라고 하라는 것이다.

AI 리뷰어가 같은 문제를 반복해서 지적하면, 코드만 고치고 넘어가지 않고 지침이나 검사 규칙을 고친다. 스킬, 린트 규칙, 지침 파일 중 하나에 반영하는 식이다.

• CLAUDE.md: 스택, 컨벤션, 목표, 하지 않을 일. 짧게 유지한다.
• REVIEW.md: 코드 오너가 작성하는 리뷰 기준. 이 레포에서 “실패”가 무엇인지 정의하고, 사소한 지적(nit)의 개수에 상한을 둔다. 지적마다 근거가 되는 파일과 줄 번호를 적게 하고, 고칠 게 없으면 그 사실도 명시하게 한다.

AI 리뷰의 노이즈를 어떻게 줄였나

• 지적을 바로 올리지 않고 다른 에이전트 그룹이 투표해서 충분히 동의를 얻은 것만 게시한다.
• 코드 스타일이나 단순 정리에 관한 지적은 걸러낸다. 이 필터는 사내 PR로 A/B 테스트했다.
• 지적마다 Important, Nit, Pre-existing 태그를 붙인다. Pre-existing은 원래 있던 버그를 작성자 탓으로 돌리지 않기 위한 장치다.
• 모든 지적에는 응답해야 한다. 고치거나, 이유를 적고 닫는다.

Research Preview를 도입한 뒤 의미 있는 리뷰 코멘트가 달린 사내 PR 비율은 16%에서 54%로 올랐다. 레포마다 빠른 검토(Quick) / 표준 검토(Standard) / 심층 검토(Deep) 중 하나를 고를 수 있고, 버그 하나를 놓쳤을 때 피해가 큰 레포에는 Deep을 쓴다.

공개 제품으로는 Code Review for Claude Code(Team/Enterprise)가 있고, 로컬에서는 /code-review, /security-review 명령으로 비슷한 리뷰를 돌릴 수 있다.

4. 위험도에 따른 사람 승인

규칙이 꽤 촘촘하다.

• 작성자가 등급을 고르지 않는다. 분류기가 변경 내용을 보고 등급을 정하고, 두 번째 분류기가 “그래도 사람이 봐야 하나”를 다시 묻는다.
• 민감 경로와 CI 워크플로 파일은 항상 사람이 본다.
• 승인 단계를 줄이는 경로는 신뢰 작성자 목록에 있는 사람만 이용할 수 있다.
• 에이전트의 승인은 사람의 승인으로 치지 않는다.
• 에이전트에게 PR 작성을 시킨 사람은 필수 리뷰어가 된다.
• 승인은 특정 커밋에만 유효하다. 시스템이 보증할 수 없는 커밋이 새로 올라오면 다시 승인받아야 한다.

5. 리뷰어를 개선하는 방법

개인적으로 가장 흥미로웠던 부분이다.

장애 사례로 평가 세트를 만든다

과거에 장애를 낸 PR을 모으고, 엔지니어가 버그와 위치를 확인해 평가 세트를 만들었다. 이 세트로 리뷰어를 매일 평가한다. 프롬프트, 도구, 모델을 바꿀 때마다 전체 사례로 점수를 매긴다. 점수가 오른 변경만 반영하고 나머지는 버린다. 장애가 하나 생기면 사례도 하나 늘어난다.

노이즈도 따로 측정한다. 먼저 작성자가 지적에 어떻게 반응했는지(고침 / 틀렸다고 함 / 의도된 것 / 상관없음)로 분류한다. 또 문제없는 것으로 확인된 PR에도 리뷰어를 돌려서, 쓸데없는 수정을 유도한 지적이 몇 건 나오는지 센다.

리뷰 왕복이 끝나지 않는 문제

작성자가 에이전트이면 노이즈 비용이 더 커진다. 에이전트는 nit까지 전부 고치기 때문에 커밋과 왕복이 계속 늘어난다.

실제로 한 PR에서는 밤새 리뷰와 수정이 50차례 넘게 오갔다. git blame으로 보니 리뷰어가 계속 지적한 코드의 약 59%는 첫 리뷰 때부터 있던 코드였다. 새 버그를 잡은 게 아니라 원래 있던 버그를 조금씩 더 찾아내고 있었던 셈이다.

대응은 다음과 같다.

• 3회 왕복 후에는 접근 방식 자체를 다시 생각해 보라고 요청
• 처음 몇 번 이후에는 그다음에 바뀐 부분만 다시 리뷰
• 같은 유형의 버그는 유형 단위로 지적해서 한 번에 고치게 함
• 이미 게시한 지적은 반복하지 않음
• 기존 코드의 오래된 버그는 야간 리뷰 에이전트가 따로 담당

리뷰어가 버그를 얼마나 빠짐없이 찾는지만 보지 않고, 통과할 때까지 리뷰가 몇 번 오가는지까지 함께 본다는 점이 인상적이었다.

6. 사람에게 남는 일

자동화가 늘어도 사람이 맡는 일은 분명하다.

• 만들지 말지 결정하기: 방향, 취향, 범위
• 위험한 코드 리뷰: 결제, 자동 업데이트, CI 워크플로
• 이후 코드가 따라 할 구조나 설계 리뷰
• 증거 읽기: 테스트 출력, 스크린샷, 리뷰 지적. 증거를 읽는 사람이 자동 검사가 놓칠 부분을 설명할 수 없다면, 사람에게 제대로 리뷰를 요청해야 한다.
• 결과에 대한 책임: “머지한 사람이 책임진다”가 팀 규칙이다. 이 원칙이 작동하려면 변경이 작고, 모든 변경을 되돌릴 수 있고, 회귀를 빨리 감지할 수 있어야 하며, 장애 회고에서 사람을 탓하지 않아야 한다.

리뷰의 두 번째 역할인 맥락 공유에는 정해진 절차가 없다. Claude Code 전체를 머릿속에 담고 있는 사람은 없다. 개발자는 필요할 때 Claude에게 해당 부분을 설명해 달라고 해서 맥락을 파악한다. 사소한 diff를 한 줄씩 읽는 것보다 이게 낫다고 한다.

한계도 솔직하게 밝힌다. 문제 감지는 아직 사람과 대시보드에 의존한다. revert율이나 장애율이 오르면 사람 승인 요건을 자동으로 강화하는 장치(서킷 브레이커)도 아직 없다. 사람 없이 머지하는 범위를 넓히기 전에 이걸 먼저 갖추고 싶어 한다.

7. 우리 팀에 적용한다면

원문 마지막에 도입 체크리스트가 있다. 그중 바로 해볼 만한 것만 추렸다.

PR 전

• 짧은 CLAUDE.md에 돌려야 할 검사를 적고, 훅으로 포매터와 린터를 실행
• 로컬에서 /code-review, /security-review 실행
• 반복되는 리뷰 지적을 REVIEW.md로 옮기기

PR

• PR 템플릿에 Testing, Risk, How to revert 항목 추가
• AI 리뷰어는 레포 하나에 먼저 도입하고, 몇 주간 REVIEW.md를 조정한 뒤 넓히기
• 리뷰 왕복에 상한 두기

승인

• 변경 내용을 기준으로 위험 등급을 정하고, 처음엔 엄격하게 시작해서 근거가 쌓이면 완화
• CODEOWNERS와 브랜치 보호로 인증, 결제, CI, 릴리스 관련 변경은 항상 사람이 보게 하기
• 봇 승인으로 사람 승인을 대체하지 않기, 새 커밋이 올라오면 승인 무효화

머지 후

• 기능 플래그, 단계적 배포, 바로 실행할 수 있는 롤백 절차
• 장애와 revert를 모아 리뷰어 평가 세트로 쓰기

결제 도메인에서 일하는 입장에서는 “저위험 등급은 사람 없이 머지”까지 가기는 어렵겠지만, 작성자 측 검증 강화, REVIEW.md로 반복 지적 줄이기, revert율을 안전장치 지표로 두기는 지금 바로 적용할 수 있다고 본다.

8. 요약

• 질문을 ‘사람이 읽었나’에서 ‘무엇을 누가 잡아야 하나’로 바꿨다.
• 검사 한 번 대신 6단계를 두고, 그 아래에 빠른 롤백을 깔았다.
• 사람 승인 수는 작성자가 아니라 변경의 위험도로 정한다. 에이전트의 승인은 사람의 승인으로 치지 않는다.
• 리뷰어는 장애 사례로 만든 평가 세트로 매일 평가하고, 노이즈와 왕복 횟수도 함께 측정한다.
• 아낀 리뷰 시간이 장애 대응으로 돌아오지 않는지 revert율과 장애율로 확인한다.

Ref.

• How the Claude Code team does code review — Claude Blog
• Claude Code Best Practices
• Code Review for Claude Code