목차
Cloudflare의 AI 코드 리뷰를 조율하는 OpenCode (2026-04)
원문 정보
- 원문: Orchestrating AI Code Review at scale
- 매체 · 게시일: The Cloudflare Blog · 2026-04-20
- 저자: Ryan Skidmore
- 원문 내용을 바탕으로 재구성한 요약입니다.
몇 시간씩 기다리던 첫 리뷰
코드 리뷰는 버그를 잡고 지식을 나누는 자리입니다. 하지만 MR(merge request)이 대기열에 머물다 검토를 받고, 변수 이름을 고치라는 댓글에 작성자가 답하고, 다시 검토를 기다리는 과정은 개발팀의 병목이 되기도 합니다. Cloudflare 내부 프로젝트에서 첫 리뷰 대기 시간의 중앙값은 종종 시간 단위였습니다.
처음에는 기존 AI 리뷰 도구를 시험했습니다. 제법 잘 작동했고 맞춤 설정도 제공했지만, Cloudflare 규모의 조직이 요구하는 유연성에는 못 미쳤습니다. 다음 시도는 급히 만든 프롬프트에 git diff를 넣고 버그를 찾아 달라고 하는 방식이었습니다. 결과는 시끄러웠습니다. 모호한 제안과 존재하지 않는 문법 오류가 쏟아졌고, 이미 오류 처리가 있는 함수에 오류 처리를 추가하라는 조언까지 나왔습니다.
Cloudflare는 OpenCode를 중심으로 CI 오케스트레이션 시스템을 만들었습니다. 최대 일곱 전문 리뷰어가 각자의 영역을 조사하고, 조율 에이전트인 coordinator가 지적을 검증해 하나의 리뷰 댓글로 모읍니다. 실제로 심각한 문제나 보안 취약점을 찾으면 병합도 차단합니다. Code Orange: Fail Small 활동의 일부인 이 시스템은 리뷰를 빨리 시작하는 데서 그치지 않고, 개발자가 받아들일 만한 지적을 남기는 데 초점을 뒀습니다.
전문 리뷰어의 지적을 다시 심사하는 coordinator
리뷰어마다 찾아야 할 문제와 무시해야 할 문제를 구체적으로 정합니다. 보안 리뷰어의 기준은 악용 가능하거나 구체적으로 위험한 문제입니다. 희박한 전제가 필요한 이론적 위험, 충분한 방어가 있는 코드에 방어를 더하라는 제안, 이번 MR이 영향을 주지 않는 기존 문제는 제외합니다. 이런 경계가 없으면 개발자가 곧 무시하게 될 경고만 쏟아집니다.
리뷰어는 critical·warning·suggestion으로 심각도를 구분한 XML을 반환합니다. coordinator는 겹치는 지적을 하나로 합치고, 코드 품질 리뷰어가 찾은 성능 문제를 성능 절로 옮기는 식으로 분류를 바로잡습니다. 추측, 사소한 취향, 오탐, 저장소 관례와 충돌하는 지적도 이 단계에서 제외합니다. 확신이 없으면 직접 소스를 읽어 확인하는 역할입니다.
판정은 승인 쪽에 무게를 둡니다. 다른 문제가 없는 MR에 production 위험이 없는 경고 하나가 붙었다면 approved_with_comments로 승인합니다. 여러 경고가 위험 패턴을 보일 때는 기존 봇 승인을 철회하고, critical 항목이나 production 안전 위험이 있으면 변경을 요청해 병합을 막습니다.
긴급 수정을 위한 탈출구도 있습니다. 사람이 break glass라고 댓글을 남기면 AI가 찾은 문제와 관계없이 강제 승인합니다. 모델 제공자가 중단되거나 리뷰 시스템에 버그가 있어도 이 경로를 쓸 수 있도록, 리뷰를 시작하기 전에 댓글을 확인하고 사용 사실을 기록합니다.
README 오탈자에 맞춘 작은 리뷰
README의 오탈자 한 줄을 고치는 데 일곱 에이전트가 Opus급 토큰을 쓸 이유는 없습니다. 시스템은 변경량과 파일 성격으로 MR을 trivial, lite, full로 나눕니다. trivial에서는 coordinator와 일반 코드 리뷰어만 실행합니다. 단, auth/나 crypto/ 같은 보안 민감 경로를 건드리면 변경량과 관계없이 전체 리뷰 대상입니다.
모델도 역할에 맞춰 배정합니다. 여러 리뷰어의 지적을 비교하고 최종 판단을 내리는 coordinator에는 최상위 모델을, 코드 품질·보안·성능에는 표준 등급 모델을 사용합니다. 문서·릴리스·AGENTS.md처럼 텍스트 중심인 작업의 기본 모델은 Kimi K2.5입니다. 작은 변경에서는 모델 비용도 낮춥니다. 예를 들어 trivial의 coordinator를 Opus에서 Sonnet으로 바꿉니다.
에이전트가 읽을 입력부터 추립니다. lock 파일, 외부 의존성, 축소 자산, 소스 맵은 diff에서 제외합니다. 생성 파일도 앞부분의 // @generated나 /* eslint-disable */ 같은 표시로 걸러내지만, 데이터베이스 마이그레이션은 예외입니다. 생성 도구가 만든 파일이어도 그 안의 스키마 변경은 검토해야 하기 때문입니다.
남은 diff를 모든 프롬프트에 복사하지도 않습니다. 파일별 패치를 diff_directory에 저장해 리뷰어가 자기 영역에 필요한 것만 읽게 하고, MR 공통 맥락은 shared-mr-context.txt로 공유합니다. 같은 MR 맥락을 일곱 프롬프트에 반복해서 넣는 토큰 비용을 피하려는 선택입니다.
입력의 경계도 관리합니다. 리뷰어별 지침에는 공통 필수 규칙을 붙이고, coordinator의 MR 메타데이터·댓글·이전 지적사항은 XML로 조립합니다. 사용자 입력에 들어 있는 예약 경계 태그는 제거합니다. MR 설명의 태그가 XML 경계를 닫고 새로운 지시를 끼워 넣는 일을 막기 위한 처리입니다.
GitLab과 모델 설정을 분리한 플러그인
수천 개 저장소에 적용할 도구에서 VCS와 AI 제공자를 고정하면, 어느 한쪽을 바꿀 때 다른 구성요소까지 수정해야 합니다. Cloudflare는 GitLab, Cloudflare AI Gateway, Engineering Codex 준수 검사, Braintrust 관측, AGENTS.md 검사, 원격 모델 설정, 텔레메트리를 플러그인으로 분리했습니다. GitLab 플러그인이 AI Gateway 설정을 읽거나 Cloudflare 플러그인이 GitLab API 토큰을 알지 않아도 되는 구성입니다.
실패를 다루는 방식도 단계마다 다릅니다. bootstrap은 병렬로 실행하고 실패를 허용하므로, 템플릿을 가져오지 못해도 리뷰를 이어갑니다. configure는 순차 실행하며 실패하면 작업을 멈춥니다. GitLab에 연결하지 못한 채 리뷰를 계속할 이유는 없기 때문입니다. 구성이 모인 뒤 원격 모델 설정 조회 같은 비동기 작업은 postConfigure에서 처리합니다.
플러그인은 최종 설정 객체를 직접 고치지 않습니다. ConfigureContext API에 에이전트, 제공자, 환경 변수, 프롬프트, 권한 설정을 등록하면 조립기가 이를 opencode.json으로 합칩니다.
OpenCode는 내부에서 이미 널리 쓰던 오픈소스였고 SDK도 갖추고 있었습니다. 특히 서버를 중심에 두고 TUI와 데스크톱 앱이 클라이언트로 동작한다는 점이 필수 조건에 맞았습니다. CLI를 우회하는 편법 없이 SDK로 세션을 만들고 프롬프트를 보내며 여러 세션의 결과를 수집할 수 있었습니다.
바깥의 조율 프로세스는 Bun.spawn으로 OpenCode를 실행합니다. 그 안에서는 런타임 플러그인의 spawn_reviewers 도구가 전문 리뷰어 세션을 생성합니다. 각 리뷰어는 독립된 세션에서 소스와 패치를 읽고 코드베이스를 검색합니다. coordinator가 개별 도구 사용까지 지휘하지는 않습니다.
개발자가 멈췄다고 오해한 CI 작업
고성능 모델은 생각하는 데 꽤 긴 시간을 쓰기도 합니다. CI 화면에서 아무 출력도 나오지 않자 개발자들은 리뷰가 멈췄다고 판단해 작업을 취소했습니다. 해결책은 단순했습니다. 30초마다 Model is thinking... (Ns since last output) 로그를 찍자, 작업 정지로 오해해 취소하는 문제는 거의 사라졌습니다.
큰 MR에서는 모델에 도달하기도 전에 실패했습니다. 로그가 가득한 MR 설명을 명령행 인자로 넘겼더니 Linux의 ARG_MAX 한계에 걸려 E2BIG 오류가 났습니다. 프롬프트를 표준 입력으로 전달하도록 바꾼 이유입니다.
출력은 한 줄마다 독립적인 JSON 객체를 담는 JSONL로 받습니다. 자식 프로세스가 중간에 종료해도 닫는 ]를 기다릴 필요 없이 이미 도착한 이벤트를 읽을 수 있습니다. 디스크에 매번 쓰는 부담을 줄이려고 100줄 또는 50ms마다 모아서 기록합니다. step_finish에서는 토큰 사용량을 추출하고, error 이벤트는 재시도 절차로 넘깁니다. 종료 이유가 length라면 모델이 max_tokens 한도에 도달해 출력을 잘랐다는 뜻이므로 다시 시도합니다.
spawn_reviewers는 작은 LLM 세션 스케줄러입니다. 완료 여부는 주로 session.idle 이벤트로 판단하고, 3초 간격의 상태 조회로 보완합니다. 시작 후 아무 출력도 없이 60초가 지난 세션은 조기에 종료합니다. 리뷰어별 제한 시간과 전체 실행 상한을 따로 두며, 전체 예산에 최소 2분이 남아 있을 때만 재시도합니다.
모델 장애에는 circuit breaker와 failback 체인을 사용합니다. 상태가 나빠진 모델을 피할 때는 같은 모델 계열의 이전 세대를 찾고, 2분 냉각 후에는 복구 확인용 요청 하나만 허용합니다. 전환을 유발하는 것은 재시도 가능한 API 오류입니다. 인증 실패, 컨텍스트 초과, 중단, 출력 형식 오류는 모델 전환 대상에서 제외합니다. coordinator 자체가 재시도 가능한 오류로 실패하면 별도 절차가 opencode.json의 모델 설정을 교체하고 프로세스를 다시 실행합니다.
제공자 전체를 바꾸기 위해 코드를 수정할 필요도 없습니다. CI는 Workers KV를 사용하는 Cloudflare Worker에서 모델 배정을 읽습니다. KV에서 제공자를 비활성화하면 실행 중인 CI 작업도 5초 이내에 우회하며, failback 체인도 원격으로 바꿀 수 있습니다.
관측 때문에 CI가 지연되지 않도록 추적 경로는 따로 뒀습니다. 시작·완료·지적사항·토큰 사용량을 별도 Worker에 보내는 클라이언트는 요청 시간을 2초로 제한하고, 대기 요청이 50개를 넘으면 정리합니다. Prometheus 메트릭은 묶어서 전송하며 프로세스 종료 직전에도 내보냅니다.
새 커밋 뒤에도 이어지는 리뷰 대화
새 커밋이 올라오면 이전 리뷰를 이어갑니다. coordinator는 마지막 리뷰 전문과 자신이 남긴 인라인 댓글, 각 댓글의 해결 상태를 받습니다. 수정된 문제는 새 출력에서 빼고 MCP 서버가 해당 스레드를 자동 해결합니다. 아직 남은 문제는 내용이 같아도 다시 출력해야 합니다. 그래야 MCP 서버가 스레드를 유지합니다.
사람이 끝낸 논의도 존중합니다. 사용자가 해결한 지적은 문제가 실질적으로 악화하지 않았다면 다시 열지 않습니다. “수정하지 않겠다”거나 “확인했다”는 답변도 해결로 취급합니다. “동의하지 않는다”는 답변에는 coordinator가 근거를 읽고 지적을 철회하거나 논의를 이어갑니다.
프로젝트 관례를 따라가야 할 AGENTS.md
팀이 Jest에서 Vitest로 옮겼는데 지침을 그대로 두면, AI는 계속 Jest 테스트를 작성하려고 합니다. AGENTS.md 전담 리뷰어는 이런 어긋남을 검사합니다. 패키지 관리자·테스트 프레임워크·빌드 도구·CI/CD 같은 변화에는 지침 갱신을 강하게 권고하고, 기존 패턴을 따르는 기능 추가나 사소한 수정에는 갱신을 요구하지 않습니다.
기존 지침의 내용도 검토합니다. 깔끔한 코드를 쓰라는 일반론, 200줄을 넘는 긴 파일, 실행 명령 없이 나열한 도구 이름은 문제로 봅니다. 짧더라도 실제 명령과 작업 경계가 담긴 AGENTS.md를 선호합니다.
팀은 GitLab CI 컴포넌트를 추가하면 Docker 이미지 준비, Vault 비밀정보 설정, 리뷰 실행, 댓글 게시를 사용할 수 있습니다. 저장소 루트의 AGENTS.md나 공통 템플릿으로 팀의 지침을 전달합니다. 로컬에서도 같은 방식으로 검토할 수 있습니다. /fullreview는 작업 트리의 diff에 동일한 위험 평가와 에이전트, 프롬프트를 적용합니다.
5,169개 저장소에 쌓인 한 달의 기록
2026년 3월 10일부터 4월 9일까지 5,169개 저장소의 48,095개 MR에서 131,246회 리뷰를 완료했습니다. 최초 검토와 수정 후 재리뷰를 합쳐 MR당 평균 2.7회입니다. 리뷰 완료 시간 중앙값은 3분 39초였고, break glass 사용은 288회로 MR의 0.6%에 해당했습니다.
리뷰당 평균 비용은 1.19달러, 중앙값은 0.98달러였습니다. 전체 리뷰가 필요한 대규모 리팩터링 때문에 비용 분포에는 긴 꼬리가 있지만, P99도 4.45달러였습니다. 위험 등급별 차이는 더 뚜렷합니다. trivial은 평균 0.20달러, 모든 전문 리뷰어를 실행하는 full은 평균 1.68달러였습니다.
전체 지적사항은 159,103건으로, 리뷰당 평균 약 1.2건입니다. 불확실한 지적을 많이 남기기보다 유효한 지적을 추리도록 설계한 결과이며, 프롬프트의 제외 기준이 기여한 부분입니다. Code Quality가 지적량의 거의 절반을 차지했고, Security가 남긴 11,985건 중 critical은 484건, 약 4%였습니다.
처리한 토큰은 약 1,200억 개이며 대부분이 캐시 읽기였습니다. 캐시 적중률은 85.7%입니다. 공통 맥락 파일과 여러 MR에서 반복 사용하는 동일한 기본 프롬프트가 기여한 요인입니다. 최상위 모델과 표준 등급 모델의 비용 비중은 대략 52 대 48이었습니다. Cloudflare는 Workers AI로 실행한 Kimi의 비용을 “없다”고 설명했습니다.
diff 밖에 남은 설계 의도
현재 모델의 AI 리뷰는 사람의 코드 리뷰를 대체하지 못합니다. diff와 주변 코드는 읽지만, 시스템이 왜 그렇게 설계됐는지와 변경이 아키텍처를 올바른 방향으로 이끄는지 판단할 맥락은 부족합니다. API 계약이 바뀌었다는 지적은 가능해도 모든 하위 소비자가 대응했는지는 검증하지 못합니다. 빠진 락을 찾는 것과 특정 타이밍·순서에 의존하는 경쟁 상태나 모든 교착 가능성을 찾는 것에도 차이가 있습니다.
큰 diff의 비용도 남아 있습니다. 500개 파일을 바꾸는 리팩터링처럼 변경 범위가 커지면 위험 등급을 나누어도 리뷰 비용이 커집니다. coordinator 프롬프트가 추정 컨텍스트 창의 50%를 넘을 때는 경고를 냅니다.
운영 설정과 측정 수치
| 항목 | 값 |
|---|---|
| 기본 coordinator 모델 | Claude Opus 4.7, GPT-5.4 |
| 기본 코드 품질·보안·성능 모델 | Claude Sonnet 4.6, GPT-5.3 Codex |
| 기본 문서·릴리스·AGENTS.md 모델 | Kimi K2.5 |
| 단순화한 위험 판정 코드 | 보안 민감 파일 또는 50개 초과 파일이면 full을 우선 적용; 그 외 변경 10줄 이하·20개 파일 이하면 trivial, 100줄 이하·20개 파일 이하면 lite, 나머지는 full |
| 보안 민감 경로 예시 | auth/, crypto/, 그 밖의 보안 관련 파일 경로 |
| trivial의 모델 조정 예시 | coordinator를 Opus에서 Sonnet으로 하향 |
| 로그 기록·heartbeat | 100줄 또는 50ms마다 기록; 30초마다 사고 중 로그 출력 |
| 상태 확인·무출력 종료 | 3초마다 폴링; 출력 없이 60초 실행된 세션 종료 |
| 실행·재시도 제한 | 작업당 5분, 코드 품질은 10분; 전체 25분; 재시도에 최소 2분 잔여 필요 |
| circuit breaker 복구 탐색 | 2분 냉각 후 탐색 요청 1개 허용 |
| 원격 설정·추적 제한 | 제공자 비활성화 후 실행 중 CI 작업이 5초 이내 우회; 추적 요청 2초 제한, 대기 요청 50개 초과 시 정리 |
| 문맥 크기 관련 기준 | AGENTS.md의 200줄 초과를 문제로 평가; coordinator 프롬프트가 추정 컨텍스트 창의 50% 초과 시 경고 |
| 측정 범위 | 2026-03-10~2026-04-09, 5,169개 저장소, 48,095개 MR, 131,246회 리뷰 |
| 재리뷰·수동 우회 | MR당 평균 2.7회 리뷰; break glass 288회, MR의 0.6% |
| 리뷰 비용 | 평균 $1.19; 중앙값 $0.98; P90 $2.36; P95 $2.93; P99 $4.45 |
| 리뷰 시간 | 중앙값 3분 39초; P90 6분 27초; P95 7분 29초; P99 10분 21초 |
| 주요 지적사항 수치 | 전체 159,103건; Code Quality 74,898건; Security 11,985건 중 critical 484건, 약 4% |
| 토큰·캐시 | 총 약 1,200억 토큰; 캐시 적중률 85.7% |
| trivial 비용 분포 | 24,529회; 평균 $0.20, 중앙값 $0.17, P95 $0.39, P99 $0.74 |
| lite 비용 분포 | 27,558회; 평균 $0.67, 중앙값 $0.61, P95 $1.15, P99 $1.95 |
| full 비용 분포 | 78,611회; 평균 $1.68, 중앙값 $1.47, P95 $3.35, P99 $5.05 |