Orchestrating AI code review at scale

개요

Cloudflare는 대규모 AI 기반 코드 검토 시스템을 구축하여 엔지니어링 팀의 병목 현상을 줄이고 코드 품질을 향상시켰습니다. 이 시스템은 단일 LLM 대신 여러 전문 AI 에이전트를 조정하는 CI 네이티브 오케스트레이션 시스템을 기반으로 합니다.

주요 내용

• 기존 코드 검토의 문제점: 수동 코드 검토는 버그를 잡고 지식을 공유하는 데 유용하지만, 엔지니어링 팀의 병목 현상을 야기하며, 검토 대기 시간이 길어지는 경향이 있습니다.
• AI 코드 검토 도구의 한계: 초기 AI 코드 검토 도구들은 유연성과 맞춤 설정 기능이 부족하여 대규모 조직에 적용하기 어려웠습니다.
• 단순 LLM 접근 방식의 비효율성: Git diff를 LLM에 직접 전달하는 방식은 모호한 제안, 잘못된 구문 오류 등을 야기하여 복잡한 코드베이스에서 원하는 결과를 얻기 어려웠습니다.
• OpenCode 기반의 오케스트레이션 시스템: monolithic 코드 검토 에이전트 대신, CI 네이티브 오케스트레이션 시스템을 OpenCode라는 오픈 소스 코딩 에이전트 위에 구축했습니다.
• 전문 에이전트 활용: 보안, 성능, 코드 품질, 문서화, 릴리스 관리, 내부 엔지니어링 규약 준수 등 최대 7개의 전문 AI 에이전트가 코드를 검토합니다.
• 코디네이터 에이전트: 여러 에이전트의 결과물을 취합하고, 중복을 제거하며, 이슈의 실제 심각도를 판단하여 단일 구조화된 검토 코멘트를 생성합니다.
• 플러그인 기반 아키텍처: 버전 관리 시스템(GitLab 등) 및 AI 제공업체에 대한 종속성을 제거하기 위해 구성 가능한 플러그인 아키텍처를 사용했습니다. 각 플러그인은 Bootstrap, Configure, PostConfigure 생명주기 단계를 따릅니다.
• OpenCode 사용 이유: 광범위한 내부 사용 경험, 오픈 소스 기반의 기여 및 조사 용이성, 프로그램 방식으로 세션을 생성하고 결과를 수집할 수 있는 서버 우선 구조가 장점입니다.
• JSONL (JSON Lines) 활용: 장기 실행 프로세스의 구조화된 로깅을 위해 각 줄이 유효한 JSON 객체인 JSONL 형식을 사용합니다.
• 스트리밍 파이프라인: 코디네이터의 출력을 실시간으로 처리하며, 토큰 사용량 추적, 오류 이벤트 감지, 출력 잘림 방지 기능을 포함합니다.
• 작업 중단 시간 최소화: 모델이 생각하는 동안 사용자에게 작업이 멈춘 것처럼 보이지 않도록 "Thinking..." 상태 로그를 주기적으로 출력합니다.
• 전문 에이전트별 프롬프트 엔지니어링: 각 에이전트는 특정 작업에 집중하도록 명확하게 정의된 프롬프트를 가지며, 무엇을 플래그할지, 무엇을 무시할지에 대한 지침이 포함됩니다.
• 에이전트별 결과 분류: 생성된 결과는 Critical, Warning, Suggestion으로 심각도를 분류하여 구조화된 데이터로 관리합니다.
• 모델 계층화: 작업 복잡성에 따라 모델을 다르게 할당합니다 (예: 최고 티어 모델은 코디네이터에 사용).
• 프롬프트 주입 방지: 사용자 제어 콘텐츠를 소독하고 경계 태그를 제거하여 LLM 프롬프트 주입 공격을 방지합니다.
• 토큰 절약: 전체 diff 대신 파일별 패치 파일을 사용하고, 공유 컨텍스트 파일을 추출하여 코디네이터 프롬프트 중복을 줄입니다.
• 코디네이터의 역할: 에이전트 결과 통합, 중복 제거, 재분류, 합리성 필터링, 최종 승인 결정 등을 수행합니다.
• 위험 등급별 에이전트 구성: 코드 변경의 크기와 종류에 따라 사용되는 에이전트 수를 조정하여 비용 효율성을 높입니다 (Trivial, Lite, Full).
• 노이즈 필터링: lock 파일, 번들링된 종속성, 축소된 에셋 등 불필요한 변경 사항을 사전에 필터링합니다.
• 동시 오케스트레이션: spawn_reviewers 도구를 사용하여 여러 에이전트 세션을 관리하며, 서킷 브레이커, 타임아웃, 재시도 로직을 구현합니다.
• 내결함성: 모델 제공업체 장애 시 서킷 브레이커 패턴과 실패 복구 체인을 사용하여 다른 모델로 대체합니다.
• 에러 분류 및 실패 복구: 에러 유형에 따라 모델 대체(failback) 여부를 결정합니다.
• 컨트롤 플레인: Cloudflare Worker를 통해 모델 라우팅 구성을 동적으로 관리하고, 원격으로 공급업체를 비활성화하거나 실패 복구 체인을 수정할 수 있습니다.
• 증분 재검토: 이전 검토 결과를 인지하고 변경된 부분만 다시 검토하여 효율성을 높입니다.
• AGENTS.md 검토: AI 에이전트가 프로젝트 규칙을 이해하는 데 사용되는 AGENTS.md 파일의 최신성을 검증하고, 주요 변경 시 업데이트를 강제합니다.
• 팀 사용 방식: GitLab CI 컴포넌트로 제공되어 쉽게 통합할 수 있으며, 로컬에서도 실행 가능합니다.
• 데이터 및 성능: 131,246건의 검토 실행, 평균 3분 39초의 검토 시간, 평균 $1.19의 비용으로 시스템이 운영되고 있습니다.
• 발견된 이슈: 코드 품질 검토자로부터 가장 많은 결과가 나왔으며, 보안 및 성능 검토자는 더 높은 심각도의 이슈를 발견하는 경향이 있습니다.
• 토큰 사용: 85.7%의 캐시 히트율을 통해 재검토 시 토큰 사용량을 크게 절감합니다.

시사점

Cloudflare의 AI 코드 검토 시스템은 LLM을 CI/CD 파이프라인의 핵심 경로에 통합하는 복잡한 엔지니어링 과제를 해결했습니다. 이는 대규모로 AI 코드 검토를 효과적으로 수행하기 위한 아키텍처, 에이전트 오케스트레이션, 비용 관리 및 내결함성 전략에 대한 실제적인 인사이트를 제공합니다.