사내 개발 규칙을 AI에게 읽히는 것만으로는 표준이 집행되지 않아요. 문서를 ‘권고’와 ‘차단’ 상태로 나누고, 각 규칙에 추적 가능한 ID를 붙여야 AI 리뷰가 개인 의견이 아닌 운영 시스템이 됩니다.
클라우드플레어가 만든 건 AI 리뷰어보다 ‘규칙의 원장’이에요
Cloudflare는 2026년 8월 공개한 사례에서 AI 코드 리뷰어가 4개월 동안 약 25만 건의 엔지니어링 표준 위반을 표시하고 1만6천 건의 머지를 막았다고 밝혔어요. 같은 표준을 사용하는 스펙 리뷰어는 구현 전 기술 설계 약 600건을 검토했습니다. 규모가 눈에 띄지만, 더 중요한 부분은 어떤 모델을 썼느냐가 아니에요. 사람과 여러 에이전트가 함께 참조하는 단일 규칙 원장을 먼저 만들었다는 점입니다.
이전에는 공식 문서, 저장소 파일, 채팅 기록과 담당자의 기억에 지침이 흩어져 있었어요. 찾은 내용이 최신인지, 권위가 있는지, 지금 작업에 적용되는지도 판단하기 어려웠고요. Cloudflare는 이를 ‘Engineering Codex’라는 관리형 표준 저장소로 옮겼습니다. 아키텍처·보안·신뢰성·TypeScript·Rust 같은 도메인마다 소유자를 두고, 직원이 머지 리퀘스트로 RFC를 제안하면 여러 단계의 검토를 거쳐 소유자가 최종 승인하는 방식이에요.
표준 문구에는 RFC 2119의 MUST와 SHOULD를 사용합니다. RFC 2119에서 MUST는 절대적인 요구사항이고, SHOULD는 타당한 사정이 있다면 영향을 충분히 검토한 뒤 벗어날 수 있는 권고예요. 이 문서는 이런 강한 표현을 상호운용이나 위해 방지에 꼭 필요한 경우에 신중하게 쓰라고도 당부합니다. 즉 모든 모범 사례를 MUST로 격상하면 표준이 강해지는 게 아니라, 차단 사유가 남발되어 신뢰를 잃기 쉬워요.
좋은 규칙은 답뿐 아니라 적용 조건을 담아요.
“OpenAPI를 작성한다”보다 “외부에 노출되는 요청·응답 스키마는 OpenAPI로 문서화해야 한다”가 기계적으로 판정하기 좋습니다. 적용 대상, 요구 수준, 근거, 예외 승인자와 원문 링크를 한 묶음으로 관리해 보세요.
핵심은 승인과 집행을 분리하는 두 번의 스위치예요
Cloudflare의 RFC는 승인됐다고 즉시 머지를 막지 않아요. approved 상태에서는 위반을 비차단 권고로 보여주고, 별도 승격을 거쳐 enforced가 된 뒤에야 MUST 위반을 차단합니다. 팀이 새 규칙을 받아들일 시간과 자동 판정의 정확도를 확인할 시간을 따로 확보하는 구조예요.
| 상태 | 리뷰 동작 | 확인할 운영 지표 |
|---|---|---|
| 초안 | 소유자와 이해관계자가 문구·범위 검토 | 모호한 조건, 중복 규칙, 예외 경로 |
| 승인 | AI가 권고하되 머지는 허용 | 오탐률, 수정 수용률, 반복 질문 |
| 집행 | 검증된 MUST 위반만 차단 | 차단 해제 시간, 예외율, 우회 시도 |
| 폐기 | 신규 판정을 중단하고 이력은 보존 | 대체 규칙 연결, 기존 예외 정리 |
이 방식은 코드 호스팅 플랫폼의 실제 집행 장치와도 잘 맞아요. GitHub의 보호 브랜치는 필수 상태 검사가 성공·건너뜀·중립 상태여야 머지를 허용하고, 특정 GitHub App이 만든 검사 결과만 신뢰하도록 출처를 제한할 수도 있습니다. AI 리뷰 결과를 차단 게이트로 연결한다면 “누가 어떤 권한으로 성공 상태를 기록할 수 있는가”까지 규칙 설계에 포함해야 해요.
반대로 SHOULD와 개인 취향까지 차단하면 리뷰가 느려집니다. Google의 공개 코드 리뷰 지침도 완벽한 코드를 요구하기보다 변경이 전체 코드 건강성을 분명히 개선하면 승인하는 쪽을 권합니다. 스타일은 문서화된 스타일 가이드를 권위로 삼고, 사소한 의견은 필수가 아님을 표시하라고 해요. AI도 똑같습니다. 근거가 있는 필수 수정, 권고, 참고 의견을 화면에서 분명히 구분해야 개발자가 모든 문장을 차단 명령으로 오해하지 않아요.
25만 건 탐지는 곧 25만 건의 품질 개선이 아니에요.
Cloudflare가 공개한 수치는 자체 운영 집계이며 독립 평가 결과가 아닙니다. 동일 위반의 반복, 오탐, 개발자가 수용한 비율은 별도로 제시되지 않았어요. 탐지 건수보다 규칙별 수용률·예외율·차단 해제 시간·재발률을 함께 봐야 합니다.
긴 문서를 통째로 넣지 말고 ‘탐색용 색인’과 원문을 분리하세요
Cloudflare Codex에는 이미 60개가 넘는 RFC가 있어 전체 문서를 매번 모델 컨텍스트에 넣기 어렵습니다. 그래서 별도 에이전트가 MUST·SHOULD 문장을 JSON으로 추출하고, RFC 번호·도메인·상태·섹션·원문 링크 같은 메타데이터를 붙입니다. 리뷰어는 먼저 이 압축 색인을 검색하고, 판단에 추가 맥락이 필요할 때만 RFC 전문을 불러와요.
각 문장에는 RFC가 수정돼도 유지되는 안정적인 slug가 붙습니다. 이 ID가 있어야 같은 규칙의 탐지량과 오탐을 기간별로 비교하고, 예외 승인과 폐기 이력을 연결할 수 있어요. AI가 “보안상 좋지 않습니다”라고만 말하면 의견이지만, “SEC-API-014 위반이며 원문 3.2절이 근거”라고 남기면 재현하고 이의를 제기할 수 있는 판정이 됩니다.
규칙과 집행 코드를 분리하는 발상은 AI에만 해당하지 않아요. Open Policy Agent는 정책을 선언형 코드로 작성하고, 애플리케이션이 구조화된 JSON 입력을 보내 판정을 받도록 설계됐습니다. 정책 결정과 실제 집행을 분리하며 CI/CD, API 게이트웨이, Kubernetes 등에서 사용할 수 있어요. 확실하게 기계 판정할 수 있는 항목은 린터나 정책 엔진에 맡기고, 문맥 판단이 필요한 아키텍처·문서 품질만 AI에 남기는 편이 빠르고 감사하기도 쉽습니다.
Cloudflare도 같은 계층을 택했어요. 기계적으로 검증 가능한 언어 규칙은 커스텀 린터로 밀리초 단위에 보여주고, AI 리뷰어는 관련 RFC를 찾아 문맥상 위반인지 평가합니다. 로컬 CLI로 CI 전에 같은 리뷰를 실행할 수 있게 해 피드백 거리도 줄였고요. 자사 AI 엔지니어링 스택에서는 모든 표준 CI 저장소의 머지 리퀘스트를 AI가 검토하고, 판정마다 구체적인 Codex 규칙 ID를 인용한다고 설명합니다.
이번 주에 작은 저장소 하나로 시작하는 4단계
반복되는 리뷰 의견 10개만 모으세요
최근 PR 또는 MR 30개를 보고 두 번 이상 반복된 의견을 추립니다. 각 항목에 rule_id, 적용 경로, 요구 수준, 근거 링크, 소유자, 예외 승인자를 적으세요. “깔끔하게 작성”처럼 판정 조건이 없는 문장은 제외합니다.
린터와 AI의 경계를 먼저 나누세요
AST·정규식·스키마로 확실히 잡히는 규칙은 ESLint, oxlint, Semgrep, OPA 같은 결정론적 검사로 보냅니다. 설계 의도나 문서 맥락을 읽어야 하는 규칙만 AI 큐에 남기세요. 같은 위반을 두 도구가 중복 보고하지 않도록 대표 검사기를 하나 지정합니다.
2주 동안 경고 모드로 관찰하세요
AI 결과에 규칙 ID, 심각도, 근거, 문제 위치, 확신도와 원문 링크를 출력하되 머지는 막지 않습니다. 개발자가 ‘수용·오탐·예외 요청’ 중 하나를 누르게 하고 규칙별 수용률을 기록하세요. 표본이 적다면 기간보다 최소 판정 건수를 기준으로 삼습니다.
검증된 MUST만 필수 검사로 승격하세요
보안·데이터 손실·호환성처럼 위반 비용이 크고 오탐이 충분히 낮은 항목만 브랜치 보호의 필수 상태 검사로 연결합니다. 예외에는 만료일과 승인자를 요구하고, 차단 해제 시간과 예외율이 급증하면 자동으로 경고 모드로 되돌리는 운영 조건도 정하세요.
최종 승인 책임은 규칙 소유자와 코드 소유자에게 남겨두세요. AI는 관련 지침을 작업 순간에 찾아주는 집행 인터페이스이지, 어떤 규칙이 조직에 옳은지를 스스로 결정하는 권위가 아닙니다.
