
앞서 저희는 Claude Code의 코드 중 약 90%를 Claude가 작성한다고 말씀드린 적이 있습니다. 그렇다면 이런 규모에서 코드 리뷰는 어떻게 할까요? 애초에 코드는 누가 읽을까요? 코드가 잘못되면 어떻게 될까요?
이 글은 Claude Code 팀이 코드 리뷰를 진행하는 과정과, 그 과정을 어떻게 개선해 왔는지를 설명합니다. 6월부터 9월까지 Claude Code 코드베이스에 병합된 풀 리퀘스트(PR)의 수는 두 배 넘게 늘었지만, 되돌려야 했던(revert) PR의 비율은 40% 넘게 줄었습니다.
저희는 코드 리뷰를 그만두지 않았습니다. 대신 읽는 작업의 대부분을 자동화했고, 사람의 시간과 노력을 최적으로 쓰도록 그 과정을 조정했습니다. 또한 실수를 빠르고 쉽게 되돌릴 수 있도록 상당한 투자를 했습니다.
코드 리뷰의 목표를 다시 생각하기
에이전트가 코드를 작성하면 변경의 양이 빠르게 늘어납니다. 저희 모노레포에서는 하루에 병합되는 변경이 5월에는 약 2,500건이었지만, 올해 9월에는 30,000건을 넘었습니다.
Claude Code는 이 모노레포에 들어 있지 않지만, 마찬가지로 큰 압박을 받고 있습니다. 이렇게 빠르게 움직이면 사람이 한 줄씩 코드를 리뷰하는 일은 불가능하지는 않더라도 점점 더 어려워집니다.
코드 리뷰에는 두 가지 목적이 있습니다.
- 출시되기 전에 버그를 찾아서 고칩니다.
- 코드베이스에 대한 이해를 팀이 함께 쌓습니다.
이 글은 주로 첫 번째 목표를 다루며, 두 번째 목표는 글의 끝부분에서 다룹니다.
저희는 "누군가 코드를 읽었는가?"라는 질문이, "이 변경에서 무엇이 잘못될 수 있고, 그것을 잡아내는 데 적합한 검사는 자동 검사와 사람 중 무엇인가?"라는 질문을 정확하게 반영하지 못하는 대용 지표라고 봅니다.
이 질문은 코드 리뷰를 하는 시점도 바꾸었습니다. 전통적으로 코드 리뷰는 사후에 수행하는 검사였습니다. 코드를 다 작성하고 PR을 올린 뒤, 다른 누군가가 살펴봐 주기를 기다렸습니다. 저희는 그 대신 코드 리뷰를 작업 흐름 안에 통합했습니다. 글을 쓰는 동안 계속 돌아가는 맞춤법 검사에 더 가깝습니다.
사람에게 리뷰를 요청하기 전에, 대부분의 변경은 이미 Claude가 적어도 한 번 리뷰하고 수정한 상태입니다. 이렇게 해서 일상적인 버그는 대부분 잡아내고, 사람의 주의는 더 높은 수준의 고려 사항을 위해 남겨 둡니다.
사람의 시간과 주의
저희는 사람의 시간과 주의를 사람만 처리할 수 있는 일에 쓰고, 나머지는 충분한 자동화로 처리하려고 합니다. 지금 같은 속도에서도 사람이 해야 할 일은 여전히 엄청나게 많고, 저희 팀은 거의 매일 새롭고 처음 보는 문제를 마주합니다.
그래서 사람의 시간에는 두 가지 비용이 있습니다. 사람들이 코드 리뷰에 쓰는 시간뿐 아니라, 잘못된 코드가 들여온 버그를 고치는 데 쓰는 시간도 계산합니다. 앞의 시간만 줄이고 뒤의 시간을 줄이지 못한다면, 사람의 시간을 실제로 아낀 것이 아닙니다.
따라서 저희의 목표는 Claude Code 저장소(CLI, 데스크톱 앱과 웹 앱, 모바일 앱)의 PR 대부분이 되돌리기나 장애를 늘리지 않으면서, 과정에 참여하는 사람(작성자일 수도 있습니다)이 최대 한 명인 상태로 병합되는 것입니다.
저희는 사람의 시간을 PR당 사람 승인 수의 중앙값(95번째 백분위수도 함께), 사람이 남긴 댓글 수, PR이 사람을 기다리는 시간으로 추적합니다. 되돌리기 비율과 장애 비율은 안전장치로 씁니다. 이 지표가 늘어난다면, 사람의 시간을 줄인 것이 아니라 다른 곳으로 옮긴 것에 불과하기 때문입니다.
변경은 어떤 과정을 거치는가?
엔지니어의 노트북에서 나온 변경이든 Slack에 있는 Claude 세션에서 나온 변경이든, 일반적인 변경은 여러 겹의 리뷰를 거칩니다.

FIG A: 변경의 일생
위 그림은 작성자의 환경에서 프로덕션까지 이어지는 일반적인 Claude Code 변경을 보여 줍니다. 이 과정의 대부분은 자동화되어 있고, 사람의 주의는 위험한 부분에 집중됩니다.
저희에게는 여섯 겹의 검사가 있고, 그 검사를 통과해 버린 문제를 처리하는 롤백 장치가 있습니다.

FIG B: 관문 하나가 아니라 여러 겹
각 층은 어떤 버그는 잡고 어떤 버그는 놓칩니다. 모든 층을 통과하는 버그는 드물고, 통과하는 버그가 생기더라도 롤백 장치가 마련되어 있습니다.
1. PR 전 검증:
리뷰의 대부분은 PR을 만들기 전에 이루어집니다. 저희는 Claude에게 테스트 실행, 빌드, 스크린숏과 디자인 비교처럼 실행할 수 있는 일을 하도록 요청합니다. 작업을 끝냈다고 말하게 하는 대신, 결과를 보여 달라고 요청합니다. 그다음에는 새로운 컨텍스트를 가진 서브에이전트가 diff를 리뷰합니다. 이 두 전략은 모두 저희의 모범 사례 가이드에 들어 있습니다.
PR을 열기 전에 저희 중 많은 사람이 몇 가지 내부 스킬도 실행합니다. 버그 찾기, diff 줄이기, 엔드 투 엔드 검증, UI 변경이 디자인 가이드라인에 맞는지 확인하는 스킬입니다.
Claude Code를 만든 Boris Cherny에 따르면, Claude에게 검증 과정을 갖춰 주는 것이 아마도 더 높은 품질의 결과를 얻는 가장 중요한 요소일 것입니다.
그는 검증 과정이 Claude가 내놓는 결과물의 품질을 두세 배 높인다고 추정합니다.
검증 과정은 분야마다 크게 다를 수 있습니다.
어떤 때는 bash 명령 하나를 실행하는 것만큼 간단합니다. 어떤 때는 테스트 스위트를 실행합니다. 어떤 때는 브라우저나 휴대폰 시뮬레이터에서 앱을 테스트합니다.
자동 리뷰어가 같은 문제를 계속 지적한다면, 저희는 그 문제를 근원에서 고칩니다. 스킬 자체를 고치거나, 린트 규칙을 추가하거나, 다음과 같은 문서 파일을 갱신합니다.
- CLAUDE.md: 프로젝트에 대한 컨텍스트(기술 스택, 관례, 목표, 목표가 아닌 것)를 Claude에게 알려 줄 때 쓰는 프로젝트 설명 파일입니다. Claude Code는 모든 리뷰마다 이 파일을 불러오기 때문에, 큰 코드베이스에서는 이 파일을 짧게 유지하고 나머지 문서는 여기서 참조합니다. 코드가 이 파일의 관례를 어기거나, 어떤 변경 때문에 이 파일의 내용이 낡게 되면 리뷰어가 그것을 지적합니다.
- REVIEW.md: 코드 소유자가 자기 담당 코드에서 무엇이 중요한지 리뷰어에게 알려 주는 파일입니다. 리뷰어가 이 지침을 실제로 따르는지는 따로 검증합니다. 좋은 REVIEW.md는 짧고, 다음 사항에 집중합니다.
- 프로젝트에서 무엇이 실패인지 정의합니다(문서는 거짓말을 하면 안 되고, 설정은 잘못된 경로로 보내면 안 됩니다).
- 사소한 지적을 제한합니다.
- 무시할 경로를 정의합니다.
- 파일 이름을 추측하지 말고 파일과 줄 번호를 명시하도록 요구합니다.
- 지적 수와 "문제 없음"이라는 명확한 문장을 담은 최상위 요약을 요구합니다.
2. 모든 풀 리퀘스트에 대한 AI 리뷰
모든 PR은 사람이 리뷰하기 전에 Claude의 리뷰를 받습니다.
리뷰는 코드베이스 전체와 PR 작성자가 밝힌 의도에 비추어 diff를 분석합니다. 리뷰는 다음을 확인합니다.
- 변경이 실제로 문제를 해결하는지
- 변경이 더 큰 시스템에 잘 들어맞는지
- 변경이 코드베이스의 다른 부분을 망가뜨리지 않는지
버그 수정을 리뷰할 때 봇은 근본 원인을 찾으려고 합니다.
저희의 공개 제품인 Code Review for Claude Code는 이제 모든 Team 및 Enterprise 고객이 사용할 수 있습니다. 로컬에서 쓰는 가벼운 버전인 /code-review도 있습니다.
리서치 프리뷰를 출시한 이후로, 실질적인 리뷰 댓글을 받는 내부 PR의 비율은 16%에서 54%로 늘었습니다. Code Review는 1,000줄이 넘는 PR 대부분에서 문제를 찾아내고, 더 작은 PR 대부분에서는 깨끗하다는 결과를 돌려줍니다. 관리자는 저장소마다 Quick, Standard, Deep 모드 중 하나를 쓰도록 설정할 수 있습니다. Deep 모드는 버그 하나를 놓치는 비용이 코드를 리뷰하는 데 드는 시간보다 클 때 유용합니다.
지적 사항은 사람이 리뷰하기 전에 여러 다른 에이전트의 검증을 거칩니다.
- 여러 에이전트가 병렬로 실행되어 버그를 찾습니다.
- 별도의 투표로 지적 사항이 유효한지 오탐인지 결정하고, 충분한 표를 얻은 지적 사항만 확정합니다.
- 스타일, 진단, 정리에만 관련된 지적 사항은 걸러 냅니다(이 필터는 출시하기 전에 저희 PR로 A/B 테스트를 거쳤습니다).
남은 지적 사항은 심각도 순으로 정렬된 인라인 댓글로 게시되며, 다음 중 하나로 분류됩니다.
- Important
- Nit
- Pre-existing(PR이 들여오지 않은 버그 때문에 작성자가 부당하게 불이익을 받지 않도록 하기 위한 표시입니다)
모든 지적 사항은 처리되어야 합니다. 고치거나, 이유를 남기고 스레드를 해결 처리해야 합니다. 많은 경우 에이전트가 밤사이에 문제를 고쳐 두기 때문에, 작성자가 돌아오면 PR은 이미 리뷰를 한 번 더 거친 상태입니다.
3. 병합을 막을 수 있는 보안 리뷰
저희는 자동 보안 리뷰도 실행합니다. 코드 리뷰나 보안 리뷰에서 나온 지적 사항이 열려 있는 동안에는 어떤 PR도 병합할 수 없습니다. 작성자는 문제를 고치거나, 짧은 이유를 적고 스레드를 닫을 수 있습니다(오탐은 이렇게 처리합니다).
이후 커밋이 문제를 해결하면 지적 사항은 자동으로 닫힙니다. 오픈 소스인 보안 리뷰 GitHub Action이나 /security-review 명령으로 같은 구성을 만들 수 있습니다. 설정 방법은 Claude Code의 자동 보안 리뷰 가이드를 참고하세요.
4. 병합을 막는 자동 검사
표준 검사로는 린트, 타입 검사, 모든 플랫폼에서의 테스트, 빌드가 있습니다(CI를 어떻게 확장했는지는 여기에 썼습니다). 일반적인 CLI PR은 누군가 들여다보기 전에 수십 개의 검사를 실행할 수 있습니다. PR 템플릿에는 변경을 어떻게 테스트했는지, 어떻게 되돌리는지를 묻는 질문이 있습니다. Claude가 대신 답할 수 있지만, 그 답을 검토할 책임은 작성자에게 있습니다.
5. 위험도에 따라 달라지는 사람의 승인
어떤 변경은 다른 변경보다 위험합니다(예를 들어 문서 수정과 자동 업데이터 변경). 그래서 필요한 리뷰 수준도 다릅니다.

FIG C
등급은 작성자가 아니라 변경에 따라 정해집니다. 분류기 하나가 변경 내용을 바탕으로 위험 수준을 정합니다. 다른 분류기는 등급상 필요하지 않더라도 특정 변경에 실제로 추가 승인이 필요한지를 판단합니다. 어떤 경로는 항상 추가 승인이 필요합니다. 소유자가 민감하다고 표시한 모든 것과 모든 CI 워크플로 파일이 여기에 해당합니다.
저장소의 신뢰 목록에 있는 작성자만 완화된 리뷰 요건을 적용받으며, 대개 그 저장소를 소유한 팀이 여기에 해당합니다. 그 밖의 모든 사람은 두 번째 사람의 승인이 필요합니다. 에이전트의 승인은 사람의 승인으로 치지 않습니다. 자동 리뷰는 위험도가 낮은 변경을 통과시킬 수 있지만, 사람의 승인이 필요한 단계를 대신할 수는 없습니다.
변경에 대한 책임은 작성자에게 있습니다. 그래서 에이전트가 PR을 작성하면 그 에이전트를 운영하는 사람이 항상 필수 리뷰어 중 한 명으로 계산됩니다. PR 승인은 커밋 하나에만 유효합니다. 신뢰할 수 없는 새 커밋이 들어오면(예를 들어 에이전트가 무언가를 푸시했거나, 누군가가 병합 충돌을 손으로 해결한 경우) PR을 다시 승인받아야 합니다.
6. 머지 큐, 기능 플래그, 단계적 출시
머지 큐는 변경을 적용한 main에서 모든 검사가 실행되도록 보장합니다. 이렇게 하면 각각 성공한 PR 두 개를 병합했는데 main이 깨지는 일을 막을 수 있습니다. 새 기능은 대개 기능 플래그 뒤에서 출시되며, Anthropic 직원이 먼저 사용합니다. 저희가 제품을 많이 쓰기 때문에 회귀 문제를 사용자보다 먼저 발견하는 경우가 많습니다.
공개 출시를 할 때 변경은 먼저 latest 채널로 나가고, stable 채널은 그 뒤를 따라갑니다.
7. 빠른 피드백과 롤백
잘못된 병합 중 일부는 어쩔 수 없이 통과하게 됩니다. 이 단계는 마지막 방어선이며, 그런 병합을 가능한 한 빨리 찾아내는 데 집중합니다. 기능 플래그 뒤에 있는 변경은 배포 없이 끌 수 있습니다.
Claude Code는 주간 온콜 순번을 운영하고, 장애 리뷰에서는 어느 층이 문제를 잡았어야 했는지를 되짚어 봅니다. 되돌리기 대시보드와 장애 대시보드를 모니터링하지만, 잘못된 병합을 알아차리는 일은 여전히 작성자와 온콜 담당자의 몫입니다. 이 지표를 바탕으로 승인 요건을 조정하는 서킷 브레이커 장치는 아직 없지만, 병합에 사람의 개입을 줄이는 방향으로 나아가면서 검토하고 있습니다.
한 팀원은 속도를 늦추고 산출량을 줄이면 실제로 정확도가 올라갈 수 있다고 지적했습니다. 하지만 그것은 대부분 전체 작업량이 줄기 때문입니다. 저희의 우선순위는 문제를 빠르게 찾아서 고치는 능력을 키우는 데 있습니다.
리뷰어를 더 낫게 만드는 방법
저희의 코드 리뷰 과정은 계속 이어지는 개선의 순환입니다.
저희는 장애를 평가 지표로 씁니다. 팀은 장애를 일으킨 PR과 그 PR을 수정한 후속 변경(fix-forward), 되돌리기를 모았고, 코드베이스를 이해하는 엔지니어들이 각 버그의 위치와 정확성을 검증했습니다. 저희는 매일 이 모음으로 리뷰 시스템을 평가합니다.

FIG D: 저희의 장애가 곧 평가 세트입니다
장애가 생길 때마다 모음에 추가하고, 리뷰 시스템을 바꿀 때마다 모음 전체로 평가합니다.
노이즈를 측정하기 위해, 저희는 사람들이 리뷰 댓글에 어떻게 반응하는지 관찰합니다. 버그가 아닌 것을 많이 보고해도 괜찮다면 버그 발견율을 높이기는 쉽기 때문에, 이 부분은 통제해야 합니다. 저희는 각 리뷰 댓글을 PR 담당자가 어떻게 처리했는지에 따라 분류합니다. 문제를 고쳤는지, 거부했는지, 의도한 것이라고 설명했는지, 중요하지 않다고 판단했는지로 나눕니다. 또한 깨끗하다고 알고 있는 PR에 리뷰 시스템을 실행해, 그대로 반영했다면 해로운 변경이 되었을 지적을 시스템이 얼마나 자주 보고하는지 관찰합니다.
저희가 밝힌 우선순위는 첫째로 실제 버그를 찾는 것, 둘째로 리뷰 주기의 수를 줄이는 것입니다.
작성자가 에이전트일 때는 리뷰 댓글을 처리하는 비용이 더 큽니다. 사람은 사소한 지적을 1초 만에 넘길 수 있지만, 에이전트가 그 지적을 처리하면 커밋이 하나 더 생기고 리뷰 주기도 한 번 더 돌게 됩니다.
리뷰 과정은 수렴해야 합니다. 작성자 에이전트와 리뷰어 에이전트는 끝없이 주고받을 수 있습니다. 저희는 CLI 프로젝트의 한 PR이 작성자 에이전트와 리뷰어 에이전트가 주고받는 바람에 밤사이 50번 넘게 주기를 도는 것을 관찰했습니다. 이 순환은 사람이 직접 멈췄지만, 그대로 두었다면 끝없이 이어졌을 수도 있습니다.
리뷰 시스템이 계속 지적한 부분에 git blame을 실행해 보니, 약 59%는 첫 번째 리뷰 때부터 있던 코드였습니다. 즉, 리뷰 시스템은 새로운 버그를 거의 찾지 못했고, 주기마다 오래된 버그를 몇 개씩 더 찾아낼 뿐이었습니다.
주기마다 다른 버그를 찾을 수 있다는 이유로 기본적으로 여러 번 리뷰 주기를 돌리는 습관이 생기면서 상황이 더 나빠졌습니다. 위험도가 높은 변경이라면 여러 번 리뷰 주기를 도는 것이 유용할 수 있지만, 모든 PR에 필요한 것은 아닙니다. 저희 팀은 재현율(recall)과 함께 통과까지 걸린 주기 수를 추적하기 시작했고, 재리뷰를 다음과 같이 바꾸었습니다.
- 주기의 수를 제한합니다. 세 번의 주기가 지나면 리뷰 시스템이 작성자에게 접근 방식을 다시 검토하라고 요청합니다.
- 처음 몇 번의 주기가 지나면 재리뷰 범위를 diff로만 제한합니다.
- 버그의 종류를 명시해, 작성자가 한 줄만이 아니라 같은 종류의 버그를 모두 고칠 수 있게 합니다.
- 이미 지적한 문제를 다시 보고하지 않습니다.
리뷰 에이전트는 밤사이 현재 코드베이스에 대해서도 실행되어, 과거의 버그가 퍼지기 전에 찾아내도록 돕습니다.

FIG E: 수렴하는 리뷰
수렴(Convergence) 적용 이후 내부 풀 리퀘스트당 평균 리뷰 라운드 수가 줄어든 모습입니다.
과정 안의 사람
흔한 오류를 리뷰하려고 시니어 엔지니어가 하던 일을 멈추게 하는 것은, 그 과정을 자동화하는 것에 비해 비용이 큰 일입니다. 그래도 어떤 일에는 여전히 사람 리뷰어가 꼭 필요합니다.
- 애초에 이것을 만들어야 하는가? 무언가를 만들지 말지 결정하고, 제품의 비전과 취향, 목표를 정하는 일입니다.
코드 리뷰라는 병목을 해결했다고 말하는 한 팀도, 팀 밖에서 들어온 변경에는 여전히 사람이 리뷰해 그것이 만들어야 할 올바른 것인지 확인합니다.
- 위험한 코드(결제, 자동 업데이터, CI 워크플로)를 감사하는 일
- 아키텍처 리뷰. 그런 선택이 다른 사람들이 따르는 관례를 정하기 때문입니다.
- 증거(테스트 출력, 실행한 명령, 스크린숏, 리뷰어 댓글)를 검증하는 일. 검사가 무엇을 놓칠지 설명할 수 없다면 👍를 요청하지 마세요. 진짜 리뷰가 필요합니다!
- 책임을 지는 일. 누가 입력했든, 출시되는 모든 변경에는 그 변경을 책임지는 사람이 있습니다.
팀 컨텍스트
코드 리뷰는 언제나 코드베이스 변경 내용을 공유하는 역할도 함께 해 왔습니다. 동료가 만든 변경의 diff를 읽는 것은 사람들이 무엇이 바뀌었는지, 코드베이스가 어떻게 동작하는지를 이해하는 일반적인 방법입니다. 읽는 일의 대부분을 기계가 한다면, 코드베이스를 배우는 방법은 무엇이 될까요?
저희에게는 이를 위한 공식적인 장치가 없습니다. 팀원 중 누구도 Claude Code 전체에 대한 멘탈 모델을 머릿속에 갖고 있지 않으며, 그런 모델이 누구에게나 필요하다고 생각하지도 않습니다. 대신 누군가 코드베이스의 한 부분을 배우고 싶으면, 바로 그 부분에 대한 설명 자료를 만들어 달라고 Claude에게 요청합니다. 몇 분이면 되고, 설명 자료는 언제나 최신 상태입니다.

FIG F: 기계가 읽는 일의 대부분을 한다면, 사람은 코드를 어떻게 배울까?
어떤 사람은 한 걸음 더 나아가, 그 영역을 시각화하고 자기가 선호하는 방식으로 가르쳐 주는 작은 아티팩트를 Claude에게 만들게 합니다.
이것은 사소한 diff를 한 줄씩 읽는 것보다 사람의 주의를 더 잘 쓰는 방법입니다. 사소한 diff(예를 들어 문구 한 줄 변경)를 읽어서는 배우는 것이 거의 없습니다. 반면 바꾸려는 모듈에 대한 설명 자료를 만들면 많은 것을 배웁니다.
게다가 저희는 대체로 공개를 기본으로 삼아 일합니다. 공개 Slack 채널에서 작업하고, 다른 사람이 무언가를 만드는 과정을 실시간으로 지켜봅니다.
"병합했다면 책임도 진다"
작거나 중간 크기의 변경을 병합했는데 그래도 무언가 잘못되면, 직접 고치는 것이 기본적인 기대입니다. 이 방식이 통제 불능으로 번지지 않는 데에는 몇 가지 이유가 있습니다.
- 변경이 작아서 리뷰하고, 디버깅하고, 되돌리기 쉽습니다.
- 모든 것을 되돌릴 수 있습니다. 기능 플래그, 되돌리기, 단계적 출시로 대부분의 실수를 몇 분 안에 되돌릴 수 있습니다.
- 영향 범위가 기준을 정합니다. 비용이 큰 코드일수록 더 많은 사람이 보고 더 많이 검증합니다.
- 회귀 문제는 텔레메트리와 내부 사용을 통해 빠르게 드러납니다.
- 책임 공방이 아닙니다. 문제를 고치는 사람이 그 문제를 맡는 이유는 그 사람에게 가장 많은 컨텍스트가 있기 때문입니다. 장애 리뷰는 시스템을 살펴봅니다.
- 게다가 팀의 많은 사람이 공개 채널에서 일하면서 책임을 나눕니다. 누구나 다른 사람이 무엇을 만드는지 보고, 대화에 참여하고, Claude에게 빈틈을 찾게 할 수 있습니다. 코드 소유자가 아닌 사람에게서도 피드백이 옵니다. 모든 줄에 관문을 두지 않고도 품질이 높게 유지되는 큰 이유가 이런 개방성입니다.
방향 바꾸기
에이전트가 있으면 새 작업을 시작하는 비용이 낮지만, 때로는 시작하지 말아야 합니다. 이런 상황은 대개 채널의 누군가가 제안된 변경이 잘못된 방향이라고 지적할 때(이전 결정을 근거로 들거나 더 나은 방향을 제안할 때) 생기며, 작성자는 PR을 닫거나 구현을 바꿉니다.
처음부터 코드를 쉽게 작성했기 때문에, PR을 닫아도 손실처럼 느껴지지 않습니다. 핵심은 마무리된 PR에 막판에 병합을 막는 댓글을 다는 대신, 스레드 초반에 방향을 트는 것입니다.
적용하는 방법
이 접근법을 이루는 요소 대부분은 여러분의 팀도 이미 쓸 수 있습니다.
풀 리퀘스트 전
- 에이전트가 실행할 수 있는 검사 체크리스트를 주세요. 이 검사들을 짧은 CLAUDE.md 파일에 나열하세요.
- 에이전트가 훅을 통해 포매터와 린터를 호출하도록 설정하세요.
- /code-review와 /security-review를 로컬에서 실행하거나, 새 컨텍스트를 가진 서브에이전트가 변경을 리뷰하게 하세요.
- REVIEW.md를 만들고, 반복되는 리뷰 문제를 추적하는 데 쓰세요.
모든 풀 리퀘스트에서
- CI를 강제하세요.
- PR 템플릿에 "Testing", "Risk", "How to revert" 항목을 추가하세요.
- 저장소 하나에 AI 리뷰어(Code Review for Claude Code 또는 Claude Code GitHub Action)를 추가하고, 다른 저장소로 넓히기 전에 몇 주 동안 REVIEW.md를 다듬으세요.
- 자동 보안 리뷰를 추가하세요.
- 병합하기 전에 모든 리뷰 스레드를 해결하도록 요구하세요.
- 위험도에 맞춰 리뷰 강도를 정하세요. 일상적인 변경은 빠르게 훑고, 위험도가 높은 영역(버그의 비용이 큰 곳)은 철저히 리뷰하세요. Code Review에는 Quick, Standard, Deep 수준이 있습니다.
- 리뷰 라운드 수를 제한하고, 몇 라운드가 지나면 새 diff만 리뷰하세요.
승인
- 위험 수준을 정의하되, 작성자가 아니라 변경을 기준으로 정하세요. 엄격하게 시작하고, 근거가 쌓이는 만큼 점차 완화하세요.
- 느슨한 승인 경로는 신뢰할 수 있는 작성자에게만 허용하세요.
- 봇의 승인으로 필수 승인을 채울 수 없게 하세요. 새 커밋이 푸시되면 기존 승인을 모두 무효로 하세요.
- 인증, 결제, CI, 릴리스 워크플로와 설치 프로그램을 다루는 코드와 정책은 사람을 승인자로 지정하세요. 이를 위해 CODEOWNERS와 브랜치 보호를 쓰세요.
병합과 병합 이후
- 머지 큐를 설정하세요.
- 기능 플래그를 실험해 보세요.
- 내부 사용자에게 먼저 출시하세요.
- 단계적으로 출시하세요.
- 한 번의 조작으로 되돌릴 수 있는 장치를 만드세요.
- 장애와 되돌리기를 기록해 평가 세트를 만드세요.
- 리뷰어의 프롬프트, 도구, 모델을 바꿀 때마다 리뷰어를 다시 평가하세요.
- 되돌리기 비율과 장애 비율을 안전장치로 삼아 사람의 노력을 추적하세요.
앞으로의 방향
Code Review는 최종 승인 결정을 여전히 사람이 내린다는 의도로 발표되었습니다. 이 제품이 하는 일은 지적 사항을 게시하는 것뿐입니다. 하지만 저희 저장소에서는 더 나아가고 있습니다. 자동 검사를 통과하면 어떤 저위험 변경을 자동으로 병합할 수 있는지를 소유자들이 정하고 있습니다. 그리고 이 경계는 계속 바뀔 것입니다.
그래서 리뷰어가 무언가를 놓칠 때마다 저희는 모델의 컨텍스트에 무엇이 없었는지 묻고, 그것을 CLAUDE.md 파일이나 스킬, 새 검사로 만듭니다. 그리고 저희의 목표는 바뀌지 않았습니다. 되돌리기 비율을 지금보다 높이지 않으면서 변경 하나에 드는 사람의 노력을 줄이는 것입니다.
그러니 여러분도 에이전트가 풀 리퀘스트를 만들도록 허용하고 있다면, 어떤 검사를 자동화했는지, 무엇에 사람이 필요한지, 저희가 무엇을 잘못하고 있는지 알려 주세요.
원래 글을 다시 쓴 것이며, Pangram으로 확인했습니다.