리뷰어를 사는 대신 설계를 가져왔다 — Claude Code Review와 직접 만든 PR 에이전트#

2026-10-25

오른쪽 유리 진열장 안 완성품 리뷰 기계에서 빛나는 부품 하나를 떼어 내, 빛의 궤적을 따라 왼쪽 작업대 위에 직접 조립한 컨베이어 기계로 옮기는 그림

뉴스 브리프에서 본 두 소식#

지난주 AI 뉴스 브리프를 정리하면서 코드 리뷰에 관한 소식 두 개를 나란히 다뤘습니다. 하나는 Anthropic의 Claude Code 팀이 자기 저장소의 코드 리뷰를 어떻게 다시 설계했는지 공개한 글과, 그 리뷰어의 공개 버전인 Claude Code Review의 정식 출시입니다. 다른 하나는 GitHub이 PR(Pull Request, 코드 변경을 반영해 달라는 요청) 과정에 보안 장치를 여럿 더했다는 소식입니다.

브리프를 쓰는 동안 같은 질문이 계속 떠올랐습니다. 이것을 필자의 회사에 들이면 지금보다 나아질까요?

필자는 올해 7월부터 회사 저장소들의 PR을 리뷰하고 병합하는 에이전트를 직접 만들어 운영하고 있습니다. 그래서 질문은 “도입할까"보다 “직접 만든 것을 버리고 갈아탈 만큼 나은가"에 가까웠습니다.

답을 먼저 적으면 이렇습니다. 제품은 들이지 않기로 했습니다. 대신 제품의 설계를 가져오기로 했습니다. Code Review는 리뷰만 하는 제품이고, 필자에게 필요한 것은 리뷰 다음의 병합, 충돌 해소, 배포까지였습니다. 그리고 필자는 하네스(에이전트가 일하는 규칙과 도구를 감싸는 틀)를 직접 고칠 수 있으니, 좋은 아이디어만 골라 넣으면 됩니다.

다만 가져오는 과정이 단순한 복사는 아니었습니다. 어떤 아이디어는 필자 환경의 전제와 부딪혀 모양을 바꿔야 했고, 어떤 아이디어는 따져 보니 가져오지 않는 편이 나았습니다. 이 글은 그 판단의 기록입니다.

먼저 필자의 PR 에이전트가 무엇을 하는지 소개합니다. 그다음 Claude Code Review와 GitHub의 보안 장치를 살펴보고, 셋을 나란히 놓아 비교합니다. 마지막으로 가져오지 않은 것과 가져와서 바꾼 것을 정리합니다.

필자가 운영 중인 PR 에이전트#

왜 만들었나#

에이전트에게 코드를 맡기기 시작하면 코드는 빨리 나옵니다. 막히는 곳은 그다음입니다. 누군가 PR을 읽고, CI(Continuous Integration, 코드를 올릴 때마다 테스트와 검사를 자동으로 돌리는 장치)가 끝나기를 기다리고, 앞 PR이 병합되면 뒤 PR의 충돌을 풀고, 병합 버튼을 누르고, 배포를 확인해야 합니다. 이 일을 사람이 하면 사람이 병목이 됩니다.

필자의 PR 에이전트는 이 병목을 줄이려고 만들었습니다. 목표는 사람이 끼어드는 순간을 최소로 만드는 것입니다.

한 회차에 하는 일#

에이전트는 오픈소스 에이전트 Hermes 위에서 돕니다. 클라우드 서버 한 대에 올려 두었고, 명령 실행은 Docker 컨테이너 안으로 격리했습니다. 10분마다 한 회차가 돌고, 한 회차에 하는 일은 다음과 같습니다.

리뷰: 새로 올라오거나 바뀐 PR을 리뷰합니다. 리뷰는 읽기 전용 하위 에이전트(부모 에이전트가 일을 나눠 맡기는 보조 에이전트)들에게 두세 건씩 나눠 맡깁니다.
병합: 리뷰를 통과한 PR을 오래된 순서로 병합합니다.
충돌 해소: 앞 PR이 병합되면서 충돌이 생긴 PR은 에이전트가 직접 풉니다. 해소 방향이 분명하지 않으면 풀지 않고 작성자에게 돌려보냅니다.
병합 뒤 CI 처리: 병합 뒤에 돈 테스트가 실패하면, 판단이 필요 없는 실패는 에이전트가 수정 PR을 올리고 그렇지 않은 실패는 원 작성자에게 알립니다.
배포: 병합된 것이 있으면 개발 서버 배포를 실행합니다.

눈에 띄는 선택이 하나 있습니다. 개발용 통합 브랜치에 병합할 때는 CI가 끝나기를 기다리지 않습니다. 리뷰를 통과하면 바로 병합하고, CI는 병합 뒤에 돕니다. 대신 운영 배포로 이어지는 릴리스는 병합 뒤 CI가 초록일 때만 병합할 수 있게 브랜치 보호(특정 브랜치에 병합 조건을 거는 GitHub 설정)로 막아 두었습니다. 빠르게 합치고, 운영으로 나가는 문에서 한 번 거르는 구조입니다.

사고가 만든 규칙들#

에이전트의 규칙 상당수는 사고에서 나왔습니다.

제품 결함만 막는다: 초기에는 테스트가 얕다는 이유로도 PR을 돌려보냈고, 작성자와 에이전트가 같은 PR을 몇 번씩 주고받았습니다. 지금은 실제 오동작이 입증된 결함만 차단하고, 테스트 깊이나 취향은 참고 의견으로 남깁니다. 기준은 첫 리뷰에 모두 제시하고, 이후 라운드에서는 새로 생긴 결함만 막으며, 돌려보내는 라운드는 세 번으로 제한합니다.
하위 에이전트는 읽기 전용: 병합 뒤 CI 실패를 고치는 일을 하위 에이전트에게 맡겼더니, 수정 PR을 만드는 데까지 가 버린 적이 있습니다. 결과물은 멀쩡했지만, 이후로 쓰기 작업은 모두 부모 에이전트만 하도록 바꿨습니다.
미완성 PR은 병합하지 않는다: 본문에 “실행 오류를 수리 중입니다"라고 적힌 PR이 리뷰를 통과해 병합된 적이 있습니다. 작성자는 아직 고치던 중이었고, 통합 브랜치가 빨간불인 채로 릴리스가 반나절 가까이 막혔습니다. 지금은 본문에서 “수리 중” 같은 진행형 표현을 찾으면, 에이전트가 그 PR을 초안 상태로 돌려놓습니다.

정리하면 필자의 에이전트는 리뷰어라기보다 리뷰부터 배포까지 이어지는 파이프라인을 굴리는 운영자에 가깝습니다. 이 점이 뒤의 비교에서 가장 큰 차이가 됩니다.

Claude Code Review는 무엇인가#

아래 내용은 2026년 10월 기준 Anthropic의 블로그 글, 출시 발표, Code Review 공식 문서를 바탕으로 정리했습니다.

Anthropic 팀의 리뷰 방식#

10월 15일 Claude Code 팀의 애디 오스마니(Addy Osmani), 모건 웨스틀리 런트(Morgan Westlee Lunt), 칭 왕(Qing Wang)이 자기 팀의 리뷰 방식을 공개했습니다. Claude Code 저장소는 코드의 약 90%를 Claude가 씁니다. 코드가 그만큼 빨리 나오면 사람이 모든 diff(변경된 부분)를 읽는 방식은 버티지 못합니다. 그래서 이 팀은 질문을 바꿨습니다. “사람이 모든 diff를 읽었는가” 대신 “이 변경에서 무엇이 잘못될 수 있고, 그것을 잡기에 알맞은 것은 사람인가 기계인가"를 묻습니다.

핵심은 위험도별 승인입니다.

위험도	예시	필요한 사람 승인
낮음	문서, 문구, 내부 기능, 기능 플래그 뒤에 추가한 변경	자동 리뷰와 보안 검사가 통과하면 없음
중간	일반 제품 변경, 캐시나 시스템 프롬프트 같은 민감 영역	1명
높음	가장 위험한 코드와 지정된 경로	2명

기능 플래그는 코드를 배포해 두고 기능만 따로 켜고 끌 수 있게 하는 스위치입니다. 문제가 생기면 배포를 되돌리지 않고 스위치만 끄면 되므로 위험이 낮다고 봅니다.

위험도는 작성자가 아니라 변경 내용이 정합니다. 분류기가 변경을 읽고 등급을 매깁니다. 오너가 민감하다고 지정한 경로와 모든 CI 워크플로 파일은 항상 사람이 봅니다. 그리고 에이전트의 승인은 사람 승인 자리를 절대 채우지 못합니다.

리뷰 과정도 여러 겹입니다. PR을 열기 전에 Claude가 테스트와 빌드를 돌려 결과를 보여 주고, 새 컨텍스트의 하위 에이전트가 diff를 리뷰합니다. PR이 열리면 여러 에이전트가 동시에 버그를 찾고, 별도의 에이전트 그룹이 지적 하나하나에 투표해 충분히 동의를 얻은 것만 게시합니다. 스타일만 지적하는 것은 버립니다.

반복되는 지적은 원천에서 고칩니다. 같은 지적이 계속 나오면 리뷰 규칙 파일, 린트 규칙(코드의 실수와 스타일 위반을 자동으로 잡는 검사 규칙), 스킬로 옮깁니다. 리뷰가 끝없이 반복되지 않도록 세 번째 라운드 뒤에는 접근 방식을 다시 생각하라고 요구합니다. 한 PR이 밤새 50번 넘게 리뷰와 수정을 오간 경험에서 나온 규칙입니다.

결과도 공개했습니다. 6월부터 9월 사이 병합된 PR은 두 배 넘게 늘었고, 되돌린 PR의 비율은 40% 넘게 줄었습니다. 이 팀은 되돌림 비율과 장애 비율을 가드레일(넘으면 안 되는 선) 로 둡니다. 이 비율이 오르면 사람의 시간을 아낀 것이 아니라 다른 곳으로 옮긴 것일 뿐이라는 이유입니다.

제품으로서의 Code Review#

같은 날 이 리뷰어의 공개 버전인 Code Review가 정식 출시됐습니다. Claude의 Team과 Enterprise 요금제에서 쓸 수 있습니다.

동작 방식: GitHub App으로 설치하고, 리뷰는 Anthropic 인프라에서 돕니다. 여러 에이전트가 diff와 주변 코드를 동시에 살피고, 검증 단계가 오탐을 걸러 내고, 중복을 없애 심각도 순으로 정리한 뒤 PR에 게시합니다.
결과 표시: 문제가 있는 줄에 댓글을 달고, 심각도를 세 가지로 나눕니다. 병합 전에 고쳐야 할 버그(Important), 사소한 지적(Nit), 그리고 이번 PR이 아니라 원래 있던 문제(Pre-existing) 입니다. 마지막 분류 덕분에 작성자가 남의 버그로 지적받지 않습니다.
할 수 없는 것: 저장소 접근은 읽기 전용이고 커밋을 올리지 않습니다. PR을 승인하지도 차단하지도 않고, 코드를 빌드하거나 실행하지도 않습니다. 병합 결정은 온전히 사람의 몫입니다.
규칙 파일: 저장소의 CLAUDE.md와 REVIEW.md를 읽습니다. REVIEW.md는 PR 쪽이 아니라 기준 브랜치에 있는 것만 읽기 때문에, PR이 자기 리뷰 규칙을 그 자리에서 바꾸지 못합니다.
실행 시점: PR이 열릴 때 한 번, push할 때마다, 댓글로 @claude review를 요청할 때만 중에서 저장소별로 고릅니다.
비용: 리뷰당 정해진 값이 없고 토큰 사용량으로 청구합니다. Anthropic 지원 문서는 리뷰 한 번에 평균 15–25달러라고 안내합니다. 출시 발표에 따르면 리뷰 시간은 프리뷰 때 약 20분에서 대부분 6–10분으로 줄었습니다.

GitHub이 더한 보안 장치#

GitHub은 같은 주에 PR 과정에 보안 장치 여러 개를 더했습니다. 용어가 낯설 수 있어 하나씩 풀어 설명합니다. 가격은 2026년 10월 기준이며, 활성 커미터(코드를 올린 사람) 1인당 월 요금입니다.

Secret Protection: 비밀값이 코드에 섞이는 것을 막습니다#

비밀값은 API 키, 비밀번호, 접속 토큰처럼 남이 알면 안 되는 문자열입니다. Secret Protection(월 19달러)은 두 가지를 합니다. 하나는 push 차단입니다. 누가 실수로 키가 든 파일을 커밋해 올리면 GitHub이 push를 거부합니다. 다른 하나는 이미 과거 커밋에 들어가 있는 키를 찾아 알려 주는 것입니다. 10월 13일부터는 시크릿 검사를 켠 저장소에서 Anthropic API 키도 기본 차단 대상이 됐습니다.

Code Security와 AI Scan: 보안 취약점을 찾습니다#

Code Security(월 30달러)의 중심은 GitHub의 분석 엔진 CodeQL입니다. CodeQL은 코드를 실행하지 않고 데이터가 흘러가는 길을 따라갑니다. 예를 들어 사용자 입력이 검사 없이 SQL 쿼리에 들어가는 경로를 찾으면 PR에 표시합니다. LLM 리뷰와 달리 정해진 규칙으로 판단하므로 같은 코드에는 늘 같은 결과를 냅니다.

10월 15일 정식 출시된 AI Scan은 CodeQL이 아직 다루지 못하는 PHP, Bash, Terraform, Dockerfile 같은 파일을 AI로 검사합니다. 결과는 참고용이라 병합을 막을 수 없게 설계됐습니다. 포크(다른 계정으로 복제한 저장소)에서 온 PR과, 의존성 업데이트 PR을 자동으로 만드는 봇인 Dependabot의 PR에서는 돌지 않습니다. 비공개 저장소에서 쓰려면 Code Security나 Advanced Security가 필요합니다.

에이전트 자동 수정: 고치고, 다시 검사하고, 사람에게 넘깁니다#

같은 날 정식 출시된 에이전트 자동 수정(agentic autofix)은 코드 스캔 경고를 에이전트에게 맡기는 기능입니다. 에이전트가 관련 파일을 살펴 수정안을 만들고, CodeQL을 다시 돌려 경고가 실제로 닫히는지 확인한 뒤 초안 PR을 엽니다. 병합 여부는 사람이 리뷰해서 정합니다. 다만 GitHub Enterprise Cloud 고객 전용이라, Team 요금제를 쓰는 필자 팀은 쓸 수 없습니다.

Actions 잠금 파일: 남이 만든 부품의 바꿔치기를 막습니다#

이 기능은 먼저 설명할 개념이 몇 가지 있습니다.

GitHub Actions는 “PR이 올라오면 테스트, 병합되면 배포” 같은 자동 작업을 정해 두는 기능입니다. 작업 순서는 워크플로 파일에 적습니다. 각 단계는 명령을 직접 실행하거나, 남이 만들어 공개한 부품을 가져다 씁니다. 이 부품을 액션이라고 부릅니다. 저장소 코드를 내려받는 액션, 클라우드에 로그인하는 액션, 배포 명령을 실행하는 액션 같은 것들입니다.

액션을 가져올 때는 보통 uses: actions/checkout@v5처럼 끝에 버전을 붙입니다. 이 @v5가 태그입니다. 태그는 특정 시점의 코드(커밋)에 붙인 이름표인데, 액션을 만든 사람이 언제든 다른 커밋으로 옮겨 붙일 수 있습니다. 반면 커밋에는 40자리 지문(SHA)이 있고, 내용이 한 글자만 달라도 지문이 바뀝니다. 비유하면 태그로 가져오는 것은 “v5판을 보내 주세요"라고 주문하는 것이고, 지문으로 가져오는 것은 “이 인쇄본과 똑같은 것"을 주문하는 것입니다.

이 차이가 실제 사고로 이어진 적이 있습니다. 2025년 3월 14일부터 15일 사이, 2만 3천 개가 넘는 저장소가 쓰던 tj-actions/changed-files라는 액션이 공격당했습니다. 공격자는 v1부터 v45.0.7까지 이 액션의 태그를 모두 악성 커밋으로 옮겨 붙였고, 악성 코드는 CI에 들어 있던 비밀값을 실행 로그에 찍었습니다. 피해 저장소들은 자기 코드를 한 줄도 바꾸지 않았습니다. 태그 대신 지문으로 고정해 둔 저장소만 무사했습니다.

배포용 액션이었다면 더 아찔합니다. 운영 서버 접속 정보를 받아 배포 명령을 실행하는 액션의 태그가 바꿔치기되면, 다음 배포 때 그 접속 정보가 공격자에게 넘어갈 수 있습니다. 이때 저장소에는 아무 변화가 없으니 PR 리뷰로는 사람도 에이전트도 잡을 수 없습니다.

10월 14일 공개 프리뷰로 나온 워크플로 잠금 파일은 각 태그가 어느 커밋을 가리키는지를 .github/workflows/actions.lock 파일에 적어 둡니다. 실행할 때는 태그를 다시 찾지 않고 적어 둔 커밋을 씁니다. 그래서 태그가 옮겨져도 예전 코드를 그대로 쓰고, 버전을 올리려면 잠금 파일을 다시 만들어야 하므로 그 변경이 PR에 드러납니다. Free와 Team 요금제에서도 쓸 수 있습니다. 다만 GitHub도 밝히듯 잠금은 지금 버전을 얼려 둘 뿐, 그 버전이 안전한지는 판단하지 않습니다.

이번에 점검해 보니 필자 팀의 워크플로도 이 문제에서 예외가 아니었습니다.

나란히 놓아 보니#

셋을 같은 자리에 놓으면 차이가 분명해집니다. GitHub의 장치들은 리뷰어라기보다 리뷰 옆에 붙는 검사기라서, 비교의 중심은 Code Review와 필자의 에이전트입니다.

항목	Claude Code Review	필자의 PR 에이전트
하는 일	리뷰	리뷰, 병합, 충돌 해소, 병합 뒤 CI 수정, 배포 실행
병합 결정	사람	리뷰를 통과하면 에이전트
지적 검증	별도 검증 단계	없음
보는 범위	PR이 속한 저장소	사본을 가진 여러 저장소
실행 신원	별도 GitHub App	필자의 GitHub 계정
규칙의 위치	저장소의 규칙 파일	서버의 하네스
비용	리뷰당 평균 15–25달러	서버 한 대와 기존 모델 구독
고칠 수 있는 범위	리뷰 수준과 규칙 파일	하네스 전체

필자가 Code Review로 갈아타지 않기로 한 이유는 첫 두 줄에 있습니다. Code Review를 들여도 병합, 충돌 해소, 배포는 여전히 누군가 해야 합니다. 리뷰만 넘기면 필자의 에이전트는 남은 일을 위해 그대로 있어야 하고, 리뷰 판단과 병합 판단이 두 시스템으로 갈라집니다.

비용도 무시할 수 없습니다. PR이 한 달에 수백 건 열리는 팀이라면 PR마다 한 번씩만 돌려도 월 수천 달러가 됩니다. push마다 돌리면 그 몇 배입니다. Anthropic이 Enterprise 조직에 주는 1만 달러 크레딧도 Team 요금제에는 해당하지 않습니다.

그렇다고 필자의 에이전트가 모든 면에서 앞서지는 않습니다. 표에서 제품이 앞서는 줄도 분명히 있습니다.

지적을 한 번 더 검증합니다. 필자의 에이전트는 하위 에이전트 한 명이 “결함"이라고 하면 그대로 PR을 막습니다.
에이전트와 사람이 구분됩니다. 필자의 에이전트는 필자의 계정으로 일해서, GitHub 기록만으로는 누가 한 일인지 가릴 수 없습니다.
규칙 기반 검사와 공급망 보호가 있습니다. CodeQL과 잠금 파일은 LLM 리뷰가 구조적으로 못 하는 일을 합니다. 앞의 태그 바꿔치기처럼 저장소에 아무 변화가 없는 공격은 어떤 리뷰어도 잡지 못합니다.

반대로 필자의 에이전트가 앞선다고 생각한 줄에도 단서가 붙었습니다. 이 이야기는 뒤에서 다시 합니다.

그래서 결론은 “버리지 않는다"에서 끝나지 않았습니다. 제품이 앞서는 점을 필자의 하네스로 가져오는 작업이 남았습니다. 그런데 막상 가져오려 하니, 그대로 옮길 수 없는 것들이 먼저 보였습니다.

그대로 가져오지 않은 것들#

사람이 항상 보는 경로#

Anthropic 팀은 CI 워크플로 파일을 항상 사람이 봅니다. 처음에는 필자도 이 원칙을 그대로 가져오려 했습니다. 워크플로 파일은 운영 배포 키를 다루고, 병합 뒤 CI처럼 안전장치 그 자체이기도 합니다. 실수든 공격이든 이 파일이 잘못되면 피해가 가장 큽니다. 그래서 워크플로를 바꾼 PR은 에이전트가 리뷰만 하고, 필자가 확인한 뒤 병합하는 방안을 생각했습니다.

그런데 이 방안은 에이전트를 만든 이유와 정면으로 부딪힙니다. 필자의 에이전트는 사람의 병목을 줄이려고 만든 것이고, 사람 확인 단계를 넣으면 필자가 다시 병목이 됩니다. 필자가 보기에 Anthropic의 원칙은 사람 리뷰어가 여럿 있는 팀을 전제로 합니다. 필자의 환경에서 같은 목적을 이루는 방법은 사람을 다시 불러오는 것이 아니라 리뷰를 더 두껍게 하는 것이었습니다. 구체적인 방법은 다음 절에서 설명합니다.

리뷰 규칙을 저장소에 공개하는 것#

Code Review는 리뷰 규칙을 저장소 안의 REVIEW.md에 둡니다. 저장소 담당자가 규칙을 직접 고칠 수 있고, 다른 도구와 같은 파일을 함께 쓸 수 있다는 장점이 있습니다. 필자도 처음에는 에이전트의 저장소별 규칙을 각 저장소로 옮기려 했습니다.

따져 보니 단점이 더 컸습니다.

규칙을 누구나 바꿀 수 있습니다. 기준 브랜치의 규칙만 읽게 하면 PR이 자기 규칙을 그 자리에서 바꾸지는 못합니다. 하지만 규칙만 느슨하게 고치는 PR을 따로 올리면, 그 PR도 에이전트가 리뷰하고 병합합니다. 사람이 보지 않는 구조에서는 규칙 약화가 에이전트 리뷰만으로 통과될 수 있습니다.
형식 규칙은 피하기 쉬워집니다. “PR 본문에 적용 계획을 적는다” 같은 규칙은 공개되면 내용 없이 형식만 맞추기 쉽습니다. 반면 “제품 결함이면 막는다” 같은 판단 규칙은 공개되어도 피할 수 없습니다. 결함은 결함이기 때문입니다.
장점이 작습니다. 필자가 하네스를 직접 운영하는 지금 구조에서는 “담당자가 규칙을 고칠 수 있다"는 장점이 크지 않습니다.

그래서 리뷰 규칙은 서버의 하네스에 두되, 저장소별 파일로 나눠 해당 저장소 PR을 리뷰할 때만 읽게 하기로 했습니다. 대신 Anthropic의 다른 아이디어를 함께 씁니다. 에이전트가 자주 돌려보내는 이유를 저장소의 작성 가이드(CLAUDE.md, AGENTS.md)에 “이렇게 써야 한다"로 옮기는 것입니다. PR을 쓰는 AI가 그 파일을 읽으니 처음부터 맞게 작성되고, 공개되는 것은 작성 기준뿐입니다.

제품 자체#

Code Review는 앞에서 말한 이유로 들이지 않습니다. 위험한 PR에만 두 번째 의견으로 불러 쓰는 방법도 생각했지만, 아래의 개선을 먼저 적용해 보고 그래도 부족하면 시범 운영하기로 했습니다.

GitHub의 장치 중 Code Security는 보류했습니다. AI Scan 결과는 병합을 막지 못하는 참고용이고, 필자 팀에는 비밀값 검사와 액션 고정이 더 급했습니다. 에이전트 자동 수정은 요금제 때문에 쓸 수 없습니다.

가져와서 바꾼 것들: 개선 계획#

아래는 아직 적용하기 전의 계획입니다.

1. 위험한 파일은 더 두껍게 리뷰하고, 병합 알림에 이유를 남긴다#

Anthropic이 고위험 변경에 사람 두 명의 승인을 요구하는 것을 기계 검사, 두 번의 에이전트 리뷰, 병합 뒤 감시로 바꿉니다.

위험한 파일을 정의합니다. 시작은 CI 워크플로 파일, DB 스키마 변경 파일, 인증과 권한 코드입니다.
기계 검사를 먼저 돌립니다. LLM이 아니라 정해진 규칙으로 동작하는 스크립트가 diff를 훑습니다. 새 외부 액션이 지문이 아니라 태그로 들어왔는지, 비밀값을 새로 쓰는지, 권한이 넓어졌는지, 배포 트리거가 바뀌었는지, 필수 검사에 “실패해도 통과"가 붙었는지를 봅니다. 스크립트는 같은 입력에 늘 같은 결과를 내고, PR 본문에 숨긴 지시문에 속지 않습니다.
위험 파일만 따로 한 번 더 리뷰합니다. 새 하위 에이전트가 위험 파일 부분만 다시 보고, 기계 검사가 찾은 신호마다 “왜 필요한가"를 PR 본문과 diff로 설명할 수 있어야 통과시킵니다. 두 리뷰가 모두 통과해야 병합합니다. 설명이 안 되면 필자가 아니라 작성자에게 돌려보냅니다.
병합 뒤 첫 실행을 지켜봅니다. 워크플로 변경이 병합되면 그 워크플로의 다음 실행을 확인하고, 실패하거나 테스트가 0건만 돌았으면 알립니다.

그리고 병합 알림에 판단 근거를 남깁니다. 필자는 사전에 확인하지 않고, 사후에 읽어 보고 이상하면 되돌립니다.

✅ [백엔드] #1234 "배포 워크플로에 빌드 캐시 추가" 병합됨
⚠️ 위험 파일 1개: 운영 배포 워크플로
- 바뀐 것: 이미지 빌드 단계에 캐시 액션 추가
- 기계 검사: 새 외부 액션 1개, 커밋 지문으로 고정됨. 비밀값 / 권한 / 트리거 변화 없음
- 2차 리뷰: 통과. 캐시 키가 브랜치별로 나뉘어 다른 브랜치 결과가 섞이지 않음
- 병합 뒤 첫 실행: 다음 회차에 확인

2. PR을 막는 지적은 한 번 더 검증한다#

Code Review의 검증 단계를 가져옵니다. 하위 에이전트가 차단 지적을 내면, 새 하위 에이전트에게 그 지적 하나만 코드로 확인시킵니다. 실제 코드 위치를 근거로 대지 못하는 지적은 차단에서 참고 의견으로 내립니다. 차단 지적이 나왔을 때만 돌기 때문에 비용은 조금만 늘고, 오탐 때문에 작성자가 반론을 달고 다음 회차를 기다리는 일이 줄어듭니다.

3. 다른 저장소에 미치는 영향을 실제로 확인한다#

비교표에서 필자는 에이전트가 “여러 저장소를 본다"고 적었습니다. Code Review는 PR이 속한 저장소만 보니, 이 점은 필자 쪽의 확실한 장점이라고 생각했습니다. 예를 들어 백엔드 PR이 API 응답 모양을 바꾸면, 프론트엔드에서 그 API를 쓰는 곳이 깨지는지 함께 볼 수 있다는 것입니다.

서버를 확인해 보니 반만 맞았습니다. 에이전트는 모든 저장소에 접근할 권한이 있지만, 검색에 쓰는 로컬 사본은 저장소를 두 그룹으로 나누면서 각자 맡은 그룹 것만 갖게 되어 있었습니다. 리뷰를 맡는 하위 에이전트는 새 사본을 만들 수 없게 막혀 있었고, 리뷰 지침에도 다른 저장소를 확인하라는 말이 없었습니다. 가능성은 있었지만 실제로는 쓰이지 않던 장점이었습니다.

그래서 양쪽 에이전트에 나머지 저장소의 사본을 두고, 리뷰 전에 최신으로 갱신하고, 리뷰 지침에 “API나 데이터 형식을 바꾸는 PR은 그것을 쓰는 다른 저장소를 찾아 확인한다"는 규칙을 넣습니다. PR이 속한 저장소만 보는 Code Review로는 할 수 없는 일이라, 제대로 쓰면 필자 쪽의 분명한 강점이 됩니다.

4. 원래 있던 버그는 따로 등록한다#

Code Review는 원래 있던 문제를 따로 표시합니다. 필자의 에이전트도 이미 “이번 PR의 결함만 막는다"는 원칙이 있어서, 기존 버그 때문에 PR을 막는 일은 거의 없습니다. 에이전트가 바뀐 부분 위주로 보니 기존 버그를 발견하는 일 자체도 드뭅니다.

빈틈은 발견한 다음입니다. 지금은 리뷰 댓글에 “후속 과제” 한 줄로 남고, 아무도 챙기지 않습니다. 발견한 버그는 고치는 것이 맞지만, 이번 PR에 섞어 고치게 하면 작성자가 모르는 코드를 건드리게 되고 PR이 커져서 리뷰와 되돌리기가 어려워집니다. 그래서 기존 버그는 PR을 막지 않되, 원 작성자에게 알리거나 작업 목록에 등록해 따로 고치게 합니다. 이번 PR 때문에 그 버그가 새로 실행되거나 더 나빠지는 경우만 이번 PR의 결함으로 보고 막습니다.

5. 되돌린 PR의 비율을 잰다#

필자는 병합 대기 시간, 통합 브랜치가 빨간불이던 시간, 충돌 해소 건수를 지표로 보고 있습니다. 모두 흐름이 얼마나 막힘없이 돌아가는지를 재는 지표입니다. Anthropic이 속도를 올리면서 함께 본 것은 되돌림 비율이었습니다. CI를 기다리지 않고 병합하는 방식이 안전한지 판단하려면 이 비율이 필요합니다.

6. 에이전트 밖에서 할 일: 액션 고정과 비밀값 검사#

리뷰로는 잡을 수 없는 위험도 있습니다. 하나는 앞에서 본 태그 바꿔치기입니다. 외부 액션을 커밋 지문으로 고정하고, 잠금 파일은 한 저장소에서 먼저 시험합니다. 고정한 버전을 올리는 PR은 1번의 위험 파일 리뷰를 거칩니다.

다른 하나는 비밀값입니다. 필자 팀은 통합 브랜치의 CI를 병합 뒤로 옮겼기 때문에, 키가 섞인 커밋이 통합 브랜치에 먼저 들어가고 나서야 잡힐 수 있습니다. 한 번 들어간 키는 커밋 이력에 남으므로 폐기하고 새로 발급해야 합니다. 그래서 Secret Protection으로 push 단계에서 막거나, 적어도 병합 전에 에이전트가 PR 변경분을 비밀값 탐지 도구로 검사하게 합니다.

맺으며#

정리하면, 필자는 Claude Code Review를 들이지 않고 그 설계를 가져오기로 했습니다. 제품이 나빠서가 아니라 필자에게 필요한 일의 범위가 달라서입니다. Code Review는 사람이 병합을 결정하는 팀에 붙는 리뷰어이고, 필자의 에이전트는 사람이 빠진 자리에서 병합까지 굴리는 운영자입니다.

이 결론에는 조건이 붙습니다. 병합 자동화가 목적이고, 하네스를 직접 고칠 수 있고, 사람 리뷰어가 많지 않은 팀이라는 조건입니다. 리뷰만 자동화하면 되는 팀, 감사 때문에 에이전트와 사람을 기록상 분명히 나눠야 하는 팀, 하네스를 운영할 사람이 없는 팀이라면 Code Review가 더 나은 선택일 수 있습니다.

이번 검토에서 얻은 것은 제품 소개서를 설계 문서로 읽는 습관입니다. 같은 문제를 먼저 푼 팀의 제품에는 그 팀이 사고를 겪으며 얻은 답이 들어 있습니다. 지적을 투표로 거르는 단계, 원래 있던 문제를 따로 표시하는 분류, 라운드 상한, 되돌림 비율이라는 가드레일이 그렇습니다. 다만 그 답은 그 팀의 전제 위에 서 있습니다. 사람이 항상 보는 경로처럼 전제가 다르면, 같은 목적을 이루는 다른 모양을 찾아야 했습니다.

지난번 직접 조립한 에이전트 환경과 OpenAI의 완제품에서도 비슷한 결론에 닿았습니다. 완제품이 늘어날수록 직접 만드는 이유는 “그것밖에 방법이 없어서"에서 “필요한 대로 고칠 수 있어서"로 옮겨 갑니다. 위의 개선을 적용하고 나면 그 효과를 되돌림 비율과 함께 다시 정리해 보겠습니다.