AI 리뷰 의견 하나 때문에 머지가 멈추기 시작했다면
처음에는 AI 코드 리뷰가 꽤 든든합니다. 사람이 놓친 사내 규칙을 찾아주고 근거 문서까지 붙여주니까요. 하지만 그 의견을 필수 검사에 연결하는 순간, 맥락을 잘못 읽은 판정도 실제 머지 차단이 됩니다. 개발자는 규칙을 따르기보다 검사를 우회할 방법부터 찾게 될 수 있어요.
Cloudflare는 이 문제를 모델 성능만으로 풀지 않았습니다. 개발 표준을 RFC로 관리하면서 문서가 승인된 상태와 자동 차단에 사용할 수 있는 상태를 분리했어요. 승인된 규칙은 먼저 비차단 권고로 표시하고, 별도로 집행 상태가 된 RFC의 충족되지 않은 MUST만 승인 보류나 머지 차단에 사용합니다.
이 사례에서 가져올 것은 거대한 AI 리뷰 시스템이 아닙니다. 규칙 하나에도 요구 수준, 안정적인 ID, 적용 범위, 원문과 집행 상태를 붙여야 AI 의견을 추적하고 이의를 제기할 수 있다는 운영 구조예요.
1만6천 건보다 먼저 집계 범위를 읽어야 합니다
Cloudflare는 2026년 8월 공개한 글의 도입부에서 이전 4개월 동안 AI 코드 리뷰어가 표준 이탈을 거의 25만 건 표시하고 1만6천 건의 머지를 막았다고 밝혔습니다. 그런데 상세 절에서는 Codex 도입 이후 약 23만 건을 표시하고 약 1만6천 건에서 승인을 보류했다고 표현해요. 두 집계의 시작일과 포함 범위가 같은지는 공개되지 않았으므로 하나의 정밀한 성과 수치로 합쳐 읽으면 안 됩니다.
탐지 건수는 품질 개선 건수가 아닙니다.
전체 또는 고유 머지 리퀘스트 수, 같은 변경에 대한 반복 판정, 오탐률과 개발자의 수정 수용률은 공개되지 않았습니다. 이 사례는 AI 리뷰의 정확도를 증명한다기보다, 많은 판정을 개발 흐름에 연결할 때 어떤 집행 구조가 필요한지 보여주는 운영 사례에 가깝습니다.
스펙 리뷰 수치도 같은 방식으로 봐야 합니다. Cloudflare의 AI 스펙 리뷰어는 2026년 5월 초부터 글 공개 시점까지 공개 상태의 고유 스펙 약 600개를 검토했고, 수정 후 재실행 등을 포함해 3,200회 넘게 실행됐습니다. 발견 사항의 심각도 구성은 major 65%, minor 29%, critical 6%였지만 총 발견 건수는 공개되지 않았고, 이 비율도 정확도나 실제 결함 예방률을 뜻하지 않습니다.
승인과 집행은 서로 다른 스위치입니다
Cloudflare Codex에서 RFC가 approved가 되면 AI 리뷰어는 관련 위반을 알려줄 수 있지만 결과는 비차단입니다. RFC가 별도 단계에서 enforced로 승격된 뒤에야 충족되지 않은 MUST가 심각도에 따라 승인 보류나 차단으로 이어집니다. 누가 승격을 승인하는지, 어느 정도의 오탐률이나 관찰 기간이 필요한지는 공개되지 않았어요.
| 규칙 상태 | AI 리뷰 동작 | 팀이 별도로 정할 것 |
|---|---|---|
| approved | 근거가 있는 비차단 권고 | 적용 범위와 반복되는 예외 확인 |
| enforced | 충족되지 않은 MUST를 승인 보류·차단에 사용 | 승격 권한, 이의 제기와 차단 해제 경로 |
MUST와 SHOULD도 같은 명령어가 아닙니다. RFC 2119에서 MUST는 절대적인 요구사항이고, SHOULD는 특정 상황에서 벗어날 타당한 이유가 있을 수 있지만 그 영향을 충분히 이해하고 검토해야 하는 수준입니다. 강한 요구 표현은 상호운용이나 위해 방지에 실제로 필요할 때 신중하게 사용해야 하고요. 모든 모범 사례를 MUST로 바꾸면 집행력이 강해지는 것이 아니라 차단 사유만 늘어날 수 있습니다.
Google의 공개 코드 리뷰 지침도 완벽함보다 코드베이스의 지속적인 개선을 우선하며, 중요하지 않은 의견에는 선택 사항이라는 표시를 붙이라고 권합니다. AI 리뷰 화면에서도 필수 수정과 권고를 분명히 구분해야 모든 의견이 사실상의 차단 명령으로 변하지 않아요.
긴 규칙집보다 안정적인 규칙 ID가 먼저예요
Cloudflare에는 60개가 넘는 RFC가 있어 매번 전문을 모델에 넣지 않습니다. 별도 에이전트가 MUST·SHOULD 문장을 JSON으로 추출하고 RFC 번호, 제목, 상태, 도메인, 섹션, 요구 수준과 원문 링크를 붙입니다. 리뷰어는 이 압축된 색인을 먼저 검색하고 추가 맥락이 필요할 때만 RFC 전문을 불러옵니다.
각 요구 문장에는 RFC가 수정된 뒤에도 유지되는 안정적인 slug가 붙습니다. 그래야 여러 시스템에서 같은 규칙의 판정, 분석과 예외를 이어서 추적할 수 있어요. Cloudflare의 내부 AI 엔지니어링 스택 역시 리뷰 판정에 구체적인 Codex 규칙 ID를 인용한다고 설명합니다.
규칙 레코드는 판정문이 아니라 근거의 주소입니다.
“API 문서가 부족합니다”보다 어떤 문서의 어느 절이 어떤 변경에 적용되는지 보여줘야 담당자가 같은 근거를 다시 확인할 수 있습니다. 다만 Cloudflare가 공개한 JSON은 축약 예시이므로 완전한 외부용 설정 스키마로 간주하면 안 됩니다.
지금 해볼 것: 비차단 규칙 레코드 하나 만들기
Cloudflare Engineering Codex와 내부 리뷰 CLI에는 외부 조직을 위한 공개 설치·인증 절차가 확인되지 않았습니다. 따라서 첫 실행은 Cloudflare 도구를 설치하는 실습이 아니라, 현재 팀 문서와 편집기만으로 반복 리뷰 의견 하나를 추적 가능한 레코드로 바꾸는 작업입니다.
- 준비물과 접근 권한을 확인합니다. 브라우저로 열 수 있는 현재 개발 표준의 정확한 섹션 링크, 최근 PR·MR에서 반복된 리뷰 의견 하나, 규칙이 속한 도메인과 문서 상태, JSON을 저장할 사내 문서나 저장소를 준비하세요. 별도 Cloudflare 계정·설치·인증은 필요하지 않습니다. 사내 원문을 열 권한과 레코드를 저장할 권한만 있으면 됩니다.
- 원문에서 요구 수준을 확인합니다. 리뷰 의견을 해당 표준의 정확한 문장과 대조하세요. 반드시 지켜야 하는 절대 요구인지, 타당한 예외가 가능한 권고인지 RFC 2119의 MUST·SHOULD 정의로 분류합니다. 현재 효력이 있는 원문이나 정확한 절을 찾을 수 없다면 자동 판정 후보에서 제외하세요.
- 아래 입력을 자체 문서에 저장합니다. 이는 Cloudflare 공개 필드를 참고해 편집부가 만든 검토용 예시이며, Cloudflare에서 실행되는 설정 파일이 아닙니다.
{ "rfc": "TEAM-API-001", "title": "API schema documentation", "status": "approved", "domain": "api-platform", "statements": [ { "slug": "api-schemas-must-be-documented", "section": ["API", "Schema"], "level": "MUST", "text": "외부 요청·응답 스키마는 팀의 API 명세에 문서화해야 한다.", "href": "https://internal.example/standards/api#schema" } ] } - 원문과 레코드를 직접 대조합니다.
href가 정확한 절을 여는지,text가 원문의 대상을 넓히거나 줄이지 않았는지,level이 원문과 일치하는지 확인하세요.slug는 이후 판정과 예외를 연결할 수 있도록 다른 규칙과 겹치지 않는 고정 식별자로 정합니다. - 성공 상태를 확인합니다. 상태, 도메인, 안정적인 slug, 원문 섹션, 요구 수준, 요구 문장과 직접 링크가 모두 있고 원문과 의미가 일치하면 첫 결과입니다.
status는approved로 유지하세요. 이 단계에서는 PR·MR을 막지 않습니다.
실제 차단 연결에는 규칙을 읽는 판정기, 저장소 권한, 결과 형식, 승격 권한과 복구 경로가 추가로 필요합니다. 공개 자료에 없는 관찰 기간이나 오탐률을 Cloudflare의 공식 승격 기준처럼 사용해서는 안 됩니다.
차단 전에는 검사 역할과 플랫폼 권한을 나누세요
같은 입력에서 항상 같은 답을 낼 수 있는 규칙까지 AI에 맡길 필요는 없습니다. Cloudflare는 기계적으로 검증 가능한 언어별 요구사항을 커스텀 린터로 제공하고 TypeScript에는 oxlint를 사용합니다. 문맥을 읽어야 하는 위반은 AI 리뷰어가 맡고, 내부 CLI로 같은 리뷰 흐름을 로컬에서 실행합니다. 다만 이 CLI의 외부 설치 명령과 인증 방식은 공개되지 않았습니다.
자체 판정기를 GitHub의 필수 상태 검사에 연결한다면 별도의 플랫폼 규칙도 적용됩니다. GitHub 공식 문서에 따르면 required check가 successful, skipped 또는 neutral 상태여야 병합할 수 있으며, 상태를 갱신할 예상 출처를 특정 GitHub App으로 제한할 수 있습니다. 이는 GitLab 기반인 Cloudflare 내부 구현을 재현하는 절차가 아니라 GitHub에서 사용할 수 있는 별도 구현 예시예요.
차단으로 승격하기 전에는 최소한 누가 승격을 승인하는지, 판정에 이의를 제기할 곳은 어디인지, 잘못된 차단을 누가 해제할지 정해야 합니다. AI 리뷰를 신뢰하게 만드는 것은 더 단호한 문장이 아니라 어떤 규칙이 지금 권고이고 어떤 규칙만 차단 권한을 갖는지 설명할 수 있는 상태입니다.
