Orchestrating AI code review at scale

TL;DR Highlight

Cloudflare가 수만 건의 머지 리퀘스트에 AI 코드 리뷰를 적용하면서 겪은 설계 결정과 아키텍처를 공개했다. 단순한 LLM 호출이 아닌 7개의 전문 에이전트를 코디네이터가 관리하는 구조로 노이즈를 줄이고 실제 버그를 잡아내는 방식이 핵심이다.

Who Should Read

CI/CD 파이프라인에 AI 코드 리뷰를 도입하려는 DevOps 또는 백엔드 개발자. 특히 여러 팀과 리포지토리에 걸쳐 일관된 코드 품질 기준을 적용해야 하는 엔지니어링 매니저나 플랫폼 팀.

Core Mechanics

처음에는 시중의 AI 코드 리뷰 툴을 써봤는데, 기능 자체는 괜찮았지만 Cloudflare 규모의 조직에서 요구하는 세밀한 커스터마이징이 불가능했다. 그래서 직접 만들기로 결정했다.
가장 단순한 접근법인 'git diff를 통째로 프롬프트에 때려넣기'를 시도했는데 결과가 처참했다. 이미 에러 처리가 있는 함수에 '에러 처리를 추가하라'는 조언이 달리는 등, 노이즈가 너무 많아 실용적이지 않았다.
최종 아키텍처는 오픈소스 코딩 에이전트인 OpenCode를 기반으로, CI 네이티브 오케스트레이션 시스템을 그 위에 얹는 방식이다. 모놀리식 에이전트 대신 역할이 분리된 다수의 전문 에이전트를 조율하는 구조를 선택했다.
머지 리퀘스트가 열리면 보안, 성능, 코드 품질, 문서화, 릴리즈 관리, 내부 Engineering Codex 준수 여부 등을 담당하는 최대 7개의 전문 리뷰어 에이전트가 동시에 실행된다.
7개 에이전트의 결과를 코디네이터 에이전트가 취합해서 중복을 제거하고, 각 이슈의 실제 심각도를 판단한 뒤 구조화된 단일 리뷰 코멘트로 합쳐서 올린다. 코디네이터에는 가장 강력한 모델(Claude Opus 등)을 쓰고 하위 리뷰어엔 상대적으로 가벼운 모델을 쓴다.
컴포저블 플러그인 아키텍처를 채택해서 VCS 프로바이더(현재 GitLab), AI 프로바이더, 내부 정책 등이 서로를 모르는 채로 조합될 수 있게 했다. 덕분에 특정 VCS에 종속되지 않는다.
공유 컨텍스트 파일(shared-mr-context.txt) 전략을 써서 토큰 비용을 줄였다. MR 전체 컨텍스트를 7개 에이전트 프롬프트에 각각 복사하는 대신, 디스크에 한 번 쓰고 각 서브 리뷰어가 읽어가게 했다.
10줄 미만의 사소한 변경(오타 수정, 문서 수정 등)은 리뷰당 평균 20센트 수준이었고, 이런 trivial 리뷰가 전체의 약 20%(약 25,000건)를 차지했다. 시스템은 이미 수만 건의 머지 리퀘스트에 실제로 적용 중이며, 심각한 버그나 보안 취약점 발견 시 머지를 직접 블로킹한다.
LLM을 CI 크리티컬 패스에 넣었을 때 예상치 못한 문제가 있었는데, 고급 모델(Claude Opus, GPT-5 등)이 생각하는 데 오래 걸려서 사용자에게 '작업이 멈춘 것처럼' 보이는 현상이다. 이를 해결하기 위한 진행 상황 스트리밍이 필요했다.

Evidence

코드 리뷰의 '지식 공유' 기능 손실에 대한 비판이 있었다. trivial한 PR(10줄 미만)을 AI가 20센트에 리뷰하는 게 과연 효율적이냐는 지적도 나왔는데, 이런 PR을 주니어 개발자가 30~60초 보는 비용도 비슷하고, 그 과정에서 사람은 경험을 쌓는다는 반론이었다.
블로그 포스트의 일부 기술적 주장에 불일치가 있다는 지적이 있었다. '서브 리뷰어 프롬프트에 MR 컨텍스트를 복사하면 토큰 비용이 7배 된다'는 설명이 틀렸다는 것인데, 공유 컨텍스트 파일 자체도 토큰을 소비하고 서브 에이전트 프롬프트가 컨텍스트 100%는 아니기 때문이다. 또한 'Opus는 코디네이터에만 쓴다'고 앞서 설명했는데 뒤에서 '7개 에이전트가 Opus급 토큰을 태운다'는 식으로 쓰는 등 내부 일관성 문제도 지적됐다.
PR 리뷰가 실제 병목이 아니라는 의견도 있었다. 진짜 병목은 리뷰 전에 개발자가 스스로 코드를 정리하거나 자기 리뷰를 하는 과정이고, AI 리뷰는 PR을 올리기 전 pre-commit 훅이나 pre-push 훅으로 돌리는 게 더 피드백 루프가 빠를 것이라는 의견도 나왔다.
비슷한 시스템을 직접 구축해본 사람들의 경험이 공유됐다. 한 댓글러는 codex exec + Git worktrees 조합으로 비슷한 걸 만들었는데, diff만 보는 것보다 전체 코드베이스를 탐색해 의존성과 아키텍처 영향을 파악할 수 있어서 좋지만 비용이 더 든다고 했다. 또 다른 사람은 GitHub Actions + Copilot으로 간단하게 만들었는데 팀 반응이 좋고 ROI가 높아서 강력한 모델을 쓰는 비용을 아끼지 않는다고 했다.
PySpark처럼 프레임워크 특화 코드에 AI 리뷰를 적용하면 그 프레임워크의 관용적 패턴을 일반 Python 관행으로 지적하는 노이즈가 많이 생긴다는 실사용 불만도 있었다. 도메인 특화 컨텍스트를 어떻게 주입하느냐가 실용성을 가르는 핵심 문제라는 공감대가 형성됐다.

How to Apply

단일 LLM 호출로 전체 diff를 리뷰하는 방식이 너무 노이즈가 많다면, Cloudflare처럼 보안/성능/품질 등 역할을 분리한 전문 에이전트를 각각 만들고, 코디네이터 에이전트가 결과를 합쳐서 최종 코멘트를 올리는 구조를 시도해볼 수 있다. 이렇게 하면 각 에이전트의 시스템 프롬프트가 짧고 집중적으로 유지돼 노이즈가 줄어든다.
7개 에이전트에 동일한 MR 컨텍스트를 각각 넣으면 토큰 비용이 선형으로 늘어나므로, 공유 컨텍스트를 파일로 디스크에 써두고 각 에이전트가 읽어가는 방식으로 중복 토큰을 줄일 수 있다. 특히 MR 컨텍스트가 큰 대형 리포지토리에서 비용 절감 효과가 크다.
CI 파이프라인에서 고급 모델(GPT-4o, Claude Opus 등)이 오래 생각하는 동안 사용자가 '작업이 멈췄다'고 착각하는 UX 문제가 생길 수 있다. 에이전트 실행 중 진행 상황을 JSONL 스트리밍으로 실시간 노출하거나, 각 도구 호출마다 'purpose' 메시지를 출력해 사용자가 진행 중임을 인지하게 하면 이 문제를 완화할 수 있다.
trivial한 변경(오타, 문서 수정 등)에 7개 에이전트를 전부 돌리는 건 비용 낭비다. diff 크기나 변경된 파일 타입을 기준으로 리뷰 강도를 조절하는 로직을 앞단에 두면, 10줄 미만 변경은 가벼운 단일 에이전트만 쓰고 복잡한 변경에만 풀 파이프라인을 실행하도록 해 비용을 최적화할 수 있다.

Terminology

머지 리퀘스트(MR)개발자가 자신이 작성한 코드를 메인 브랜치에 합쳐달라고 요청하는 것. GitHub에서는 Pull Request(PR)라고 부른다.

오케스트레이션여러 에이전트나 서비스가 협력해 하나의 작업을 완료하도록 실행 순서와 데이터 흐름을 관리하는 것. 악단의 지휘자 역할과 비슷하다.

코디네이터 에이전트여러 전문 에이전트의 결과를 수집해 중복을 제거하고 심각도를 판단해 최종 결과물을 만드는 상위 에이전트.

CI/CD 파이프라인코드를 커밋하면 자동으로 빌드, 테스트, 배포까지 이어지는 자동화 흐름. Cloudflare는 이 흐름에 AI 리뷰를 끼워 넣었다.

컴포저블 플러그인 아키텍처각 기능(VCS 연동, AI 프로바이더 설정 등)을 독립적인 플러그인으로 분리해서 레고처럼 조합할 수 있게 만든 설계 방식. 특정 컴포넌트를 바꿔도 나머지에 영향이 없다.

Engineering Codex조직 내부에서 코드 작성 방식, 아키텍처 원칙, 보안 규칙 등을 정리한 내부 가이드라인 문서.