2026년의 AI 코딩 도구는 이제 팀의 코드만 읽지 않습니다. 설계 RFC, incident report, repository instruction, CI 결과, 보안 정책까지 읽고 PR에 의견을 붙이거나 작업을 시작합니다. 이때 엔지니어링 표준은 위키의 참고 자료로 머물기 어렵습니다. agent와 reviewer가 같은 규칙을 반복 적용하려면, 무엇이 최신인지·어떤 저장소에 해당하는지·발견만 할지 차단할지·예외는 언제 끝나는지를 기계와 사람이 함께 이해할 수 있어야 합니다.
Cloudflare는 2026년 8월 공유 engineering guidance를 domain owner와 RFC 구조로 관리하는 “Codex"에 연결하고, AI code reviewer와 spec reviewer가 이를 적용한다고 공개했습니다. 중요한 설계는 approved와 enforced 상태를 분리한 점입니다. 승인된 RFC는 우선 non-blocking finding을 만들고, 팀이 흡수할 시간을 가진 뒤에야 MUST 위반을 차단할 수 있습니다. 같은 시기 GitHub도 PR 안에 AI security detection을 표시하는 흐름을 넓히고 있습니다. 다만 GitHub의 현재 public preview 결과는 정보성이며 merge를 자동 차단하지 않습니다. 두 신호를 합치면 결론은 단순합니다. AI가 찾아낸 결과와 조직이 차단하기로 합의한 정책은 다른 제품 단계입니다.
이 글은 Harness Engineering, Agent Instruction Context Hygiene, AI Usage Metrics Contract, AI 코드 리뷰 거버넌스의 다음 단계입니다. 앞선 글들이 agent 실행 프레임, 컨텍스트 품질, 비용 관측, 리뷰 라우팅을 다뤘다면, 여기서는 그 프레임이 참조하는 표준 자체를 어떻게 운영 제품으로 만들지에 집중합니다.
참고한 공식 신호:
- Cloudflare: How Cloudflare enforces engineering standards using AI — domain owner, RFC, approved/enforced lifecycle, code·spec review 연결
- GitHub Changelog: Code scanning shows AI security detections on pull requests — PR 표면의 AI 탐지, enterprise enablement, 정보성 결과의 범위
- GitHub: From coder to orchestrator — agent의 유연한 작업과 CI·branch rule의 결정적 경계를 결합하는 흐름
이 글에서 얻는 것
- agent instruction, coding standard, security rule, design RFC를 한 덩어리 문서가 아니라 서로 다른 lifecycle을 가진 정책으로 분리할 수 있습니다.
draft → approved → shadow → enforced → retired전환에서 무엇을 측정하고 언제 멈춰야 하는지 숫자 기준을 얻습니다.- AI finding을 곧바로 merge block으로 만들지 않고, deterministic check·사람 검토·예외 만료와 연결하는 방법을 이해합니다.
- 5~20명 팀도 과도한 governance 도입 없이 표준 3개부터 시작할 수 있는 최소 운영 모델을 갖게 됩니다.
핵심 개념/이슈
1) 표준의 문제는 검색이 아니라 권위와 적용 가능성이다
팀 문서가 흩어져 있으면 agent가 필요한 규칙을 못 찾는 문제가 생깁니다. 그러나 검색 시스템만 붙인다고 해결되지는 않습니다. 오래된 wiki, 임시 Slack 답변, 특정 팀의 README, 보안 가이드가 모두 검색되면 agent와 사람은 더 많은 상충 근거를 받습니다. 표준으로 쓸 수 있으려면 적어도 다음 질문에 답해야 합니다.
| 필드 | 질문 | 없을 때 생기는 문제 |
|---|---|---|
| source of truth | 어느 문서가 실제 규칙인가? | 오래된 안내를 최신 정책처럼 적용 |
| owner | 누가 정확성·변경을 책임지는가? | finding에 이의가 있어도 결론을 못 냄 |
| scope | 어떤 언어·서비스·경로에 적용되는가? | frontend 규칙이 batch worker PR을 막음 |
| norm | MUST, SHOULD, 참고 중 무엇인가? | 권고가 차단 규칙으로 과승격 |
| evidence | 어떤 파일·테스트·설계 항목으로 검증하는가? | agent가 그럴듯한 의견만 반복 |
| lifecycle | 언제 활성화·폐기되는가? | 이미 끝난 예외와 규칙이 계속 남음 |
Cloudflare의 사례에서 domain owner와 RFC 형식, RFC 2119의 MUST·SHOULD, front matter 상태가 함께 언급되는 이유도 이것입니다. 표준을 자연어 한 문장으로만 남기면 사람에게는 유연해 보이지만, agent가 일관되게 적용할 경계가 없습니다. 반대로 모든 것을 정적 분석 규칙으로 바꾸려 하면 도메인 판단과 설계 trade-off를 잃습니다. 좋은 표준은 자연어의 이유·예외·예시와 기계가 읽을 metadata·검증 증거를 함께 가집니다.
2) 발견(finding)과 차단(enforcement)은 다른 신뢰 단계다
AI reviewer가 finding을 만들었다고 해서 곧바로 branch protection을 걸어서는 안 됩니다. GitHub의 AI security detection도 PR에 결과를 표시하지만 현 단계에서는 informational입니다. 이건 기능이 약하다는 뜻이 아니라, 검출 자체와 조직의 merge 결정 사이에 오탐 비용·우회 경로·담당자·복구 방식을 검증해야 한다는 뜻입니다.
Cloudflare의 approved/enforced 분리는 실무적으로 좋은 모델입니다. 문서가 승인됐을 때부터 agent는 관련 위반을 찾아 보여줄 수 있지만, 차단은 별도 promotion 뒤에 시작합니다. 이 사이에서 팀은 rule wording, repository scope, validator 품질, migration 비용을 조정합니다. 차단은 규칙이 존재한다는 선언이 아니라, 오탐과 예외를 감당할 운영 능력이 생겼다는 선언입니다.
아래처럼 state를 분리하면 논의가 빨라집니다.
draft : 제안 중. agent retrieval 대상 아님
approved : source of truth. 교육·설계 리뷰에는 사용 가능
shadow : finding만 기록. PR 차단 금지
enforced : 명시된 MUST + 적용 범위에서만 required check
retired : 새 변경에는 미적용. 과거 예외와 migration 기록만 보존
approved와 shadow를 생략하면 표준이 승인되자마자 개발 흐름을 멈추거나, 반대로 문서가 아무 행동 변화도 못 만드는 두 극단으로 갑니다. 보안·권한·데이터 삭제처럼 false negative 비용이 높은 영역은 짧은 shadow 뒤 더 엄격하게 갈 수 있습니다. formatting·naming처럼 false positive 비용이 더 큰 영역은 차단보다 autofix 또는 정보성 comment가 적합할 수 있습니다.
3) AI는 해석·탐색에, 결정적 검사는 증거에 쓴다
agent가 잘하는 일은 흩어진 규칙을 작업 맥락에 맞춰 찾고, 설계의 빠진 질문을 드러내고, 기존 test나 config의 영향 범위를 설명하는 것입니다. 하지만 같은 입력에도 결과가 달라질 수 있는 AI finding 하나를 배포 승인의 유일 근거로 만들면 감사와 재현성이 약해집니다.
따라서 구현은 둘을 연결하되 교체하지 않는 구조가 좋습니다.
- AI retrieval/review: 관련 표준 후보, 적용 근거, 위험 경로, 수정 제안을 PR·RFC에 남긴다.
- deterministic validation: lint, unit/integration test, schema check, dependency policy, IaC plan처럼 반복 가능한 증거를 실행한다.
- human decision: 도메인 invariant, 고객 영향, policy exception, rollout/rollback은 owner가 승인한다.
- audit trail: 어느 standard version이 어떤 finding·결정·예외·테스트와 연결됐는지 저장한다.
GitHub가 설명한 agent flow도 issue나 schedule 같은 이벤트가 agent를 시작하고, 결과 PR에서 lint·test·security scan·build verification과 CODEOWNERS·branch protection이 합쳐지는 구조입니다. agent의 유연성은 가치가 있지만, merge boundary는 가능한 결정적으로 유지해야 합니다. Harness Engineering의 capability/validation/recovery 분리가 표준 운영에도 그대로 적용됩니다.
4) 표준 품질은 규칙 수가 아니라 feedback loop로 측정한다
“규칙 50개를 등록했다"는 것은 성과 지표가 아닙니다. 실제로 봐야 할 것은 누가 적용했고 어떤 결과가 나왔는지입니다. 특히 AI finding은 coverage가 넓어지는 대신 관련 없는 경고도 늘 수 있으므로 precision과 개발 흐름 비용을 같이 봐야 합니다.
| 지표 | 확대 신호 | 보류·수정 신호 |
|---|---|---|
| finding precision | 표본 검토에서 80% 이상 actionable | 60% 미만 또는 반복적인 이유 없는 경고 |
| false-positive override | 5% 미만 | 10% 초과가 1주 지속 |
| remediation p95 | 서비스 등급별 SLO 안 | finding이 backlog에만 쌓임 |
| enforcement bypass | 승인된 긴급 예외만 존재 | owner 없는 bypass 또는 임시 해제 반복 |
| rule coverage | 대상 PR의 95% 이상에 올바른 scope | 관련 없는 repo·경로에 과적용 |
| rollback after enforcement | 0건 목표 | merge block이 릴리스·incident를 유발 |
숫자는 팀의 변경량에 맞춰 바꿉니다. 다만 threshold를 처음부터 문서화해야 “시끄럽지만 중요한 규칙"과 “조용하지만 무시되는 규칙"을 구분할 수 있습니다. AI Usage Metrics Contract에서 비용을 PR 결과와 join하듯, 표준 finding도 merge, hotfix, exception, review time과 연결해야 합니다.
실무 적용
1) 세 가지 표준으로 최소 제품을 만든다
처음부터 전사 engineering manual을 agent knowledge base로 옮기지 않습니다. 최근 incident나 반복 리뷰에서 비용이 컸고, 적용 범위가 명확하며, owner가 있는 표준 세 개를 고릅니다. 예를 들면 다음 조합입니다.
- S1: 외부 HTTP 호출 — timeout, retry budget, circuit breaker, metric을 명시한다.
- S2: DB schema migration — expand/contract와 rollback·backfill 계획을 PR에 붙인다.
- S3: privileged action — 권한 변경·데이터 export·삭제는 audit event와 2인 승인을 요구한다.
각 표준을 id, title, owner, applies_to, normative_requirements, evidence, exception_process, status, review_after 필드로 관리합니다. 여기서 applies_to를 파일 path, service label, change type으로 좁히는 일이 중요합니다. 예를 들어 문서 PR에 database migration rule이 나온다면 모델 품질 문제가 아니라 표준 metadata 품질 문제입니다.
2) 30일 shadow와 점진 enforcement를 운영한다
1주차: baseline. 최근 20~50개 PR을 표본으로 삼아 새 표준이 몇 건을 잡는지, 사람이 맞다고 보는 비율이 얼마인지 수동으로 확인합니다. 이 시기에는 agent comment를 PR에 자동 게시하지 않고 내부 report로만 봐도 됩니다.
2~3주차: shadow finding. 적용 범위가 명확한 PR에만 informational finding을 남깁니다. owner는 매일이 아니라 주 2회 30분씩 표본을 검토하고, false positive reason code를 남깁니다. not-applicable, stale-standard, missing-evidence, validator-bug처럼 분류를 고정하면 rule 수정의 방향이 보입니다.
4주차: limited enforcement. 표본 precision이 80% 이상, false-positive override가 5% 미만, remediation p95가 팀 목표 안이고 rollback 경로가 확인된 규칙만 MUST 항목으로 차단합니다. 처음에는 신규 서비스 또는 pilot repository 1~3개로 제한합니다. 예외는 issue/티켓 ID, owner, 만료일(기본 14일, 최대 30일)을 요구하고 영구 bypass를 허용하지 않습니다.
이 단계에서 rollout을 되돌릴 kill switch도 있어야 합니다. validator outage, 10분 동안 3건 이상의 clearly-invalid block, hotfix path의 과도한 대기 중 하나가 발생하면 enforcement를 shadow로 즉시 내리고 원인·영향·재개 조건을 기록합니다. policy가 안전을 위해 존재하더라도, policy 장애가 서비스 복구를 더 늦추면 신뢰를 잃습니다.
3) instruction과 표준을 구분해 연결한다
AGENTS.md나 repo instruction에는 “변경 전 표준 registry를 확인하고, 적용된 standard ID와 검증 결과를 PR에 남긴다” 같은 행동 규칙만 둡니다. timeout 숫자, migration 순서, 데이터 retention 세부처럼 자주 바뀌는 정책 본문까지 모두 instruction에 복사하면 drift가 생깁니다.
표준 본문은 versioned registry에서 관리하고, agent는 task·path·service metadata로 필요한 표준만 retrieve합니다. Agent Instruction Context Hygiene가 말한 Core/Scoped/On-demand 분리는 여기에도 유효합니다. safety boundary는 항상 로드하되, 언어별 구현 규칙과 운영 runbook은 scope를 만족할 때만 읽는 편이 정확도와 token 예산 모두에 유리합니다.
4) 예외도 수명주기를 가진 변경으로 다룬다
예외는 실패가 아닙니다. legacy migration, regulator 요구, 장애 복구, vendor limitation 때문에 필요할 수 있습니다. 문제는 “이번만"이라는 comment가 영구 규칙이 되는 것입니다. 예외에는 최소한 standard ID, 위험 설명, compensating control, 승인자, 만료일, 제거 PR 또는 ticket을 붙입니다.
예외가 30일 뒤에도 남는다면 재승인하기보다 먼저 세 질문을 합니다. 표준 scope가 너무 넓은가? validator가 실제 구현 패턴을 지원하지 못하는가? 제품 요구가 표준의 가정을 바꾸었는가? 예외가 같은 repository에서 3회 반복되면 individual waiver가 아니라 표준 개정 RFC로 승격하는 기준을 두면 숨은 운영 부채를 줄일 수 있습니다.
트레이드오프/주의점
- 표준을 강제하면 초기 속도는 떨어질 수 있습니다. 특히 legacy codebase에 새 rule을 한꺼번에 적용하면 기존 부채가 모든 PR의 차단 사유가 됩니다. 새 변경만 적용하거나 touched-line 방식으로 시작해야 합니다.
- AI finding은 증거가 아니라 가설일 수 있습니다. 보안·성능·설계 issue의 설명은 유용하지만, merge block은 재현 가능한 test·scanner·정책 check 또는 명시된 사람 승인과 결합해야 합니다.
- owner 없는 표준은 agent가 더 빨리 낡게 만듭니다. 문서가 오래됐는데 AI가 대량으로 인용하면 잘못된 정책을 더 넓게 확산할 수 있습니다. owner와 review-after가 없는 표준은 retrieval 대상에서 낮추거나 제외합니다.
- 예외를 숨기면 bypass가 늘어납니다. 지나치게 엄격한 gate는 사람이 증거를 남기지 않는 우회 경로를 찾게 합니다. 짧고 추적 가능한 예외 흐름이 오히려 정책 준수율을 높입니다.
- 벤더 사례의 숫자를 그대로 목표로 삼지 않습니다. 대규모 조직의 수십만 finding과 수만 merge block은 방향을 보여 주지만, 작은 팀은 20개 PR 표본과 세 규칙의 precision부터 보는 편이 낫습니다.
체크리스트 또는 연습
체크리스트
- 표준마다 source of truth, owner, scope,
MUST/SHOULD, evidence, status, review-after가 있다. - AI finding과 deterministic check, 사람 승인, branch protection의 책임이 구분돼 있다.
- 새 rule은 baseline과 shadow finding 없이 바로 merge block이 되지 않는다.
- enforcement 승격 기준에 precision, override, remediation time, rollback 조건이 숫자로 적혀 있다.
- 예외에 ticket, owner, compensating control, expiry가 있고 만료된 bypass를 주간 점검한다.
- agent instruction은 표준 본문을 복제하지 않고 registry 조회·증거 기록 같은 행동 계약만 담는다.
연습 과제
- 최근 incident 또는 반복 review comment 하나를 골라
standard ID / scope / MUST / evidence / owner / exception / review-after형식의 1쪽 RFC로 바꿔 보세요. - 최근 PR 20개에 이 표준을 shadow 적용하고, true positive·not applicable·stale standard·validator bug 비율을 계산해 보세요.
- precision 80%, override 5% 미만, rollback 가능이라는 세 조건을 만족할 때만 pilot repository에 차단을 켜는 GitHub branch rule 또는 CI check 설계를 작성해 보세요.
💬 댓글