Claude가 코드의 90%쯤을 쓰는 Claude Code 팀은 코드 리뷰에서 ‘사람이 읽었나’ 대신 ‘무엇이 잘못될 수 있나’를 묻기로 했어요. 6월에서 9월 사이 머지된 PR은 두 배 넘게 늘었고 되돌린 PR의 비율은 40% 이상 줄었어요. 10월 15일 claude.dev 블로그의 「How the Claude Code team does code review」 이야기예요. 지난 글 「AI가 하루 3만 번 머지하자, Anthropic은 git을 떠났다」에서 다룬 Hacker News 댓글 가운데 답글이 가장 많이 달린 스레드도 이 속도로 리뷰는 어떻게 하느냐고 물었어요. 며칠 뒤 올라온 ‘이해하지 못한 AI 코드를 내보내도 되느냐’는 질문과 나란히 읽고 작은 팀이 가져다 쓸 규칙을 골랐어요.
‘사람이 읽었나’를 묻지 않기로
원문은 코드 리뷰가 두 가지 일을 한다고 정리해요. 배포 전에 문제를 찾아 고치는 일, 그리고 팀이 코드베이스를 함께 이해하게 만드는 일이에요. 팀은 변경이 이만큼 쏟아지면 한 줄씩 읽는 리뷰는 불가능에 가깝다고 인정하고 첫 번째 일을 두고 던지는 질문부터 바꿨어요.
‘사람이 코드를 읽었나’는 ‘이 변경에서 무엇이 잘못될 수 있나, 그걸 잡기에 알맞은 검사는 자동 검사인가 사람인가’를 가늠하기에는 부정확한 잣대다.
Claude Code 팀, 「How the Claude Code team does code review」
그래서 아껴야 할 자원을 사람의 시간과 주의력으로 정했어요. 사람의 시간에는 리뷰하는 시간과 나쁜 코드가 망가뜨린 것을 고치는 시간이 둘 다 들어가요. 앞쪽을 줄였는데 뒤쪽이 늘면 아낀 게 없어요. 목표는 PR 대부분이 사람 한 명 이하를 거쳐 머지되는 것이에요. 그 한 명은 작성자 본인이어도 돼요. 단 되돌리는 일이나 장애가 늘어서는 안 돼요. 그래서 PR마다 사람의 승인 수와 댓글 수, 사람을 기다린 시간을 재고 되돌린 PR 비율과 장애율을 안전선으로 지켜봐요.
관문 하나 대신 여러 겹의 검사
리뷰는 이제 PR이 생기기 전에 대부분 끝나요. Claude에게 테스트나 빌드, 디자인과 견줄 스크린숏처럼 스스로 확인할 수단을 주고 ‘다 됐다’고 말하는 대신 결과를 직접 보여 달라고 해요. 그다음 앞의 대화를 모르는 새 서브에이전트가 diff를 다시 봐요. Claude Code를 만든 Boris Cherny는 Claude에게 자기 작업을 검증할 수단을 주는 것이 좋은 결과를 얻는 데 아마 가장 중요하다고 했고 최종 결과가 두세 배 좋아진다고 봤어요.
PR마다 사람보다 Claude가 먼저 리뷰해요. 여러 에이전트가 동시에 버그를 찾고 다른 에이전트들이 찾아낸 문제마다 투표해서 충분히 동의를 얻은 것만 댓글로 남겨요. 스타일이나 정리에 그치는 지적은 버리고 남은 것에는 Important · Nit · Pre-existing 레이블을 붙여요. Pre-existing은 이 PR이 만들지 않은 버그가 작성자 탓처럼 보이지 않게 하려는 레이블이에요. 리뷰가 단 지적에는 전부 답해야 해요. 고치거나 이유를 적고 닫아요. 이 리뷰를 연구용 미리보기로 처음 켰을 때 실질적인 리뷰 댓글이 달린 사내 PR은 16%에서 54%로 늘었다고 해요.
보안 리뷰도 따로 돌아요. 버그 리뷰나 보안 리뷰가 단 지적이 하나라도 해결되지 않으면 머지할 수 없어요. 그 뒤에는 린트 · 타입 검사 · 모든 플랫폼의 테스트 · 빌드가 버티고 있어요. PR 템플릿은 ‘어떻게 테스트했나’와 ‘어떻게 되돌리나’를 물어요. 그 칸은 Claude가 채워도 되지만 변경을 요청한 사람이 직접 확인해요.
사람의 승인은 위험도만큼
문서 수정과 자동 업데이트 기능 수정은 위험이 다르니 리뷰도 달라요. 등급을 정하는 건 작성자의 판단이 아니에요. 분류기가 변경을 읽고 등급을 고르고 두 번째 분류기가 ‘등급은 낮아도 이 변경만큼은 사람이 한 명 더 봐야 하나’를 다시 물어요. 문서 · 문구 · 사내 전용 기능 · 기능 플래그로 가려 둔 추가 변경은 위험이 낮아서 자동 리뷰와 보안 검사가 통과하면 사람 승인이 필요 없어요. 보통의 제품 변경과 캐시 · 자동 업데이트 · 시스템 프롬프트처럼 민감한 곳을 건드리는 변경은 한 명, 가장 위험한 코드는 두 명이 승인해요. 승인이 가벼운 이 길은 저장소의 신뢰 목록에 든 작성자에게만 열려 있어요.
규칙이 몇 개 더 붙어요. 에이전트의 승인은 사람의 승인으로 치지 않아요. 에이전트가 쓴 PR에서는 에이전트에게 일을 시킨 사람을 필요한 리뷰어 한 명으로 계산해요. 그 사람이 코드를 직접 입력한 것과 똑같이 보는 거예요. 승인은 커밋 하나에만 유효해서 에이전트가 푸시한 커밋처럼 시스템이 보증할 수 없는 커밋이 오면 승인을 다시 받아야 해요. 코드 소유자가 민감하다고 지정한 경로와 CI 워크플로 파일은 언제나 사람이 봐요.
PR이 오면 분류기가 변경을 읽고 위험 등급을 골라요.
둘째 분류기는 등급이 낮아도 이 변경만큼은 사람이 한 명 더 봐야 하는지 다시 물어요.
위험이 낮은 변경은 자동 리뷰와 보안 검사만 통과하면 사람 승인 없이 머지돼요.
보통은 한 명, 가장 위험한 코드는 두 명이 승인해요.
그 위에 규칙이 붙어요. 에이전트의 승인은 사람 승인으로 세지 않고 에이전트에게 일을 시킨 사람을 리뷰어 한 명으로 계산해요.
승인은 커밋 하나에만 유효하고 가벼운 길은 신뢰 목록에 든 작성자에게만 열려요.
머지 큐는 main에 변경을 얹은 상태로 검사를 다시 돌려요. 따로따로는 통과한 PR 둘이 합쳐져 main을 깨는 일을 막으려는 거예요. 새 기능은 대개 플래그를 걸어 사내 직원에게 먼저 내보내고 공개 릴리스도 latest 채널이 stable 채널보다 먼저 나가요. 플래그는 배포 없이 끌 수 있어요. 한 동료는 속도를 늦추면 오류율이 낮아지기는 하지만 대개 모든 일을 덜 해서 그렇다고 말했다고 해요. 팀은 그보다 문제를 더 빨리 알아채고 고치는 쪽을 골랐어요. 원문은 아직 없는 것도 적어 뒀어요. 되돌린 PR 비율이나 장애 지표가 나빠지면 승인 기준을 자동으로 높이는 서킷 브레이커는 아직 없어요. 엔지니어들은 사람 없이 머지되는 코드가 더 늘기 전에 그것부터 갖추고 싶어 한다고 해요.
리뷰어도 리뷰를 받는다
AI 리뷰어도 매일 시험을 봐요. 팀은 과거에 장애를 낸 PR을 모으고 그 코드를 아는 엔지니어가 버그와 위치를 하나하나 확인해 평가 세트(eval)를 만들었어요. 리뷰어를 바꿀 때마다 이 평가 세트 전체로 점수를 매겨요. 쓸데없는 지적, 곧 노이즈도 재요. 리뷰어가 단 댓글마다 사람이 어떻게 반응했는지 나눠요. 고쳤는지, 틀렸다고 했는지, 의도한 동작이라고 했는지, 상관없다고 했는지예요. 작성자가 에이전트라면 노이즈가 더 비싸요. 사람은 사소한 지적을 몇 초 만에 넘기지만 에이전트는 그걸 고치고 커밋해서 리뷰를 한 번 더 받거든요.
에이전트 작성자와 에이전트 리뷰어는 서로를 끝없이 바쁘게 만들 수 있어요. CLI PR 하나는 밤새 리뷰와 수정을 50번 넘게 오간 끝에 작성자가 멈춰 세웠다고 해요. 리뷰어가 거듭 지적한 곳에 git blame을 돌려 보니 59%쯤은 첫 리뷰 때부터 있던 코드였어요. 새 버그를 찾았다기보다 옛 버그를 매번 몇 개씩 더 꺼내고 있었던 거예요. 그래서 리뷰 횟수에 상한을 뒀어요. 세 번을 넘기면 리뷰어가 작성자에게 접근 방식을 다시 생각해 보라고 해요. 처음 몇 번이 지나면 새로 바뀐 부분만 다시 봐요. 버그는 그 줄 하나 대신 같은 종류 전체를 짚고 이미 단 지적은 되풀이하지 않아요.
그럼 코드는 누가 아나
리뷰의 두 번째 일, 팀이 코드를 함께 이해하는 일은 어떻게 됐을까요. 원문은 정해 둔 절차가 없다고 그대로 적었어요. 코드의 어느 부분을 알고 싶으면 Claude에게 딱 그 부분만 설명하는 글을 써 달라고 해요. 몇 분이면 나오고 지금의 코드를 그대로 비춘다는 거예요. 한 줄짜리 문구 수정을 리뷰해서는 배우는 게 거의 없지만 곧 고칠 모듈의 설명서에서는 많이 배운다는 논리예요. 대신 ‘머지한 사람이 책임진다’는 규범을 지켜요. 작거나 보통인 변경이 문제를 일으키면 대개 머지한 사람이 고쳐요. 탓하려는 건 아니에요. 그 사람이 맥락을 가장 잘 알기 때문이에요.
팀에서 Claude Code 전체를 머릿속에 그려 두고 있는 사람은 없다. 누구도 그럴 필요가 없다고 본다.
Claude Code 팀, 「How the Claude Code team does code review」
사흘 뒤, 댓글 615개의 불안
이 글이 Hacker News에 오르고 사흘 뒤 「Ask HN: How to deal with shipping AI-written code you don’t understand?」가 올라왔어요(484점). 글쓴이는 Meta의 한 엔지니어가 LinkedIn에 쓴 글을 옮겨 왔어요. 요즘 코드를 쓰면 전부 블랙박스 같고 큰 그림은 알지만 세부를 다 알지는 못한다는 고백이에요. 눈에 띄는 답은 세 갈래였어요.
설계는 사람이 정해요. 답글이 가장 많이 달린 댓글(41개)은 LLM에게 설계를 맡기지 않는다고 했어요. 추상화와 역할 나누기를 먼저 정해 두고 빈칸만 채우게 하면 각 단위가 어떻게 구현됐는지는 몰라도 무엇을 맡고 어떻게 맞물리는지는 안다는 거예요.
위험한 곳은 손으로 짜요. 한 댓글은 화면 코드는 통째로 맡기지만 SQL 스키마는 지금도 손으로 짠다고 했어요. 틀렸을 때 치르는 대가가 훨씬 크다는 이유였어요. 코딩에 쓰던 시간을 이제 테스트에 쓴다는 댓글도 있었어요.
그래도 읽어야 해요. 반대쪽 댓글은 운영에 내보내기 전에 코드를 반드시 읽어야 하고 회사에 그 코드를 설명할 수 있는 사람이 적어도 한 명은 있어야 한다고 했어요.
이건 품질보다 책임의 문제다.
같은 Ask HN 스레드의 댓글
Claude Code 팀의 글에 달린 댓글 479개도 곱지만은 않았어요. 한 댓글은 작은 팀들이 ‘Google은 이렇게 한다’며 Google 규모의 방식을 따라 하다 쓴맛을 본 일을 떠올렸어요. 토큰을 사실상 무한히 쓸 수 있는 회사라서 가능한 방식이라는 거예요. 다른 댓글은 자기 회사의 SOC 2 감사인이 운영에 나가는 모든 코드를 다른 사람이 한 명 이상 리뷰해야 한다고 했다며 이 방식이 감사를 어떻게 통과했느냐고 물었어요. 원문은 비용과 감사 규정에는 답하지 않아요. ‘AI는 코딩 시간을 아껴 주지만 책임은 100% 그대로 나에게 남는다’는 댓글도 있었어요.
도구인가, 자동화인가
같은 2주 사이에는 더 근본적인 반론도 나왔어요. Clojure를 만든 Rich Hickey는 「‘AI’ Is Not a Tool」(HN 318점)에서 LLM은 손에 쥐고 다루는 도구가 아니라 자동화라고 했어요. 요리를 피하게 해 주는 드라이브스루를 요리 도구라고 하지 않는 것과 같다는 비유를 들면서 직접 쓰고 읽지 않으면 생각하는 법을 배울 기회를 놓친다고 했어요. 곧바로 Huahai가 「AI Is a Tool. Using It Well Takes Skill.」(805점)로 반박했어요. 톱을 들었다고 곧게 자를 수 있는 게 아니듯 LLM도 잘 쓰는 데 기술이 든다는 거예요. 저수준 코드를 8년 동안 다뤄 온 purplesyringa는 「Grieving the loss of details」(506점)에서 LLM 중심의 개발이 프로그래밍을 견딜 만하게 해 주던 부분을 모두 걷어 냈다고 썼어요. 18일에는 배포할 때마다 그 코드를 이해했는지 퀴즈를 내는 훅 Sphinx(252점)까지 나왔어요.
도구는 내가 그것으로 무언가를 하는 물건이다. 나 대신 일을 해 주는 물건이 아니다.
Rich Hickey, 「‘AI’ Is Not a Tool」
작은 팀이 가져다 쓸 것
원문 끝에는 다른 팀이 따라 해 볼 수 있는 목록이 있어요. 토큰을 마음껏 쓸 수 없는 작은 팀도 바로 할 수 있는 것만 골랐어요.
위험도 표를 글로 적어요. 등급은 누가 썼느냐보다 무엇을 바꿨느냐로 정하고 처음에는 엄격하게 시작해 근거가 쌓이면 풀라는 게 원문의 권고예요. 인증 · 결제 · CI · 릴리스 워크플로 · 설치 프로그램은 CODEOWNERS와 브랜치 보호로 언제나 사람을 거치게 해요.
PR 템플릿에 세 칸을 더해요. ‘어떻게 테스트했나’ · ‘위험’ · ‘어떻게 되돌리나’예요.
REVIEW.md를 둬요. 그 저장소에서 실패가 어떤 모습인지 적어요. 원문의 예로는 문서라면 ‘거짓말을 한다’, 설정이라면 ‘엉뚱한 곳으로 보낸다’예요. 사소한 지적에는 상한을 두고 근거로 파일과 줄을 요구해요. 같은 리뷰 댓글이 되풀이되면 그 내용을 이 파일로 옮겨요.
리뷰 횟수에 상한을 둬요. 처음 몇 번이 지나면 새로 바뀐 부분만 다시 리뷰해요.
봇의 승인으로 사람의 승인을 대신하지 않아요. 새 커밋이 올라오면 받아 둔 승인은 무효로 해요.
사람의 시간을 재고 되돌린 PR 비율을 안전선으로 둬요. 장애를 낸 PR과 되돌린 PR은 모아 리뷰어의 평가 세트로 만들어요.
Scion 글에서 Anthropic은 엔지니어의 일이 Claude에게 ‘안 돼’라고 말하는 것일 때가 많았다고 했어요. 이번 글에서 사람에게 남긴 일도 비슷해요. 이걸 만들지 말지 정하는 일, 결제나 자동 업데이트처럼 위험한 코드를 보는 일, 증거를 읽는 일, 결과를 책임지는 일이에요. Ask HN의 615개 댓글이 ‘이 코드를 누가 아느냐’고 물었다면 Claude Code 팀은 ‘이 변경을 누가 책임지느냐’로 답한 셈이에요. 두 질문이 같은 질문인지는 아직 아무도 몰라요. 그래도 작은 팀이 먼저 할 일은 분명해 보여요. 사람이 꼭 봐야 하는 곳을 글로 적어 두는 거예요.