AI가 쓴 코드를 어떻게 검토할까: Claude Code 팀의 코드 리뷰 6계층

질문이 하나 있습니다. 회사 코드의 90%를 AI가 쓴다면, 그 코드를 누가 읽고 승인할까요?

Anthropic의 Claude Code 팀은 10월 15일 공식 블로그에서 이 질문에 대한 자기 답을 공개했습니다. 결론부터 말하면, 그들은 리뷰를 없애지 않았습니다. 대신 "사람이 읽었는가"라는 질문을 버리고, "이 변경이 무엇을 망가뜨릴 수 있고, 어떤 검사가 그것을 잡아야 하는가"로 바꿨습니다.

숫자부터 보겠습니다. 6월부터 9월 사이 Claude Code 저장소에 병합된 PR은 두 배 이상 늘었습니다. 같은 기간 되돌려야 했던 PR의 비율은 40% 넘게 줄었습니다. 더 많이, 더 안전하게 머지했다는 뜻입니다.

왜 이 질문이 필요해졌나

Anthropic 모노레포에서 하루에 들어오는 변경 수는 5월 약 2,500건에서 9월 30,000건을 넘어섰습니다. Claude Code는 별도 저장소지만 압력은 같습니다.

[5월]  하루 변경 약 2,500건
[9월]  하루 변경 30,000건 이상

이 규모에서 사람이 한 줄씩 읽는 리뷰는 불가능에 가깝다.
그런데 리뷰를 빼면 품질이 무너진다. 그래서 질문 자체를 바꿨다.

블로그가 정의하는 코드 리뷰의 두 가지 역할은 이렇습니다.

출시 전에 문제를 찾아 고친다
팀 전체에 코드베이스 이해를 공유한다

이 글은 대부분 1번에 집중합니다. 그런데 2번에 대한 답도 글 끝에 나옵니다.

핵심 재정의는 이 문장입니다. "사람이 코드를 읽었는가"는 "이 변경이 무엇을 망가뜨릴 수 있고, 어떤 검사(자동이든 사람이든)가 그것을 잡아야 하는가"에 대한 부정확한 대리 지표라는 것입니다. 이 질문을 택하면 리뷰가 일어나는 시점도 바뀝니다. 예전에는 코드를 다 쓰고 PR을 열고 동료를 기다리는 마지막 관문이었습니다. 이제는 마치 글을 쓰면서 맞춤법 검사를 돌리듯, 리뷰가 상시로 돌아갑니다. 대부분의 변경은 사람이 보기 전에 이미 Claude에게 최소 한 번 검토되고 고쳐집니다.

희소 자원은 사람의 시간이다

목표는 명확합니다. Claude Code 저장소(CLI, 데스크톱·웹 앱, 모바일 앱)의 대부분 PR이, 되돌림이나 장애 증가 없이, 최대 한 명의 사람(작성자 본인 포함)만 거치고 머지되는 것.

여기서 중요한 구분이 있습니다. 사람의 시간은 두 갈래입니다.

사람의 시간 비용 = (리뷰에 쓰는 시간) + (나쁜 코드가 깨뜨린 것을 고치는 시간)

앞만 줄이고 뒤가 늘면, 시간을 아낀 게 아니라 옮긴 것이다.
그래서 핵심 지표는 '사람 승인 수'와 '되돌림·장애율'을 함께 본다.

측정 방식도 구체적입니다. PR당 사람 승인 수(중앙값과 95백분위), 사람이 남긴 코멘트 수, 사람을 기다린 시간을 추적합니다. 되돌림과 장애율은 안전장치(guardrail)입니다. 이게 오르면 시간을 아낀 게 아니라 미룬 것입니다.

변경 하나의 생애: 6계층

블로그의 그림을 그대로 옮기면, 변경 하나는 이런 층을 지납니다.

[PR 이전]
  ① 검증        : Claude가 테스트·빌드·린트를 실행.
                  새 컨텍스트의 서브에이전트가 diff를 다시 리뷰.
                  내부 스킬(버그 탐색·diff 단순화·end-to-end 확인) 추가 실행

[모든 PR]
  ② 필수 CI     : 린트·타입·전 플랫폼 테스트·빌드·패키징. 빨간불이면 머지 차단
  ③ AI 리뷰     : 여러 에이전트가 병렬로 버그를 찾고,
                  별도 에이전트들이 각 발견에 투표.
                  충분히 동의한 것만 게시. 스타일·정리 코멘트는 폐기
  ④ 보안 리뷰   : 별도 패스. 어느 리뷰든 미해결 발견이 있으면 머지 차단
  ⑤ 위험 기반 승인: 분류기가 등급 결정 → 사람 0명 / 1명 / 2명

[머지]
  ⑥ 머지 큐     : main에 변경을 적용한 상태로 모든 검사를 다시 실행

[머지 이후]
  ⑦ 플래그·점진 배포: 내부 사용 → 최신 채널 → 안정 채널
  ⑧ 감시 후 수정 또는 롤백: 플래그는 배포 없이 끄고, 깨진 빌드는 되돌린다

이 구조의 요점은 "관문 하나가 아니라 층 여러 개"라는 것입니다. 각 층은 어떤 문제는 잡고 어떤 문제는 놓칩니다. 여러 층을 다 통과하는 문제는 거의 없고, 마지막으로 롤백이 나머지를 처리합니다.

계층별로 조금 더

1. 남이 보기 전에 스스로 검증한다

리뷰의 대부분은 PR이 생기기 전에 끝납니다. 방법은 단순합니다. Claude에게 "실행할 수 있는 것"을 주고, "됐다"고 말하는 대신 그 증거를 보여주게 합니다. 테스트, 빌드, 혹은 디자인과 비교할 스크린샷 같은 것들입니다.

Claude Code를 만든 Boris Cherny는 "Claude에게 자기 작업을 검증할 방법을 주는 것"이 좋은 결과를 얻는 데 아마 가장 중요한 요소라고 말합니다. 마지막 결과를 두세 배 더 좋게 만든다고 추정합니다. 검증의 형태는 도메인마다 다릅니다. bash 명령 하나일 수도, 테스트 스위트일 수도, 브라우저나 폰 시뮬레이터에서 앱을 직접 확인하는 것일 수도 있습니다.

같은 문제를 리뷰어가 반복해서 지적하면, 코멘트를 무시하는 게 아니라 원인을 고칩니다. 스킬, 린트 규칙, 그리고 안내 파일을 업데이트합니다.

CLAUDE.md : 이 프로젝트가 무엇인지 (스택, 관례, 목표, 비목표)
             크면 짧게 유지하고 다른 문서로 연결. 리뷰마다 로드된다
REVIEW.md : 코드 오너가 작성. "내 영역에서 중요한 것"을 리뷰어에게 알린다
             실패가 어떤 모습인지(문서면 "거짓말", 설정이면 "잘못 라우팅")
             니트 상한, 건너뛸 경로, 이름 추측 대신 파일·줄 근거 요구

2. 모든 PR에 AI 리뷰가 붙는다

모든 PR은 사람이 보기 전에 Claude 리뷰를 받습니다. diff를 저장소 전체와 PR의 의도에 비추어 "이 변경이 문제를 해결하는가, 시스템에 맞는가, 다른 것을 깨뜨리는가"를 묻습니다.

리서치 프리뷰 당시, 실질적인 리뷰 코멘트를 받은 내부 PR 비율은 16%에서 54%로 올랐습니다. 대부분 1,000줄이 넘는 PR은 발견 사항이 나오고, 작은 PR은 깨끗하게 돌아옵니다. 저장소마다 Quick, Standard, Deep 중 하나를 설정하고, 놓친 버그의 비용이 큰 곳에는 Deep을 씁니다.

여기서 노이즈를 줄이는 장치가 인상적입니다. 발견 사항은 사람에게 가기 전에 다른 에이전트들이 검증합니다.

[병렬 탐색]  여러 에이전트가 동시에 버그를 찾는다
     ↓
[투표]      별도 그룹이 각 발견에 대해 "진짜인가"를 투표.
            충분한 동의가 없으면 게시하지 않는다
     ↓
[필터]      스타일·진단·정리성 코멘트는 폐기
            (자체 PR로 A/B 테스트해서 이 필터를 남겼다)
     ↓
[게시]      인라인 코멘트를 심각도 순으로 정렬
            각 코멘트에 Important / Nit / Pre-existing 태그
            (PR이 만들지 않은 버그가 작성자 잘못처럼 보이지 않게)

블로그 표현대로 "모든 발견 사항은 답을 받아야 합니다." 고치거나, 이유를 적어 스레드를 닫거나. 흔히 에이전트가 밤사이 수정을 집어가서, 작성자가 돌아오면 이미 한 라운드를 더 거친 PR을 만납니다.

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

보안은 별도의 자동 리뷰를 받습니다. 버그 리뷰든 보안 리뷰든 미해결 발견이 있으면 머지할 수 없습니다. 고치거나 짧은 사유와 함께 스레드를 닫으면 오탐이 해소됩니다. 이후 커밋이 문제를 고치면 발견이 스스로 사라집니다. 오픈소스 보안 리뷰 GitHub Action이나 /security-review 명령으로 같은 것을 구성할 수 있습니다.

4. 승인은 위험도에 따라 나뉜다

여기가 팀 적용에서 가장 참고할 만한 표입니다.

위험도	예시	필요한 사람 승인
낮음	문서, 카피, 내부 전용 기능, 플래그 뒤의 추가적 변경	자동 리뷰와 보안 검사가 통과하면 없음
중간	일반 제품 변경, 캐싱·자동 업데이터·시스템 프롬프트 같은 민감 영역	1명
높음	최고 위험 코드, 항상 두 사람이 필요한 소수의 경로	2명

중요한 규칙들:

등급을 정하는 것은 작성자가 아니라 변경 내용입니다. 분류기가 읽고 등급을 정합니다. 두 번째 분류기가 "이 등급이면 사람이 필요 없다"는 경우에도 이 특정 변경에 사람이 필요한지 다시 묻습니다.
소유자가 민감하다고 지정한 경로, 그리고 모든 CI 워크플로 파일은 항상 사람이 필요합니다.
신뢰 목록에 있는 작성자만 가벼운 경로를 씁니다. 에이전트의 승인은 사람의 자리를 채우지 못합니다.
변경을 지시한 사람이 책임자입니다. 에이전트가 쓴 PR에서도 에이전트를 지시한 사람이 필수 리뷰어 한 명으로 계산됩니다.
승인은 특정 커밋에만 유효합니다. 시스템이 보증하지 못하는 커밋(에이전트의 푸시, 손으로 해결한 머지)이 들어오면 다시 승인받아야 합니다.

5. 머지 큐와 플래그

머지 큐는 main에 변경을 적용한 상태로 모든 검사를 다시 돌립니다. 각각 통과한 두 PR이 합쳐지며 main을 깨뜨리는 것을 막습니다. 새 동작은 보통 먼저 Anthropic 직원에게 플래그로 배포되고, 직원들의 헤비한 사용이 사용자보다 먼저 회귀를 드러냅니다.

6. 빠른 감지, 빠른 롤백

그래도 실수는 남습니다. 마지막 층은 그것을 빨리 잡는 데 집중합니다. 플래그는 배포 없이 끌 수 있고, 주간 온콜 로테이션이 돌며, 장애 리뷰에서 "어느 층이 잡았어야 했는가"를 묻습니다.

여기서 정직한 부분도 있습니다. 되돌림과 장애 대시보드의 수치가 움직이면 승인을 더 엄격하게 조이는 회로 차단기는 아직 없다고 밝힙니다. 더 많은 코드가 사람 0명 머지로 넘어가기 전에 그것을 원한다고 씁니다.

전: 리뷰어를 더 좋게 만드는 루프

이 프로세스는 돌면서 계속 좋아집니다. 여기서 실무적으로 가장 값진 부분이 나옵니다.

[장애·되돌림] → [전문가가 확인한 케이스] → [평가셋에 추가]
      ↑                                            ↓
[리뷰어 변경]  ← [점수 올랐나?] ← [매일 전체 케이스로 채점]
                    (프롬프트·도구·모델 변경마다 채점)

과거에 장애를 낸 PR을 모아, 그 수정과 롤백까지 정리하고, 그 코드를 아는 엔지니어가 각 버그를 확인합니다. 리뷰어는 이 세트를 매일 돌립니다.

노이즈는 사람들의 행동으로 측정합니다. 코멘트를 "고쳤다 / 틀렸다고 했다 / 의도된 동작이었다 / 중요하지 않다고 판단했다"로 정렬합니다. 깨끗한 PR에 리뷰어를 돌려서 해로운 변경으로 이끌 만한 것을 얼마나 자주 보고하는지도 셉니다. 우선순위는 명문화되어 있습니다. 진짜 버그를 잡는 것이 먼저, 리뷰 라운드를 줄이는 것이 그다음.

그리고 아주 구체적인 실패 사례가 나옵니다.

에이전트 작성자 + 에이전트 리뷰어는 서로를 무한히 붙들 수 있다.
CLI PR 하나가 밤사이 50라운드가 넘는 리뷰와 수정을 돌다가 멈췄다.

반복 지적된 코드에 git blame을 돌려보니 약 59%가
리뷰어의 첫 패스부터 있던 코드였다.
= 리뷰어가 새 버그를 찾은 게 아니라, 오래된 버그를
  라운드마다 조금씩 더 찾고 있었다.

그래서 재리뷰를 바꿨습니다. 3라운드가 지나면 리뷰어가 작성자에게 접근을 다시 생각하라고 요청합니다. 처음 몇 번 이후에는 새 diff만 재리뷰합니다. 버그의 부류를 표시해서 한 줄이 아니라 모든 인스턴스를 고치게 합니다. 이미 게시한 발견은 반복하지 않습니다. 결과는 이렇습니다.

지표	이전	수렴 작업 이후
리뷰·수정 한 번에 통과	65%	78%
5회 이상 라운드 필요	8.9%	1.5%
평균 통과까지 리뷰 횟수	2.08	1.32

사람은 어디에 남는가

사람의 자리는 "기계가 못하는 결정"으로 옮겨갑니다.

① 정말 만들어야 하나 — 방향, 취향, 범위
   (리뷰 병목이 해소됐다고 선언한 팀도 팀 밖에서 온 변경은
    여전히 사람이 본다. "이걸 해야 하나?"를 누군가 묻기 위해)
② 위험한 코드 — 빌링, 자동 업데이터, CI 워크플로
③ 아키텍처 — 다른 사람이 따라 할 패턴
④ 증거 읽기 — 테스트 출력, 실행한 명령과 결과, 스크린샷, 리뷰 발견
   (이 검사가 무엇을 놓칠지 말할 수 없다면, 빠른 승인 대신 진짜 리뷰를 요청)
⑤ 결과 소유 — 누가 타이핑했든, 출시된 모든 변경에 사람이 책임진다

2번째 역할(코드베이스 이해 공유)에 대한 답도 여기 있습니다. 아무도 Claude Code 전체를 머릿속에 담고 있지 않고, 담을 필요도 없다고 말합니다. 어떤 부분을 이해하고 싶으면 Claude에게 바로 그 조각에 대한 설명(explainer)을 써달라고 합니다. 몇 분이면 되고, 지금의 코드를 반영합니다.

그리고 팀 규범 하나가 제목처럼 붙습니다. "You land it, you own it." 작거나 중간 규모의 변경을 머지했는데 문제가 생기면, 보통 본인이 고칩니다. 이게 나쁘게 흐르지 않는 이유는 변경이 작고, 되돌리기 쉬우며, 폭발 반경이 기준을 정하고, 회귀가 텔레메트리로 빨리 드러나기 때문입니다. 책임이지 비난이 아닙니다.

결론: 팀에 적용하는 순서

블로그는 우리 팀이 오늘 바로 쓸 수 있는 목록을 제공합니다.

[PR 이전]
[ ] 에이전트에게 실행할 검사를 준다 (짧은 CLAUDE.md + 포매터/린터 훅)
[ ] 로컬에서 /code-review, /security-review 실행
    (또는 새 컨텍스트의 서브에이전트 리뷰)
[ ] REVIEW.md를 만들고, 반복되는 코멘트를 그쪽으로 옮긴다

[모든 PR]
[ ] CI를 필수로. PR 템플릿에 Testing / Risk / How to revert 추가
[ ] 한 저장소에 AI 리뷰어를 붙이고 몇 주 동안 REVIEW.md를 조정한 뒤 확대
[ ] 자동 보안 리뷰 추가. 머지 전에 모든 리뷰 스레드 해결을 요구
[ ] 위험도에 맞춰 리뷰 강도를 조절 (Quick / Standard / Deep)
[ ] 리뷰 라운드에 상한을 둔다. 초반 몇 번 이후엔 새 diff만 재리뷰

[승인]
[ ] 위험 등급을 문서화. 작성자가 아니라 변경으로 정한다
[ ] 초기에는 엄격하게, 증거가 쌓이면 완화
[ ] CODEOWNERS와 브랜치 보호로 인증·빌링·CI·릴리스 워크플로·설치 프로그램은 항상 사람
[ ] 봇 승인이 필수 사람 자리를 대체하지 못하게. 새 커밋에서 승인 무효화

[머지와 이후]
[ ] 머지 큐, 피처 플래그, 내부 우선 사용, 단계적 릴리스, 한 단계 롤백
[ ] 인시던트와 되돌림을 평가셋으로 만들고, 리뷰어 변경 시마다 다시 채점
[ ] 사람 시간을 측정하되, 되돌림·장애율을 안전장치로 둔다

한 줄로 요약하면 이렇습니다.

"사람이 읽었는가"를 묻지 말고,
"무엇이 잘못될 수 있고, 그걸 누가 잡는가"를 물어라.

이 전환은 AI가 코드를 많이 쓰는 시대의 리뷰를 "감시"에서 "설계"로 바꿉니다. 리뷰를 자동화했다는 말보다, 검증 가능한 시스템을 만들었다는 말이 더 정확합니다. 하네스 엔지니어링이 무엇인지 궁금하면 하네스 엔지니어링이란?에서 이어 볼 수 있습니다.

참고 자료

이 주제를 직접 따라가며 배우고 싶다면

위 계층을 내 저장소에 그대로 옮기려면, 먼저 Claude Code가 무엇을 읽고 어떤 도구를 쓰는지 이해해야 합니다. CLAUDE.md와 REVIEW.md, 훅과 서브에이전트, 승인 규칙을 직접 붙여보면 리뷰가 어떻게 하네스가 되는지 체감할 수 있습니다.

Claude Code·하네스 엔지니어링 강의 보기