Claude Code 팀은 코드 리뷰를 어떻게 하나

claude-codecode-reviewai-agent

안녕하세요! 재니미입니다.

Claude Code 팀이 자기 팀의 코드 리뷰 방식을 공개했습니다. 요지는 리뷰를 없앤 것이 아니라 읽는 일 대부분을 기계에 넘기고, 사람의 시간은 위험한 변경에만 쓰도록 바꿨다는 것입니다. 그 결과 6월부터 9월 사이 머지된 PR은 두 배 넘게 늘었는데, 되돌린(revert) 비율은 40% 넘게 줄었다고 합니다. 이번 글에서는 이 과정을 단계별로 정리했습니다.

이 글은 claude.dev 블로그의 How the Claude Code team does code review를 읽고 정리한 것입니다. 수치는 모두 원문에 실린 결과입니다.

문제: 사람이 다 읽을 수 없는 양

Claude Code 코드의 약 90%는 Claude가 씁니다. 회사 전체로 보면 변경량이 더 극적입니다. Anthropic은 여러 프로젝트의 코드를 저장소 하나에 모아 관리하는 모노레포(monorepo)를 쓰는데, 여기에 하루에 들어오는 변경이 5월 약 2,500건에서 9월 3만 건 이상으로 늘었습니다. 이 변화 때문에 git을 떠나게 된 이야기는 「AI가 코드를 너무 많이 쓰면 git이 막힌다」에서 다뤘습니다. Claude Code는 이 모노레포와 별개의 저장소를 쓰지만 같은 압박을 받고 있습니다. 이 속도에서는 한 줄씩 읽는 리뷰가 사실상 불가능합니다.

그래서 팀은 질문을 바꿨습니다. “사람이 코드를 읽었는가” 대신 “이 변경에서 무엇이 잘못될 수 있고, 그걸 잡을 검사는 사람과 자동화 중 무엇이 맞는가”를 묻습니다. 목표는 대부분의 PR이 사람 한 명(작성자 본인이어도 됨)만 거쳐 머지되면서도 되돌림과 장애가 늘지 않는 것입니다.

PR 전에 대부분 리뷰가 끝난다

리뷰는 이제 마지막 관문이 아니라 글을 쓰는 동안 돌아가는 맞춤법 검사에 가깝습니다.

  • Claude에게 테스트, 빌드, 디자인 비교용 스크린샷처럼 실행할 수 있는 검증 수단을 주고, “다 했다”는 말 대신 결과를 보여달라고 합니다.
  • 새 컨텍스트의 서브에이전트가 diff를 다시 리뷰합니다.
  • PR을 열기 전에 버그 찾기, diff 단순화, 전체 동작 확인용 스킬을 돌립니다.

같은 지적이 반복되면 리뷰어를 탓하지 않고 근원을 고칩니다. 스킬이나 린트 규칙(코드를 실행하지 않고 실수를 자동으로 찾아내는 검사 규칙)을 고치거나, 프로젝트 설명서인 CLAUDE.md, 코드 소유자가 쓰는 리뷰 기준서 REVIEW.md를 고칩니다.

PR에 붙는 자동 리뷰

모든 PR은 사람이 보기 전에 Claude 리뷰를 받습니다. 여러 에이전트가 동시에 버그를 찾고, 다른 에이전트 그룹이 각 지적이 진짜인지 투표해서 통과한 것만 댓글로 남깁니다. 스타일이나 정리 수준의 지적은 걸러냅니다. 연구 프리뷰를 낸 뒤 실질적인 리뷰 댓글이 달리는 사내 PR 비율이 16%에서 54%로 올랐습니다.

모든 지적에는 답해야 합니다. 고치거나, 이유를 적고 스레드를 닫습니다. 보안 리뷰도 따로 돌고, 열린 지적이 남아 있으면 머지할 수 없습니다.

위험도에 따라 사람 수가 정해진다

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

위험도는 작성자가 아니라 변경 내용으로 정해집니다. 분류기가 변경을 읽고 등급을 매기고, 다른 분류기가 등급과 별개로 사람이 더 필요한지 한 번 더 봅니다. 가벼운 경로는 신뢰 목록에 있는 작성자만 탈 수 있고, 에이전트의 승인은 사람의 승인으로 치지 않습니다. 에이전트에게 일을 시킨 사람이 그 PR의 리뷰어 중 한 명으로 책임을 집니다.

실수는 빨리 잡고 빨리 되돌린다

머지 큐는 main에 변경을 얹은 상태로 검사를 다시 돌립니다. 새 기능은 대부분 플래그 뒤에 숨겨 사내에 먼저 내보내고, 배포 없이 플래그를 끌 수 있습니다. 장애 회고에서는 “어느 단계가 잡았어야 했나”를 묻습니다.

느리게 가면 오류율이 줄긴 하지만, 그건 주로 모든 일을 덜 하기 때문이라는 동료의 말이 인용돼 있습니다. 팀은 속도를 늦추는 대신 문제를 알아채고 고치는 속도를 높이는 쪽을 택했습니다.

리뷰어도 측정하고 고친다

  • 과거에 장애를 일으킨 PR을 모아 평가 세트로 만들고, 리뷰어를 매일 그 세트에 돌립니다.
  • 리뷰 댓글마다 사람이 어떻게 반응했는지(고침, 틀렸다고 함, 의도된 동작이라 함, 중요하지 않다고 함)를 분류해 잡음을 잽니다.

에이전트 작성자와 에이전트 리뷰어는 서로를 끝없이 붙잡을 수 있습니다. 한 PR은 밤새 50번 넘게 리뷰와 수정을 오갔고, 반복된 지적의 약 59%는 첫 리뷰 때부터 있던 코드였습니다. 새 버그를 찾은 게 아니라 원래 있던 문제를 라운드마다 몇 개씩 더 찾아낸 것입니다.

그래서 리뷰가 끝나도록 장치를 넣었습니다.

  • 라운드 상한: 세 라운드가 지나면 리뷰어가 작성자에게 접근 방식을 다시 생각해 보라고 요청합니다.
  • 바뀐 부분만 다시 리뷰: 처음 몇 번 이후에는 새로 바뀐 부분만 봅니다.
  • 버그를 종류째로 지적: 한 줄이 아니라 같은 종류의 실수를 한 번에 모두 고치게 합니다.
  • 같은 지적은 반복하지 않음: 이미 남긴 지적은 다시 달지 않습니다.

이 장치를 넣은 뒤 사내 PR 하나당 리뷰 라운드가 줄었다고 합니다. 팀이 적어 둔 우선순위는 진짜 버그를 잡는 것이 먼저이고, 리뷰 라운드를 줄이는 것이 그다음입니다.

코드 이해는 어떻게 나누나

리뷰의 또 다른 역할은 팀이 코드를 함께 이해하는 것입니다. 기계가 대부분을 읽으면 사람은 어떻게 코드를 배우냐는 질문에, 팀은 필요한 부분만 Claude에게 설명 문서를 써달라고 한다고 답합니다. 사소한 diff를 한 줄씩 읽는 것보다 곧 고칠 모듈의 설명서를 읽는 쪽이 배우는 게 많다는 이유입니다.

마치며

Claude Code 팀의 방식은 “사람이 읽었는가” 대신 “무엇이 잘못될 수 있고 그걸 무엇이 잡는가”를 묻는 데서 출발합니다. 원문은 작은 규모에서 바로 시작할 수 있는 방법도 소개합니다. 혼자 작업하는 규모에서도 /code-review나 /security-review 명령, 새 컨텍스트의 서브에이전트 리뷰 정도는 바로 써볼 수 있습니다. 원문의 마지막 조언은 리뷰가 놓친 게 있으면 모델이 무엇을 못 봤는지 묻고 CLAUDE.md나 스킬에 반영하라는 것입니다.

감사합니다.

참고 자료