여러 AI 리뷰어가 같은 변경을 봤다고 머지 안전성이 자동으로 높아지지는 않는다. 같은 전제를 공유하면 같은 결함을 놓치고, 역할만 나눈 채 검증하지 않으면 비슷한 경고가 쌓인다. 멀티 에이전트 리뷰의 목표는 지적 수가 아니라 실제로 재현되고 수정할 가치가 있는 결함의 비율을 높이는 것이다.
Claude Code의 관리형 Code Review도 여러 에이전트가 후보를 찾은 뒤 실제 코드 동작을 확인하고, 중복 제거와 심각도 분류를 거쳐 결과를 낸다. 2026-07-29 현재 이 기능은 Team·Enterprise용 연구 프리뷰이며 Zero Data Retention 조직에서는 쓸 수 없다. 제공 범위는 Code Review 공식 문서에서 확인한다.
1. 리뷰할 변경과 제외할 문제를 고정한다
리뷰 입력은 현재 PR의 기준 커밋, 머리 커밋, diff, 관련 인터페이스와 테스트다. “저장소를 전부 검토하라”가 아니라 이번 변경이 새로 만든 정확성·보안·데이터 손상·동시성 위험을 찾게 한다. 기존 결함과 스타일 취향은 별도 등급으로 보내 머지 차단 신호와 섞지 않는다.
리뷰 규칙에는 금지 영역, 중요 경로, 허용된 도구, 테스트 명령을 적는다. Claude Code Review에서는 공통 프로젝트 맥락은 CLAUDE.md, 리뷰 전용 심각도와 보고 규칙은 루트의 REVIEW.md에 둔다. REVIEW.md는 모든 리뷰 에이전트에 최우선으로 그대로 들어간다. @ 가져오기와 참조 파일은 펼쳐지지 않으므로 실행할 규칙을 본문에 직접 쓴다.
2. 탐색자와 검증자의 성공 기준을 나눈다
탐색 에이전트는 인증, 예외 처리, 데이터 흐름, 경합, 테스트 누락처럼 서로 다른 위험을 넓게 찾는다. 이 단계의 결과는 결함이 아니라 후보 목록이다. 검증 에이전트는 각 후보의 호출 경로를 추적하고 재현 입력이나 실패 테스트를 만든다. 근거가 확인되지 않으면 머지 차단 목록에서 내린다.
Claude Code의 표준 명령 /code-review ultra는 여러 에이전트가 병렬 탐색하고 지적을 독립 재현·검증하는 원격 리뷰다. 제공 계정에서 /ultrareview는 별칭이다. 지원되지 않는 환경에서는 로컬 리뷰로 돌아가므로 LOCAL_FALLBACK으로 기록하고 원격 검증 완료로 세지 않는다. 실행 조건은 Ultrareview 공식 안내로 확인한다.
3. 지적 하나를 재현 가능한 보고서로 만든다
모든 결과는 같은 형식으로 반환한다.
- 파일과 줄, 관련 호출 경로.
- 기준·머리 SHA, 실행 모드·범위·상태.
- PR이 새로 만든 문제인지 여부.
- 발생 조건과 최소 재현 절차.
- 사용자·데이터·보안에 미치는 영향.
- 심각도, 검증 여부, 근거 테스트와 수정 후 확인 방법.
“위험해 보인다”는 차단 사유가 아니다. 재현이 어렵다면 불확실성과 필요한 추가 증거를 적어 사람 검토 목록으로 보낸다. 수정 뒤에는 같은 테스트를 다시 실행하고, 새 커밋에서 지적이 사라졌는지 확인한다.
4. AI 리뷰와 실제 머지 관문을 분리한다
Claude Code Review의 check run은 항상 neutral로 끝나며 자체적으로 PR을 승인하거나 막지 않는다. 별도 CI는 정상 완료와 검토 SHA를 확인한 뒤 check run의 bughunter-severity JSON을 읽는다. normal은 Important 건수이므로 1 이상이면 차단한다. 오류·시간 초과·건너뜀·payload 없음·이전 SHA는 NOT_RUN으로 재실행한다.
AI 결과와 별도로 필수 테스트와 사람 승인을 유지한다. GitHub 보호 규칙에서는 상태 검사 통과, 오래된 승인 해제, 최신 검토 가능 푸시에 대한 승인을 설정할 수 있다. 기준은 GitHub 보호 브랜치 공식 안내에서 확인한다.
5. 발견 수보다 정밀도와 누락을 기록한다
매주 확인된 결함, 잘못된 경고, 사람이 추가로 찾은 누락, 리뷰 대기 시간과 비용을 역할별로 집계한다. 틀린 경고가 많은 역할은 프롬프트와 범위를 좁히고, 반복해서 놓친 문제는 새 탐색 관점이나 결정적 검사로 옮긴다.
좋은 멀티 에이전트 리뷰는 승인 도장을 여러 번 찍는 시스템이 아니다. 후보를 넓게 찾고 독립적으로 재현한 뒤, 사람과 CI가 이해할 수 있는 근거만 머지 판단에 남기는 필터다.