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

https://claude.dev/blog/solving-code-review-at-anthropic/

에이전트가 쏟아 내는 그 많은 코드를 어떻게 리뷰할 수 있을까요? Claude Code 팀은 리뷰 커버리지를 높이고 깊이 있는 리뷰를 갖춘 뒤부터, 되돌림(revert)이나 장애를 늘리지 않는 선에서 사람이 리뷰에 쓰는 시간을 최소한으로 줄이는 쪽으로 최적화하기 시작했습니다.

저희는 Claude Code 자체 코드의 약 90%를 Claude가 작성한다고 말씀드린 적이 있습니다. 그렇다면 이렇게 많이 만들어지는 코드를 어떻게 리뷰할까요? 아직도 코드를 읽는 사람이 있기는 할까요? 그리고 무언가 고장 나면 누가 잡아낼까요?

이 글에서는 Claude Code 팀의 코드 리뷰 흐름과 그 흐름이 어떻게 발전해 왔는지 다룹니다. 6월부터 9월까지 Claude Code 코드베이스에 병합된 풀 리퀘스트는 두 배 넘게 늘었지만, 그중 되돌려야 했던 비율은 40% 넘게 줄었습니다.

리뷰를 없앤 것은 아닙니다. 다만 코드를 읽는 일 대부분을 기계에 넘겼고, 사람의 시간과 주의력을 아끼는 쪽으로 최적화했으며, 실수를 빠르고 쉽게 되돌릴 수 있게 만드는 데 많은 투자를 했습니다.

코드 리뷰의 목적을 다시 생각하기

에이전트가 코드를 쓰면 변경의 수가 빠르게 늘어납니다. Anthropic 모노레포에서 하루에 반영되는 변경은 올해 5월 약 2,500건에서 9월 3만 건 이상으로 늘었습니다.

Claude Code는 모노레포와 분리된 별도 저장소에 있지만, 이곳도 상당한 압박을 받고 있습니다. 이렇게 빠르게 출시하다 보면, 사람이 한 줄 한 줄 코드를 리뷰하는 일은 불가능까지는 아니더라도 엄청나게 어렵습니다.

코드 리뷰는 두 가지 일을 합니다.

1. 출시되기 전에 문제를 찾아 고치는 일
2. 팀 전체가 맥락을 공유하고 코드베이스를 이해하게 만드는 일

이 글은 주로 문제를 찾아 고치는 일을 다루지만, 두 번째 일도 글 끝부분에서 다시 다룹니다.

저희는 '사람이 코드를 읽었는가?'라는 질문이 '이 변경에서 무엇이 잘못될 수 있고, 그것을 잡아내기에 알맞은 검사는 자동 검사와 사람 중 무엇인가?'라는 질문을 정확하게 대신하지 못한다고 생각합니다.

이 질문을 던지자 리뷰가 언제 이루어지는지도 바뀌었습니다. 예전에는 리뷰가 길 끝에 놓인 관문이었습니다. 코드를 쓰고, PR을 열고, 동료가 봐 주기를 기다렸습니다.

이제 리뷰는 쉬지 않고 계속 돌아갑니다. 글을 쓰는 동안 돌아가는 맞춤법 검사에 더 가깝습니다. 대부분의 변경은 사람에게 봐 달라고 요청하기 전에 이미 Claude가 적어도 한 번은 리뷰하고 고친 상태입니다. 이렇게 하면 일상적인 실수 대부분이 걸러지고, 팀은 주의력을 더 높은 수준의 질문과 꼼꼼한 검토에 아껴 둘 수 있습니다.

귀한 자원: 사람의 시간과 주의력

저희는 사람만 풀 수 있는 문제에 사람의 시간과 주의력을 아껴 두고, 나머지는 자동 검사가 확실히 잡아내게 하고 싶습니다. 지금 같은 변경 속도에서도 사람이 해야 할 일은 여전히 엄청나게 많고, 저희 팀은 거의 매일 새롭고 처음 보는 문제와 마주칩니다.

사람의 시간은 리뷰 비용의 양쪽을 모두 포함합니다. 하나는 사람이 리뷰하는 데 쓰는 시간이고, 다른 하나는 나쁜 코드가 망가뜨린 것을 고치는 데 쓰는 시간입니다. 앞의 시간을 줄여도 그만큼이 뒤의 시간으로 옮겨 가기만 한다면 소용이 없습니다.

그래서 저희 목표는 Claude Code 저장소들(CLI, 데스크톱 앱과 웹 앱, 모바일 앱)의 풀 리퀘스트 대부분을, 되돌림이나 장애를 늘리지 않으면서 사람이 많아야 한 명만 관여한 채로 병합하는 것입니다. 그 한 명은 작성자 본인이어도 됩니다. 사람의 시간을 측정하기 위해 저희는 PR당 사람의 승인 수(중앙값과 95번째 백분위수), 사람이 남긴 코멘트 수, 그리고 PR이 사람을 기다리는 시간을 추적합니다. 되돌림 비율과 장애 비율은 가드레일 역할을 합니다. 이 비율이 오른다면 사람의 시간을 아낀 것이 아니라 다른 곳으로 옮겼을 뿐입니다.

변경 하나가 거치는 길

엔지니어의 노트북(또는 Slack 속 Claude 세션)에서 시작된 일반적인 변경은 여러 겹의 코드 리뷰를 거칩니다.

그림 A 경로 대부분은 자동으로 진행되고, 사람은 위험이 있는 지점에 주의를 기울입니다

계층별로 살펴보기

그림 B 계층마다 잡아내는 문제도 있고 놓치는 문제도 있습니다. 모든 계층을 빠져나가는 문제는 드물고, 나머지는 롤백으로 처리합니다.

1. 다른 사람이 보기 전에 작업부터 검증합니다

이제 리뷰 대부분은 PR이 생기기도 전에 이루어집니다. 저희는 Claude에게 직접 실행해 볼 수 있는 것, 예를 들어 테스트나 빌드, 디자인과 비교해 볼 스크린샷 같은 것을 주고, 다 됐다고 말하는 대신 실행 결과를 보여 달라고 요청합니다. 그다음 서브에이전트가 새 컨텍스트에서 diff를 리뷰합니다. 두 습관 모두 저희 모범 사례 가이드에서 나온 것입니다.

저희 중 상당수는 PR을 열기 전에 내부 스킬도 몇 가지 실행합니다. 하나는 버그를 찾고, 하나는 diff를 단순하게 다듬고, 하나는 동작을 처음부터 끝까지 확인합니다. UI 변경은 디자인 가이드라인에 맞는지도 확인합니다.

Claude Code를 만든 Boris Cherny는 Claude에게 자기 작업을 검증할 방법을 주는 것이 좋은 결과를 얻는 데 아마 가장 중요한 일이라고 말한 바 있습니다. Cherny는 이렇게 하면 최종 결과가 두세 배 좋아진다고 추정하며, 이렇게 썼습니다. "검증의 모습은 분야마다 다르다. bash 명령 하나를 실행하는 것처럼 간단할 수도 있고, 테스트 스위트를 돌리거나 브라우저나 휴대폰 시뮬레이터에서 앱을 테스트하는 것일 수도 있다."

자동 리뷰어가 같은 문제를 계속 지적하면, 저희는 근본에서 고칩니다. 스킬에 반영하거나, 린트 규칙을 만들거나, 다음과 같은 지침 파일을 업데이트합니다.

• CLAUDE.md는 Claude에게 이 프로젝트가 무엇인지 알려 줍니다. 기술 스택, 컨벤션, 목표와 비목표(non-goal)가 여기에 들어갑니다. 모든 리뷰가 이 파일을 불러오기 때문에, 큰 코드베이스에서는 짧게 유지하고 이 파일에서 다른 문서를 가리키게 합니다. 리뷰어는 이 파일에 적힌 컨벤션을 어기는 코드와, 이 파일의 내용 일부를 더는 맞지 않게 만드는 변경도 지적합니다.
• REVIEW.md는 코드 오너가 작성하며, 자기가 맡은 코드 영역에서 무엇이 중요한지 리뷰어에게 알려 줍니다. 리뷰어가 이 파일을 실제로 따르는지는 따로 확인합니다. 잘 쓴 REVIEW.md는 짧습니다. 그 저장소에서 실패가 어떤 모습인지 설명하고(문서라면 '사실과 다른 내용', 설정이라면 '엉뚱한 곳으로 보내는 라우팅'), 사소한 지적(nit)의 개수를 제한하고, 건너뛸 경로를 나열하고, 이름만 보고 짐작하지 말고 파일과 줄 번호를 증거로 대라고 요구합니다. 또 요약을 개수로 시작하고, 고칠 것이 없으면 없다고 분명히 말하라고 요구합니다.

2. 모든 풀 리퀘스트에 대한 AI 리뷰

모든 풀 리퀘스트는 사람이 보기 전에 Claude의 리뷰를 받습니다. Claude는 저장소 전체와 PR에 적힌 의도에 비추어 diff를 읽고 이렇게 묻습니다. 이 변경이 원래 풀려던 문제를 해결하는가, 시스템에 잘 맞는가, 아니면 다른 무언가를 망가뜨리는가?

버그 수정이라면 근본 원인을 찾습니다. 공개 버전인 Code Review for Claude Code는 이제 Team 및 Enterprise 요금제에서 정식으로 제공되고, /code-review는 더 가벼운 버전을 로컬에서 실행합니다.

리서치 프리뷰를 출시했을 때, 실질적인 리뷰 코멘트를 받는 내부 PR의 비율은 16%에서 54%로 올랐습니다. 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 템플릿은 변경을 어떻게 테스트했고 어떻게 되돌릴 수 있는지 묻습니다. 이 항목은 Claude가 채울 수 있지만, 확인하고 승인하는 사람은 그 변경을 요청한 사람입니다.

5. 위험도에 따라 달라지는 사람의 승인

문서 수정과 자동 업데이터 변경은 위험도가 다르므로, 리뷰도 다르게 받습니다.

등급은 작성자가 아니라 변경이 정합니다. 분류기가 변경을 읽고 위험도 등급을 고릅니다. 두 번째 분류기는 등급상으로는 필요 없더라도, 이 특정 변경에 사람이 한 명 더 필요한지 판단합니다. 어떤 경로는 언제나 사람이 봐야 합니다. 오너가 민감하다고 지정한 모든 경로와 모든 CI 워크플로 파일이 그렇습니다.

가벼운 경로는 신뢰받는 작성자만 쓸 수 있습니다. 저장소의 신뢰 목록에 오른 작성자만 가벼운 경로를 이용할 수 있는데, 대부분은 그 저장소를 맡은 팀입니다. 그 밖의 사람은 모두 두 번째 사람의 승인이 필요합니다. 또 에이전트의 승인은 결코 사람의 승인으로 치지 않습니다. 자동 리뷰는 위험도가 낮은 변경을 통과시킬 수는 있지만, 사람이 맡아야 하는 자리를 대신 채울 수는 없습니다.

변경을 프롬프트한 사람이 그 변경을 책임집니다. 에이전트가 작성한 PR에서는 에이전트를 지휘한 사람이 필수 리뷰어 중 한 명으로 계산됩니다. 그 사람이 직접 코드를 입력했을 때와 똑같습니다.

승인은 특정 커밋 하나에만 적용됩니다. 에이전트의 푸시나 누군가 손으로 해결한 병합처럼 시스템이 보증할 수 없는 새 커밋이 들어오면, 승인을 다시 받아야 합니다.

6. 병합 큐, 플래그, 점진적 릴리스

병합 큐는 변경을 적용한 main을 대상으로 모든 검사를 다시 실행합니다. 그래서 따로따로는 통과한 두 PR이 합쳐져 main을 깨뜨리는 일이 생기지 않습니다. 새 동작은 보통 플래그 뒤에 숨긴 채 Anthropic 직원에게 먼저 출시되며, 저희가 워낙 많이 쓰다 보니 사용자보다 먼저 회귀를 발견하는 경우가 많습니다. 공개 릴리스는 먼저 latest 채널로 나갑니다. stable 채널은 그 뒤를 따릅니다.

7. 빠른 감지, 빠른 롤백

그래도 일부 실수는 빠져나가기 마련이라, 마지막 계층은 그런 실수를 빨리 잡아내는 데 집중합니다. 플래그는 배포 없이 끌 수 있습니다. Claude Code에는 주 단위로 돌아가는 온콜 순번이 있고, 장애 리뷰에서는 어느 계층이 그 문제를 잡았어야 했는지 묻습니다.

잘못된 병합을 알아차리는 일은 여전히 작성자와 온콜 담당자, 그리고 되돌림·장애 대시보드에 달려 있습니다. 이 수치가 움직일 때 승인 기준을 조이는 서킷 브레이커는 아직 없습니다. 이곳 엔지니어들은 사람이 전혀 관여하지 않는 병합으로 더 많은 코드를 넘기기 전에 그런 장치부터 갖추기를 바랍니다.

한 동료는 속도를 늦추면 오류율이 낮아지기는 하지만, 그건 주로 모든 일을 덜 하게 되기 때문이라고 말했습니다. 저희는 그보다 문제를 알아차리고 고치는 속도를 높이는 쪽을 택하겠습니다.

리뷰어를 더 낫게 만드는 방법

저희 코드 리뷰 프로세스는 하나의 루프 안에서 끊임없이 개선됩니다.

모든 장애는 이제 평가(eval) 데이터가 됩니다. 팀은 장애를 일으켰던 과거 PR을 그에 따른 후속 수정(fix-forward), 되돌림과 함께 모았고, 해당 코드를 잘 아는 엔지니어들에게 버그 하나하나와 그 버그가 있던 위치를 확인받았습니다. 리뷰어는 매일 이 데이터셋으로 평가를 받습니다.

그림 C 평가 세트는 장애가 생길 때마다 커지고, 리뷰어를 바꿀 때마다 평가 세트 전체로 점수를 매깁니다.

노이즈는 사람들이 코멘트를 어떻게 처리하는지 보고 측정합니다. 버그가 아닌 것까지 잔뜩 지적해도 상관없다면 버그를 더 많이 잡기는 쉽습니다. 그래서 이를 견제할 장치가 필요합니다. 저희는 리뷰어가 남긴 모든 코멘트를 PR 담당자가 어떻게 반응했는지에 따라 분류합니다. 고쳤는지, 틀린 지적이라고 했는지, 의도한 동작이라고 했는지, 중요하지 않다고 판단했는지를 봅니다. 또 문제가 없다고 알려진 PR에 리뷰어를 돌려서, 누군가 해로운 변경을 하게 만들었을 법한 지적을 얼마나 자주 내놓는지 셉니다. 저희가 문서로 정해 둔 우선순위는 첫째가 진짜 버그를 잡는 것이고, 둘째가 리뷰 회차를 줄이는 것입니다.

작성자가 에이전트라면 노이즈의 비용은 더 커집니다. 사람은 사소한 지적쯤은 몇 초 만에 넘길 수 있습니다. 하지만 에이전트는 그 지적을 고치고, 그러면 커밋이 하나 더 생기고 리뷰도 한 차례 더 돌아갑니다.

리뷰는 수렴해야 합니다. 작성자도 에이전트이고 리뷰어도 에이전트라면, 둘은 서로를 끝없이 바쁘게 만들 수 있습니다. 한 CLI PR은 작성자가 멈출 때까지 밤사이 리뷰와 수정을 50번 넘게 반복했습니다.

리뷰어가 계속 지적하는 코드에 git blame을 돌려 보니, 약 59%는 리뷰어가 처음 리뷰했을 때부터 이미 있던 코드였습니다. 리뷰어가 새 버그를 찾는 경우는 드물었고, 회차마다 오래된 버그를 몇 개씩 더 찾아내고 있었던 것입니다.

문제를 키운 데는 저희 탓도 있습니다. 회차마다 새로운 것이 하나씩 잡히다 보니, 기본으로 여러 회차를 돌리는 데 익숙해져 있었습니다. 위험한 변경이라면 그럴 만한 가치가 있을 수 있지만, 모든 PR에 그럴 필요는 없습니다. 팀은 이제 재현율(recall)과 함께 통과까지 걸린 회차 수도 추적하고, 재리뷰 방식을 다음과 같이 바꿨습니다.

• 회차 상한. 세 번째 회차가 지나면 리뷰어는 작성자에게 한발 물러서서 접근 방식을 다시 생각해 보라고 요청합니다.
• 처음 몇 차례 리뷰한 뒤로는 diff만 재리뷰합니다.
• 버그의 유형을 지적합니다. 그래야 작성자가 한 줄만 고치지 않고 같은 유형을 모두 고칩니다.
• 이미 게시한 발견 사항은 반복하지 않습니다.

리뷰 에이전트는 매일 밤 기존 코드도 훑어서, 오래된 버그가 다른 곳에서 문제를 일으키기 전에 잡아내도록 돕습니다.

그림 D 수렴 개선 이후 내부 풀 리퀘스트 하나당 리뷰 회차가 줄었습니다

사람이 계속 관여하는 곳

깊이 몰입해 있는 시니어 엔지니어를 불러내 일상적인 실수 하나를 잡게 하는 것은 자동 리뷰보다 훨씬 큰 비용이 듭니다. Anthropic에서 저희가 하는 일은 모든 diff를 읽는 것에서, 기계가 잘 못하는 결정을 내리는 쪽으로 옮겨 갔습니다.

• 애초에 이걸 만들어야 할까? 방향과 안목, 범위의 문제입니다. 리뷰 병목을 해결했다고 선언한 한 팀도 팀 밖에서 들어온 변경에는 사람의 리뷰를 남겨 두었습니다. 누군가는 "이걸 정말 해야 할까?"라고 물어야 하기 때문입니다.
• 위험한 코드. 과금, 자동 업데이터, CI 워크플로 같은 코드입니다.
• 다른 사람들이 따라 할 패턴을 정하는 아키텍처.
• 증거 읽기. 테스트 출력, 실행한 명령과 그 결과, 스크린샷, 리뷰어의 발견 사항이 여기에 해당합니다. 검사가 무엇을 놓칠지 말할 수 없다면, 빠른 승인 대신 제대로 된 리뷰를 요청하세요.
• 결과에 책임지기. 누가 입력했든, 출시되는 모든 변경에는 책임지는 사람이 있습니다.

그림 E 사람의 역할은 모든 diff를 읽는 일에서 기계가 잘 못하는 결정을 내리는 일로 옮겨 갔습니다

팀 전체에 맥락 공유하기

코드 리뷰의 두 번째 일은 언제나 코드베이스에 대한 이해를 퍼뜨리는 것이었습니다. 팀원의 diff를 읽으면서 무엇이 바뀌었고 각 부분이 어떻게 맞물리는지 배우게 됩니다. 기계가 코드 읽기 대부분을 맡는다면, 사람은 코드를 어떻게 익힐까요?

이를 위한 공식 프로세스는 없습니다. 팀에서 Claude Code 전체에 대한 완전한 멘탈 모델을 머릿속에 담고 있는 사람은 없고, 저희는 누구도 그럴 필요가 없다고 생각합니다. 누군가 코드베이스의 한 부분을 이해하고 싶으면, Claude에게 딱 그 부분에 대한 설명서를 써 달라고 합니다. 몇 분이면 되고, 설명서에는 지금 있는 그대로의 코드가 반영됩니다.

저희 중에는 한 걸음 더 나아가, 그 코드 부분을 시각화하고 자기가 좋아하는 학습 방식으로 가르쳐 주는 작은 아티팩트를 Claude에게 만들게 하는 사람도 있습니다.

사람의 주의력을 잘 쓰는 것이 목표라면, 이쪽이 사소한 diff를 한 줄씩 읽는 것보다 낫습니다. 한 줄짜리 문구 수정에서는 배울 것이 거의 없습니다. 곧 바꾸려는 모듈에 대한 설명서에서는 많은 것을 배웁니다. 기본적으로 공개 Slack 채널에서 일하는 문화도 도움이 됩니다. 다른 사람이 무언가를 만드는 동안 그 과정을 지켜볼 수 있기 때문입니다.

"반영한 사람이 책임진다"

작거나 중간 규모의 변경을 반영했는데 그래도 문제가 생기면, 보통 반영한 사람이 직접 고치는 것이 팀의 규범입니다. 이 방식이 나쁘게 흘러가지 않도록 받쳐 주는 장치가 몇 가지 있습니다.

• 변경이 작습니다. 그래서 리뷰하고, 디버깅하고, 되돌리기 쉽습니다.
• 모든 것을 되돌릴 수 있습니다. 플래그, 되돌림, 단계적 릴리스로 대부분의 실수를 몇 분 안에 원래대로 돌립니다.
• 영향 범위가 기준을 정합니다. 잘못되면 비용이 큰 코드일수록 더 많은 사람과 더 많은 검사가 붙습니다.
• 회귀가 빨리 드러납니다. 텔레메트리와 내부 사용 덕분입니다.
• 누구를 탓하려는 것이 아닙니다. 수정을 맡는 이유는 그 사람이 맥락을 가장 많이 알기 때문이고, 장애 리뷰는 시스템을 들여다봅니다.

책임도 함께 나눕니다. 팀의 상당수는 공개 채널에서 일하는데, 그곳에서는 누구든 다른 사람이 무엇을 만드는지 보고, 스레드를 이어받거나, 빈틈을 Claude에게 맡길 수 있습니다. 피드백도 그 코드를 맡지 않은 사람들에게서 옵니다. 이런 개방성이 한 줄 한 줄마다 관문을 두지 않고도 품질을 높게 유지하는 큰 비결입니다.

방향을 바꿀 때

에이전트 덕분에 일을 시작하는 비용이 싸졌기 때문에, 반영되지 말아야 할 작업도 생깁니다. 보통은 채널의 누군가가 왜 하는지 묻거나, 예전에 내린 결정을 짚어 주거나, 더 간단한 방법을 제안합니다. 그러면 작성자가 PR을 닫거나 방향을 다시 잡습니다.

코드를 빨리 썼으니 PR을 닫아도 손해 본 느낌이 들지 않습니다. 요령은 다른 방향을 완성된 PR에 병합을 막는 코멘트로 다는 것이 아니라, 스레드에서 일찍 꺼내는 것입니다.

여러분의 팀에 이 프로세스를 도입하는 방법

여러분의 팀에서 이렇게 하는 데 필요한 요소는 대부분 이미 나와 있습니다.

풀 리퀘스트 이전

• 에이전트가 실행할 수 있는 검사를 짧은 CLAUDE.md에 정리해 주고, 포매터와 린터를 실행하는 훅도 추가하세요.
• 로컬에서 /code-review와 /security-review를 실행하거나, 새 컨텍스트의 서브에이전트에게 리뷰를 맡기세요.
• REVIEW.md를 추가하고, 반복되는 리뷰 코멘트를 그 파일로 옮기세요.

모든 풀 리퀘스트에서

• CI를 필수로 지정하고, PR 템플릿에 "테스트", "위험도", "되돌리는 방법" 항목을 추가하세요.
• 저장소 하나에 AI 리뷰어(Code Review for Claude Code 또는 Claude Code GitHub Action)를 붙이고, 몇 주 동안 REVIEW.md를 다듬은 다음 범위를 넓히세요.
• 자동 보안 리뷰를 추가하고, 병합 전에 모든 리뷰 스레드를 해결하도록 요구하세요.
• 리뷰에 들이는 노력을 위험도에 맞추세요. 일상적인 변경은 빠르게 한 번 훑고, 버그를 놓쳤을 때 비용이 큰 곳은 깊게 리뷰하세요(Code Review의 Quick, Standard, Deep).
• 리뷰 회차에 상한을 두고, 처음 몇 회차가 지나면 새 diff만 재리뷰하세요.

승인

• 위험도 등급을 문서로 정하되, 작성자가 아니라 변경을 기준으로 정하세요. 처음에는 엄격하게 시작하고, 근거가 쌓이면 완화하세요.
• 가벼운 승인 경로는 신뢰하는 작성자에게만 열어 두세요.
• CODEOWNERS와 브랜치 보호 규칙을 활용해 인증, 과금, CI 및 릴리스 워크플로, 설치 프로그램에는 항상 사람이 필요하게 하세요.
• 봇의 승인이 필수로 받아야 할 사람의 승인을 대신하게 두지 말고, 새 커밋이 올라오면 기존 승인을 무효로 하세요.

병합과 그 이후

• 병합 큐, 기능 플래그, 내부 우선 사용, 단계적 릴리스, 한 번에 되돌리는 롤백을 활용하세요.
• 장애와 되돌림을 평가 세트로 만들고, 리뷰어의 프롬프트나 도구, 모델이 바뀔 때마다 점수를 다시 매기세요.
• 사람의 시간을 측정하되, 되돌림 비율과 장애 비율을 가드레일로 삼으세요.

앞으로의 방향

Code Review 발표문에서는 풀 리퀘스트를 승인하는 일은 여전히 사람이 판단할 몫이라고 밝혔습니다. 제품은 발견 사항을 게시할 뿐, 승인하지는 않습니다. 저희 저장소들은 여기서 한 걸음 더 나아가, 위험도가 낮은 변경 중 어떤 것을 자동 검사만으로 병합할지 오너가 정하게 하고 있으며, 그 경계선은 계속 움직이고 있습니다.

리뷰가 무언가를 놓치면, 저희는 그때 모델이 어떤 정보를 보지 못했는지 묻고, 그 해결책을 CLAUDE.md나 스킬, 혹은 새 검사에 반영합니다. 목표는 변하지 않았습니다. 변경 하나에 드는 사람의 시간은 줄이고, 되돌림은 예전보다 늘리지 않는 것입니다.

여러분의 팀이 에이전트에게 풀 리퀘스트를 열게 한다면, 어떤 검사를 자동화했는지, 어떤 검사에 아직 사람이 필요한지, 그리고 저희가 무엇을 잘못 생각하고 있는지 듣고 싶습니다.