Anthropic은 코드 리뷰를 어떻게 할까?

2026.10.20 게시

코드 변경을 살펴보는 Claude 캐릭터와 리뷰 경험을 정리한 노트

최근 Agent에게 분석·설계·구현뿐 아니라 리뷰도 맡기는 사례를 자주 접한다. 나 역시 방법론을 만들고 실제 작업에 적용하면서 다른 Agent에게 설계와 코드를 리뷰하게 하고 있다. 쓰다 보니 다른 사람들은 어떻게 쓰고 있는지 궁금해졌다.

그러다 Anthropic이 10월 15일에 공개한 How the Claude Code team does code review를 읽었다. Claude Code 팀이 실제로 코드를 검토하고 병합하고, 문제가 생겼을 때 되돌리는 과정까지 설명한 글이다. 내가 리뷰를 쓰며 바꿔 온 방식과 비슷한 부분도 있고, 개인 프로젝트와는 조건이 다른 부분도 있었다.

Anthropic은 Claude Code 코드의 약 90%를 Claude가 작성한다고 밝힌 바 있다. 이 글에서는 6월부터 9월까지 Claude Code 코드베이스에 병합된 PR이 두 배 이상 늘었고, 그중 되돌려야 했던 PR의 비율은 40% 넘게 감소했다고 보고한다. 코드 대부분을 기계가 읽게 하면서 사람의 주의력을 어디에 쓸지 조정하고, 실수를 쉽게 되돌리는 체계를 함께 갖춘 결과다. 여러 변화가 함께 이루어진 내부 운영 결과이므로, 특정 리뷰 기법 하나의 효과로 읽지는 않았다.

아래는 원문의 절 순서를 따라 정리했다. 각 절에서는 Anthropic의 운영을 먼저 설명하고, 직접 연결되는 경험이 있는 곳에만 내 경험을 덧붙였다. 내 기록에는 코드 리뷰뿐 아니라 구현 전 설계 리뷰도 포함된다.

목차
  1. 1. 코드 리뷰의 목적을 다시 생각하다
  2. 2. 가장 부족한 자원은 사람의 시간과 주의력
  3. 3. 변경 하나가 사용자에게 도착하기까지
  4. 4. 하나의 관문 대신 여러 검증 계층을 둔다
    1. 4.1. 다른 사람이 보기 전에 작업 결과를 검증한다
    2. 4.2. 모든 PR에 AI 리뷰를 실행한다
    3. 4.3. 보안 리뷰도 병합을 차단한다
    4. 4.4. 자동화 검사도 병합 조건으로 둔다
    5. 4.5. 위험도에 따라 사람의 승인을 조절한다
    6. 4.6. 최신 main과 합쳐 보고, 출시 범위를 넓힌다
    7. 4.7. 빠르게 발견하고 되돌린다
  5. 5. 리뷰어 자체를 어떻게 개선하는가
    1. 실제 장애를 평가 사례로 만든다
    2. 리뷰가 끝나도록 재검토 방식을 바꾼다
  6. 6. 사람은 어디에 계속 관여하는가
  7. 7. 코드의 맥락을 팀에 어떻게 공유하는가
  8. 8. 병합한 사람이 문제 해결을 맡는다
  9. 9. 시작한 작업의 방향을 바꾸기도 한다
  10. 10. 팀에 도입한다면 어디서 시작하는가
  11. 11. 앞으로 무엇을 바꾸려 하는가
  12. 참고 자료

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

Anthropic이 먼저 꺼내는 문제는 코드가 만들어지는 속도다. Anthropic 모노레포에서 하루에 반영되는 변경은 5월 약 2,500건에서 9월 30,000건 이상으로 늘었다. Claude Code는 이 모노레포와 별도 저장소에 있지만 비슷한 압박을 받는다. 이 규모에서는 사람이 모든 변경을 한 줄씩 읽는 방식으로 따라가기 어렵다.

원문은 코드 리뷰의 역할을 두 가지로 나눈다. 배포 전에 문제를 찾아 고치는 것, 그리고 팀이 코드베이스에 대한 이해를 공유하는 것이다. 우선 첫 번째 역할에 집중하면서 질문을 바꾼다. 사람이 읽었는지만 확인하는 대신, 이 변경에서 무엇이 잘못될 수 있고 그것을 잡기에 적절한 검사는 무엇인지 묻는다. 그 검사는 자동화일 수도 있고 사람의 검토일 수도 있다.

이 질문은 리뷰 시점도 바꾼다. 예전에는 코드를 작성하고 PR을 연 다음 동료를 기다렸다면, 지금은 작성 중에도 계속 리뷰를 실행한다. 대부분의 변경은 사람이 보기 전에 Claude의 검토와 수정을 적어도 한 번 거친다. 일상적인 실수는 이 과정에서 먼저 처리하고, 사람에게는 더 높은 수준의 판단을 남기는 방식이다.

내 경험 — 리뷰어를 나눈 다음에는 질문을 좁혀야 했다.

2편에서 구현 담당과 리뷰 담당을 분리했다. 그런데 그냥 “리뷰해줘”라고 하니 전체 코드와 문서를 다시 훑고, 실제 변경과 관계가 적은 대안이나 이미 정한 설계까지 다시 논의했다. 그래서 백로그에서 변경 내용과 확인할 지점을 추려 리뷰용 요약으로 넘겼다. 검토가 실제 변경에 가까워졌지만, 이후에는 요약에서 빠진 사실까지 놓칠 수 있다는 문제가 남았다. 무엇을 확인할 리뷰인지 정하는 일이 별도 Agent를 부르는 것만큼 필요했다.

2. 가장 부족한 자원은 사람의 시간과 주의력

Anthropic은 사람이 리뷰에 쓰는 시간과 잘못된 코드 때문에 복구에 쓰는 시간을 함께 본다. 리뷰 시간을 줄여도 장애를 고치는 시간이 늘면 비용을 옮긴 셈이기 때문이다.

목표도 구체적이다. CLI, 데스크톱·웹, 모바일 등 Claude Code 저장소의 대부분 PR이 최대 한 명의 사람만 관여한 상태로 병합되게 하되, 롤백과 장애는 늘리지 않는 것이다. 이 한 명은 PR 작성자여도 된다. 사람의 관여를 줄이는 목표와 운영 결과를 지키는 조건이 붙어 있다.

보는 대상 추적하는 지표 확인하려는 것
승인 부담 PR당 사람 승인 수의 중앙값·95백분위수 보통의 PR과 승인이 많이 필요한 PR의 부담
사람의 개입 사람이 작성한 리뷰 댓글 수 사람이 검토 과정에 얼마나 관여하는가
기다림 PR이 사람의 응답을 기다리는 시간 개발 흐름이 어디에서 멈추는가
병합 이후 롤백 비율·장애 발생률 리뷰에서 줄인 비용이 복구 비용으로 옮겨가지는 않았는가

출처: Anthropic 원문의 측정 항목을 정리했다. 개인 프로젝트의 측정 결과는 아니다.

내 경험 — 검토하는 사람은 나 하나였다.

20편에서 다룬 문제도 사람의 처리량이었다. Agent가 확인할 내용을 만드는 속도는 빨라졌는데, 단계마다 검토하고 승인하는 사람은 나 하나였다. 하루에 읽을 양이 감당하기 어려워지자 의무감으로 승인하는 날이 생겼다. 키로 서명하게 만들었더니 키가 없는 환경에서는 진행 자체가 막혔다. 결국 10월 15일 설계 단계 승인과 서명을 빼고, 미해결 질문과 큰 작업의 병합에 사람 판단을 남겼다. 승인 부담을 줄이려는 변경이었고, 이후 재작업까지 줄었는지는 아직 재지 않았다.

3. 변경 하나가 사용자에게 도착하기까지

일반적인 변경은 개발자의 노트북이나 Slack의 Claude 세션에서 시작한다. PR을 만들기 전부터 작업을 실행해 검증하고, PR이 생기면 CI·코드 리뷰·보안 리뷰를 거친다. 위험도에 맞는 승인을 받은 뒤에도 검증은 이어진다. 최신 main과 합쳤을 때의 상태를 확인하고, 내부 사용과 단계적 출시를 거쳐 사용자에게 전달한다.

시점 실제로 하는 일 다음 단계로 가져가는 근거
PR 생성 전 테스트·빌드·린트 실행, 새 문맥의 Agent가 diff 검토 실행 결과와 수정한 변경분
PR 생성 후 필수 CI, 여러 Agent의 코드 리뷰, 별도 보안 리뷰 검사 통과와 지적 사항 처리
승인 변경 위험도와 경로에 따라 사람 승인 요구 해당 커밋에 대한 필요한 승인
병합 Merge Queue에서 최신 main에 변경을 적용해 재검증 함께 병합해도 검사를 통과하는 상태
병합 이후 기능 플래그, 직원 우선 사용, latest → stable 출시 내부 사용과 공개 이후의 관측
문제 발생 작성자·당직 담당자가 확인하고 수정 또는 롤백 복구 결과와 다음 평가에 쓸 실패 사례

출처: Anthropic 원문의 변경 흐름을 표로 재구성했다. 모든 단계를 한 번의 리뷰 호출로 수행하는 구조는 아니다.

여기서 사람은 마지막에 코드를 읽는 역할로만 등장하지 않는다. 위험한 변경을 판단하고, 검증 근거를 확인하며, 병합 이후 문제가 생겼을 때도 관여한다. 자동화가 많은 경로를 담당하고 사람의 주의력이 위험한 지점에 모이는 흐름이다.

내 경험 — 지적을 해결할 단계도 나눴다.

9월에 누락 탐색 리뷰를 추가한 뒤에는 구현에서 고칠 문제까지 설계 차단으로 남으면서 문서와 리뷰가 반복될 수 있었다. 그래서 사람이 결정할 문제, 구현 전에 계약을 확정할 문제, 구현에서 고치고 검증할 문제, 현재 작업을 막지 않는 관찰을 나눴다. 계획에서 풀어야 할 차단 문제가 없으면 구현으로 넘어가고, 인계한 지적은 코드와 테스트로 닫도록 했다. 지적을 발견하는 것에 더해 어느 단계에서 해결을 확인할지도 정한 셈이다.

4. 하나의 관문 대신 여러 검증 계층을 둔다

Anthropic의 구조는 서로 다른 검사가 각자의 빈틈을 보완하는 방식이다. 실행 검증, AI 리뷰, 보안 리뷰, 사람 판단, 병합과 출시 과정이 각각 문제를 찾는다. 그 모두를 통과한 문제에 대비해 빠른 롤백을 아래에 둔다. 원문은 이를 다음 일곱 부분으로 풀어 설명한다.

4.1. 다른 사람이 보기 전에 작업 결과를 검증한다

먼저 Claude가 직접 실행하거나 확인할 수 있는 수단을 준다. 테스트와 빌드, 디자인과 비교할 스크린샷이 여기에 해당한다. 완료했다는 말만 받는 대신 실행 결과를 요구하고, 이후 별도 Agent가 새 문맥에서 diff를 검토한다. 많은 팀원은 PR을 열기 전에 버그 탐색, diff 단순화, 처음부터 끝까지 동작 확인을 맡는 내부 스킬도 실행한다. UI 변경은 디자인 가이드라인과 대조한다.

반복해서 같은 지적이 나오면 다음 리뷰에서도 다시 지적하도록 두는 데서 끝내지 않는다. 스킬, 린트 규칙, 지침 파일을 바꿔 원인 쪽에 반영한다. 원문은 두 파일의 역할을 구체적으로 설명한다.

파일 담는 내용 리뷰에서 사용하는 방법
CLAUDE.md 기술 구성, 규칙, 목표와 하지 않을 일 규칙 위반뿐 아니라 변경 때문에 설명이 낡아진 부분도 확인한다. 매번 읽으므로 짧게 쓰고 상세 문서로 연결한다.
REVIEW.md 코드 소유자가 정한 해당 영역의 실패 기준과 검토 범위 사소한 지적의 수와 제외 경로를 정하고, 파일명 추측 대신 파일·줄 근거를 요구한다. 리뷰어가 지침을 따르는지도 별도로 확인한다.

문서 저장소에서는 잘못된 정보를 주는 것, 설정에서는 잘못된 대상으로 연결하는 것이 실패의 예다. 좋은 REVIEW.md는 이런 기준을 짧고 구체적으로 적는다. 결과도 지적 개수로 시작하고, 수정할 문제가 없으면 없다고 명확히 알리도록 한다. 원문에서 Boris Cherny는 스스로 검증할 수단을 주는 것이 결과를 두세 배 개선한다고 추정하지만, 이는 이 글에서 제시한 통제 실험의 수치는 아니다.

4.2. 모든 PR에 AI 리뷰를 실행한다

사람이 보기 전에 모든 PR이 Claude 리뷰를 받는다. 리뷰어는 diff만 고립해서 보지 않고 전체 저장소와 PR에 적힌 의도를 함께 참고한다. 변경이 원래 문제를 해결하는지, 기존 시스템과 맞는지, 다른 동작을 깨뜨리지 않는지 확인한다. 버그 수정에서는 근본 원인도 살핀다.

리뷰 결과를 곧바로 사람에게 보내지도 않는다. 여러 Agent가 병렬로 버그를 찾고, 별도 Agent 그룹이 각 지적이 실제 문제인지 검증하며 투표한다. 충분한 동의를 얻은 지적만 남기고, 스타일·진단 정보·단순 정리에 관한 지적은 걸러낸다. 이 필터는 자체 PR에서 A/B 테스트한 뒤 유지하기로 했다고 설명한다.

남은 지적은 심각도순의 인라인 댓글로 표시한다. Important, Nit, Pre-existing 분류를 붙여 기존부터 있던 문제와 이번 PR이 만든 문제를 구분한다. 모든 지적에는 수정하거나 수정하지 않을 이유를 남겨 대화를 해결해야 한다. 밤사이 Agent가 수정해서 작성자가 돌아왔을 때 이미 후속 리뷰까지 끝나 있는 경우도 있다.

연구 미리보기 출시 당시, 실질적인 리뷰 의견이 달린 내부 PR 비율은 16%에서 54%로 늘었다. 1,000줄이 넘는 PR에는 대부분 지적이 나오고 작은 PR은 대부분 문제가 없다고 판정된다고 한다. 여기서 16%와 54%는 리뷰 의견이 달린 PR의 비율이다. 결함 검출률이나 장애 감소율을 뜻하지 않는다.

원문 게시 시점에는 공개 제품인 Code Review for Claude Code가 Team·Enterprise에서 정식 제공되며, /code-review는 더 가벼운 로컬 리뷰를 실행한다고 설명한다. 저장소별 Quick·Standard·Deep 수준도 설정할 수 있다. 놓친 버그 하나의 비용이 추가 검토 비용보다 큰 영역에는 Deep을 사용하는 식이다.

내 경험 — 사실 확인과 누락 탐색을 분리했다.

내 설계 리뷰에서는 문서에 적힌 주장과 직접 연결된 코드는 확인했는데, 기존 화면의 소비 경로와 복구 조건, 저장소 사이의 경계처럼 문서 밖에 빠진 사실이 별도 검토에서 나왔다. 그래서 9월 5일 큰 작업의 현황 분석과 계획에 Review A와 B를 나눴다. A는 사실·계약의 일관성을, B는 빠진 사실과 숨은 가정을 찾게 했다. B의 첫 판단 전에는 A의 PASS와 지적 목록을 주지 않았다. 기록에는 B가 상위 계약 충돌과 복구 누락을 추가로 찾은 사례가 남아 있다. Anthropic의 후보 지적 검증·투표와 내 설계 A/B는 역할이 다르지만, 한 리뷰에 어떤 질문을 맡길지 나눈다는 점을 함께 볼 수 있었다.

4.3. 보안 리뷰도 병합을 차단한다

보안은 일반 버그 리뷰와 별도로 자동 검토한다. 버그 리뷰나 보안 리뷰의 지적이 하나라도 미해결이면 PR을 병합할 수 없다. 실제 문제는 수정하고, 오탐이거나 수정하지 않을 이유가 있으면 짧은 설명을 남겨 대화를 닫는다. 이후 커밋에서 문제가 수정되면 지적은 자동으로 해결된다.

이 과정에서 필요한 것은 지적마다 대응이 남는 것이다. 리뷰어가 지적했다는 이유만으로 모든 코드를 고치는 방식은 아니다. 원문은 같은 구성을 적용할 수 있는 수단으로 오픈소스 보안 리뷰 GitHub Action과 /security-review를 소개한다.

4.4. 자동화 검사도 병합 조건으로 둔다

린트, 타입 검사, 플랫폼별 테스트, 빌드는 계속 필수다. 일반적인 CLI PR 하나도 사람이 보기 전에 수십 개의 검사를 실행할 수 있다고 한다. AI가 코드를 읽고 판단하는 과정과 실행 가능한 검사는 함께 유지된다.

PR 템플릿에는 어떻게 테스트했는지, 문제가 생기면 어떻게 되돌릴지를 적는다. Claude가 작성할 수 있지만, 변경을 요청한 사람이 그 내용을 확인하고 승인한다. 검사 결과뿐 아니라 검증과 복구 방법을 사람이 확인할 수 있게 남기는 구조다.

4.5. 위험도에 따라 사람의 승인을 조절한다

문서 수정과 자동 업데이트 코드 변경은 실패했을 때의 영향이 다르다. Anthropic은 변경 내용을 읽는 분류기로 위험도를 정하고, 두 번째 분류기로 그 변경에 추가 사람 검토가 필요한지도 판단한다.

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

출처: Anthropic의 내부 승인 정책. 신뢰 작성자·경로별 예외 조건은 아래와 함께 읽어야 한다.

완화된 경로는 저장소의 신뢰 목록에 있는 작성자에게만 적용한다. 그 밖의 작성자에게는 추가 사람 승인이 필요하다. 소유자가 민감하다고 정한 경로와 모든 CI 워크플로 파일은 항상 사람 검토를 요구한다. Agent의 승인은 사람 승인 자리를 채우지 못한다.

Agent에게 변경을 지시한 사람은 직접 코드를 작성했을 때처럼 필수 리뷰어 중 한 명으로 인정되며 변경에 책임을 진다. 승인도 특정 커밋에만 유효하다. Agent의 추가 푸시나 수동으로 해결한 병합처럼 시스템이 보증할 수 없는 새 커밋이 들어오면 다시 승인받는다.

4.6. 최신 main과 합쳐 보고, 출시 범위를 넓힌다

각 PR이 따로 검사를 통과했어도 함께 합친 상태는 다를 수 있다. Merge Queue는 최신 main에 변경을 적용한 상태에서 검사를 다시 실행한다. 개별 PR 검증 다음에 통합 상태를 확인하는 단계다.

새 동작은 보통 기능 플래그 뒤에 두고 Anthropic 직원에게 먼저 공개한다. 직원들이 제품을 많이 사용하면서 사용자에게 공개되기 전 회귀를 발견한다. 공개 버전도 latest 채널에 먼저 배포하고 stable 채널이 뒤따른다. 병합 직후 모든 사용자에게 같은 범위로 노출하는 흐름과는 차이가 있다.

4.7. 빠르게 발견하고 되돌린다

검사를 통과한 뒤의 실수에도 대응한다. 기능 플래그는 재배포 없이 끌 수 있고, Claude Code 팀은 주 단위로 당직을 교대한다. 작성자와 당직 담당자가 롤백·장애 현황판 등을 보며 문제를 확인한다. 장애를 검토할 때는 어느 검증 계층에서 잡았어야 했는지도 묻는다.

원문은 아직 갖추지 못한 장치도 밝힌다. 롤백과 장애 지표가 나빠지면 승인 기준을 자동으로 강화하는 차단 장치는 없다. 팀의 엔지니어들은 사람 승인 없이 병합하는 범위를 더 넓히기 전에 이를 원한다고 한다. 현재의 자동 병합 범위는 검증뿐 아니라 사람이 관측하고 복구하는 운영 위에 놓여 있다.

5. 리뷰어 자체를 어떻게 개선하는가

실제 장애를 평가 사례로 만든다

Anthropic은 과거 장애를 일으킨 PR과 후속 수정·롤백을 모으고, 그 코드를 아는 엔지니어가 버그의 존재와 위치를 확인하게 했다. 리뷰어는 이 평가 집합 전체를 매일 실행한다. 새 장애가 생기면 사례를 늘리고, 프롬프트·도구·모델을 바꿀 때도 전체 사례로 평가한다. 점수가 개선되면 변경을 유지하고 그렇지 않으면 되돌리는 순환이다.

버그를 많이 찾는지만 보지는 않는다. 리뷰 댓글에 대해 작성자가 실제 수정했는지, 잘못된 지적이라고 했는지, 의도된 동작이라고 설명했는지, 중요하지 않다고 판단했는지를 분류한다. 문제가 없다고 확인된 PR에도 리뷰어를 실행해, 지적을 따랐으면 오히려 해로운 변경을 했을 사례를 센다. 실제 버그 발견을 첫째로, 리뷰 반복 감소를 둘째로 둔다.

Agent가 작성자일 때는 불필요한 지적의 비용도 커진다. 사람은 사소한 지적을 무시할 수 있지만 Agent는 수정하고 새 커밋을 만든다. 그 커밋이 또 리뷰를 부른다. 오탐이 코드 변경과 반복 작업으로 이어질 수 있는 것이다.

리뷰가 끝나도록 재검토 방식을 바꾼다

실제로 CLI 저장소의 한 PR은 작성자가 중단하기 전까지 하룻밤에 50회 넘게 리뷰와 수정을 반복했다. 계속 지적한 코드를 git blame으로 확인했더니 약 59%는 첫 리뷰 때부터 존재하던 코드였다. 새로 만든 버그를 계속 발견했다기보다, 매번 기존 문제를 조금씩 더 찾아내고 있었다.

팀도 매번 무언가 나오니 여러 차례 리뷰하는 것을 기본으로 삼았다고 돌아본다. 위험한 변경에는 가치가 있어도 모든 PR에서 그렇게 할 필요는 없었다. 그래서 버그 발견과 함께 통과까지 필요한 리뷰 횟수를 추적하고 재검토 규칙을 바꿨다.

바꾼 규칙 실제 동작
반복 횟수 제한 세 차례 뒤에는 작성자에게 접근 방식 자체를 다시 보도록 요청한다.
변경분 재검토 초기 몇 차례 이후에는 새로 바뀐 diff만 확인한다.
같은 유형을 묶어 지적 한 줄씩 고치게 하지 않고 동일한 버그 유형의 발생 지점을 함께 수정하게 한다.
같은 지적 반복 금지 이미 보고한 지적을 다시 게시하지 않는다.
기존 코드 별도 검사 매일 밤 기존 코드도 검사해 오래된 버그를 찾는다.

이 변경 뒤 Anthropic 내부 PR에서는 다음과 같은 결과를 보고했다.

내부 PR의 리뷰 수렴 지표 개선 전 개선 후
한 차례 리뷰·수정으로 통과 65% 78%
5회 이상 리뷰가 필요한 PR 8.9% 1.5%
통과까지 평균 리뷰 횟수 2.08회 1.32회

출처: Anthropic 원문 Figure D. 여러 수렴 규칙을 적용한 내부 전후 결과이며, 개별 규칙의 효과나 내 프로젝트 결과를 뜻하지 않는다.

내 경험 — 새 버전마다 처음부터 보는 규칙을 고쳤다.

내 작업에서도 지적을 반영할 때마다 새 버전이 생기고, 새 리뷰가 다시 누락을 찾았다. 9월 25일에는 SHA가 바뀌었다는 이유만으로 A와 새 B를 모두 다시 시작하던 규칙을 영향 기준으로 바꿨다. 기록만 바뀌면 검토 대상을 유지하고, 국소 수정이면 변경분과 직접 영향을 확인하고, 핵심 결정이나 복구 의미가 달라지면 설계를 다시 보게 했다. 같은 충돌이 수정과 재확인 뒤에도 두 번 연속 남으면 자동 리뷰를 멈추고 범위·근거·사람 판단을 다시 정하도록 했다. 선택한 사례의 진단은 했지만 실제 작업의 반복 횟수나 비용 감소는 비교하지 않았다.

내 경험 — 기대대로 동작한 것과 개선을 입증한 것은 달랐다.

8편에서는 관계없는 요청에 Skill이 실행되어 설명을 고치고 Eval을 돌렸다. 수정 뒤 몇 문장이 기대대로 동작했지만 수정 전 기준선이 없었다. 설명을 바꿔서 좋아졌다고 말할 수는 없었고, 호출 여부와 실행 후 절차 준수도 따로 봐야 했다. 리뷰 규칙을 바꾼 지금도 같은 질문이 남는다. 놓쳤던 문제와 정상 변경을 함께 둔 평가가 있어야, 지적을 더 많이 내는 변화와 실제로 도움이 되는 변화를 구분할 수 있다.

6. 사람은 어디에 계속 관여하는가

Anthropic은 일상적인 실수를 찾기 위해 숙련된 엔지니어의 집중을 끊는 비용이 자동 리뷰보다 크다고 설명한다. 그러면서도 사람이 계속 맡는 일을 분명히 남긴다.

첫째는 무엇을 만들지 결정하는 일이다. 방향과 범위, 제품에 대한 판단이 포함된다. 리뷰 병목을 해결했다고 본 팀도 외부에서 들어오는 변경에는 사람 리뷰를 유지했다. 애초에 해야 할 작업인지 묻는 사람이 필요했기 때문이다. 결제·자동 업데이트·CI 같은 위험한 코드와, 다른 개발자들이 따라 할 구조를 정하는 아키텍처도 사람이 본다.

또 사람은 검증 근거를 직접 읽는다. 테스트 출력, 실행 명령과 반환 결과, 스크린샷, 리뷰 지적이 그 대상이다. 현재의 검증이 무엇을 놓칠 수 있는지 설명할 수 없다면 형식적으로 승인하지 말고 제대로 된 리뷰를 요청해야 한다고 한다. 누가 코드를 작성했든 배포되는 변경마다 책임지는 사람도 남는다.

내 경험 — 빠진 대안을 리뷰가 찾고 선택은 내가 했다.

20편에서 설계 승인을 방법론에 남길지 검토할 때, 처음에는 유지하거나 프로젝트 선택으로 넘기는 안이 있었다. 독립 리뷰가 “설계 판단은 유지하되 서명 같은 기록 수단만 가볍게 하는 안”이 빠졌다고 지적해 대안이 추가됐다. 그런데 그 안과 승인 자체를 프로젝트가 고르는 안을 비교하려면, 설계 승인이 재작업을 줄이는지 알아야 했다. 측정이 없어서 Agent는 권고를 거뒀다. 나는 서명 비용뿐 아니라 혼자 승인하는 병목을 겪었기 때문에 프로젝트가 판단 지점을 고르는 안을 선택했다. 리뷰가 선택지를 보완해도 무엇을 감수할지 정하는 일은 남았다.

7. 코드의 맥락을 팀에 어떻게 공유하는가

글 앞에서 미뤄 둔 코드 리뷰의 두 번째 역할로 돌아온다. 동료의 diff를 읽는 것은 무엇이 바뀌고 각 부분이 어떻게 연결되는지 배우는 방법이었다. 기계가 대부분을 읽게 되면 이 학습은 어떻게 되는가.

Anthropic은 이를 위한 공식 절차는 없다고 밝힌다. 팀에 코드베이스 전체를 머릿속에 담고 있는 사람은 없고, 그럴 필요도 없다고 본다. 특정 영역을 이해해야 할 때 Claude에게 현재 코드를 기준으로 설명 문서를 만들게 한다. 원문에서는 관리형 설정을 어떻게 가져오는지 묻는 예를 든다. 일부 팀원은 그 영역을 시각화한 작은 결과물도 만들게 하고 자신에게 맞는 방식으로 설명받는다.

문구 한 줄의 diff를 읽는 것보다 지금 수정할 모듈의 설명을 읽는 편이 더 많은 맥락을 줄 수 있다는 관점이다. 기본적으로 공개 Slack 채널에서 작업해 다른 사람이 무엇을 만들고 있는지 볼 수 있는 문화도 이를 돕는다. 필요할 때 현재 코드를 설명받는 방식과 진행 중인 작업이 보이는 환경이 함께 있다.

8. 병합한 사람이 문제 해결을 맡는다

작거나 중간 규모의 변경을 병합한 뒤 문제가 생기면, 일반적으로 병합한 사람이 수정한다. 원문은 이 관례가 작동하는 조건을 함께 설명한다. 변경이 작아야 리뷰·디버깅·되돌리기가 쉽고, 기능 플래그·커밋 되돌리기·단계적 출시로 대부분의 실수를 빠르게 복구할 수 있어야 한다. 실패 비용이 큰 변경에는 더 많은 사람과 검사를 붙인다. 원격 측정과 내부 사용은 회귀가 빨리 드러나도록 돕는다.

책임을 맡기는 이유는 그 사람이 변경의 맥락을 가장 많이 알고 있기 때문이다. 장애 분석은 개인보다 시스템을 대상으로 한다. 팀원들은 공개 채널의 작업을 보고 논의에 참여하거나 빠진 곳에 Claude를 투입할 수 있고, 담당자가 아닌 사람도 피드백을 준다. 변경에 대한 담당 책임과 팀의 공동 지원이 함께 있는 방식이다.

이 절까지 읽으면 앞의 저위험 자동 병합이 어떤 환경을 전제로 하는지 더 분명해진다. 작은 변경, 되돌리기 수단, 관측, 수정할 담당자, 주변의 피드백까지 이어져 있다.

9. 시작한 작업의 방향을 바꾸기도 한다

Agent 덕분에 작업을 시작하는 비용이 낮아졌으므로, 시작한 PR을 모두 병합할 필요는 없다고 한다. 공개 채널에서 누군가 작업 이유를 묻거나 이전 결정을 알려주거나 더 간단한 방법을 제안하면, 작성자는 PR을 닫거나 방향을 바꾼다. 코드를 쓰는 데 들인 비용이 작아 닫는 것도 큰 손실로 느끼지 않는다고 설명한다.

이때 개입 시점이 중요하다. 다 만든 PR에 병합을 막는 댓글을 남기기보다 논의 초기에 다른 방향을 제시한다. 코드가 조건을 만족하는지 검토하는 것과 작업 방향을 바꾸는 대화가 개발 과정 안에서 함께 일어난다.

내 경험 — 통과시킬 조건 자체가 커지기도 했다.

19편에서는 필요한 실제 모델 검증을 고르려던 작업이 처음에는 API 112회 호출 계획이 됐다. 줄인 뒤에도 28결과를 전부 통과해야 한다는 완료 조건이 남았다. 최초 112회 계획도 리뷰를 통과했다. 규모는 줄였지만 무엇이 위험해서 꼭 확인해야 하는지보다 정해진 집합을 채우는 일이 중심에 남았다. 계약에 맞게 진행되는지와 함께 그 계약이 원래 목적에 비례하는지, 더 작은 대안은 없는지를 앞에서 물었어야 했던 사례다.

10. 팀에 도입한다면 어디서 시작하는가

원문은 앞의 운영을 도입 단계별로 정리한다. PR 전에는 Agent가 실행할 검증 명령을 짧은 CLAUDE.md에 적고 포맷터·린터 훅을 둔다. 로컬 리뷰나 새 문맥의 Agent 리뷰를 실행하고, 반복 지적은 REVIEW.md의 규칙으로 옮긴다.

PR에서는 CI를 필수로 만들고 템플릿에 Testing, Risk, How to revert를 넣는다. AI 리뷰어는 하나의 저장소부터 적용해 몇 주 동안 REVIEW.md를 조정한 뒤 범위를 넓히라고 권한다. 보안 리뷰와 대화 해결 조건을 추가하고, 위험에 따라 리뷰 강도를 조절한다. 초기 검토 뒤에는 변경분을 중심으로 재검토하고 반복 횟수도 제한한다.

승인 단계에서는 위험도를 문서화하고 처음에는 엄격하게 시작해 근거가 쌓이면 완화한다. 신뢰 작성자에게만 완화된 경로를 주고, 인증·결제·CI·출시 워크플로·설치 프로그램 관련 변경에는 CODEOWNERS와 브랜치 보호로 사람 승인을 남기도록 한다. 봇 승인이 사람 승인을 대신하지 않게 하고 새 커밋에는 기존 승인을 무효화한다.

병합과 출시에는 Merge Queue, 기능 플래그, 내부 우선 공개, 단계적 출시, 간단히 실행할 롤백을 둔다. 장애·롤백 사례는 평가에 넣고 리뷰어의 프롬프트·도구·모델이 바뀔 때 다시 평가한다. 사람 시간과 롤백·장애를 함께 측정하는 것까지가 도입 절차에 포함된다.

적용 시점 먼저 갖출 것 운영하면서 조정할 것
PR 전 실행 가능한 검증, 짧은 지침, 별도 리뷰 반복 지적을 규칙으로 옮기기
PR 필수 CI·보안 리뷰·지적 처리, 검증·위험·복구 기록 한 저장소에서 리뷰 강도와 재검토 범위 조정
승인 위험도·신뢰 작성자·민감 경로별 사람 승인 근거가 쌓인 범위에서 승인 완화
병합 이후 통합 검증, 단계적 출시, 롤백 실패 사례 평가와 사람 시간·장애의 동시 관측

출처: Anthropic의 도입 제안. 내 프로젝트에 모두 적용했다는 목록은 아니다.

11. 앞으로 무엇을 바꾸려 하는가

원문은 공개 제품과 내부 저장소를 구분하며 끝난다. Code Review 제품은 지적 사항을 게시하고, PR 승인 여부는 사람이 결정한다. 내부 저장소에서는 소유자가 저위험 변경에 자동 검증만으로 병합을 허용할지 정할 수 있고 그 범위가 계속 달라지고 있다.

리뷰가 문제를 놓치면 모델에게 필요한 어떤 정보가 없었는지 묻는다. 그 정보를 CLAUDE.md, 스킬, 새로운 검사에 반영한다. 목표는 변경 하나당 사람이 쓰는 시간을 줄이면서 롤백은 늘리지 않는 것이다. 리뷰를 실행하는 도구만이 아니라, 실패가 다음 검증을 바꾸는 운영을 계속 손보고 있다.

내 경험 — 규칙을 바꾼 다음 무엇을 볼지가 남았다.

나는 리뷰 범위를 좁혔다가 누락 탐색을 따로 두었고, 지적을 해결할 단계와 재검토 범위를 나눴다. 승인 병목에서는 설계 단계 승인을 줄이되 리뷰와 미해결 질문에서의 사람 판단은 남겼다. 각각 실제로 막힌 곳을 고친 변경이지만, 그 전체가 품질과 비용을 얼마나 개선했는지는 아직 모른다. 지금 있는 기록에서 추가로 찾은 유효한 문제, 기각한 지적, 다시 검토한 이유, 병합 뒤 재작업을 구분해 보는 것이 다음 질문이다.

Anthropic의 글을 읽고 나서는 내가 바꾼 리뷰 규칙 옆에 무엇을 더 확인해야 할지가 보였다. 다음 리뷰가 새로운 근거를 주는지, 이미 본 문제를 다시 도는지. 사람이 확인하는 시간을 줄인 만큼 뒤에서 복구할 일이 늘지는 않았는지. 리뷰를 계속 쓰면서 이 둘을 같이 보려고 한다.


참고 자료

2026년 10월 20일 기준. 개인 사례의 과거 검증은 이번 글을 위해 다시 실행하지 않았다.