2026 개발 트렌드: Repo-local Agent Policy, AI 코딩 에이전트의 작업 규칙이 README에서 실행 계약으로 이동한다

AI 코딩 에이전트 도입이 빨라지면서 저장소 안의 문서 역할도 바뀌고 있습니다. 예전 README는 사람에게 “이 프로젝트는 이렇게 빌드합니다"를 알려주는 안내서였습니다. 지금은 에이전트가 저장소를 열자마자 읽는 작업 규칙의 입력값이 되고 있습니다. 어떤 테스트를 먼저 돌릴지, 어떤 파일은 건드리면 안 되는지, 대량 삭제는 승인 없이 금지인지, PR 설명에는 어떤 증거를 넣어야 하는지 같은 규칙이 모델 행동을 직접 바꿉니다.

그래서 최근 개발 조직에서 중요해지는 흐름이 Repo-local Agent Policy입니다. 이는 단순히 AGENTS.md, CLAUDE.md, .github/copilot-instructions.md 같은 파일을 하나 더 만드는 이야기가 아닙니다. 저장소별 개발 규칙을 에이전트 런타임이 읽고 따르는 계약으로 만들고, CI와 리뷰 시스템이 그 계약을 확인하게 만드는 방향입니다. 이 흐름은 Tool Permission Manifest, Context Contract Registry, Test Evidence Pipeline, Agent Sandbox Egress Policy와 같은 문제의식에서 나옵니다. 모델이 더 똑똑해져도 저장소의 작업 경계가 흐리면 결과는 불안정합니다.

이 글에서 얻는 것

• repo-local agent policy가 단순 스타일 가이드와 어떻게 다른지 이해할 수 있습니다.
• 에이전트에게 반드시 알려야 할 허용 작업, 금지 작업, 검증 게이트, 보고 형식을 나눌 수 있습니다.
• 정책 파일이 길어지거나 도구별로 갈라질 때 생기는 drift를 줄이는 운영 방식을 잡을 수 있습니다.
• AI 코딩 자동화를 도입할 때 policy, CI, 리뷰, 감사 로그를 어떤 우선순위로 연결할지 판단할 수 있습니다.

핵심 개념/이슈

1) 에이전트는 팀 컨벤션을 “추측"하면 안 된다

사람 개발자는 저장소를 몇 번 만지면 암묵지를 익힙니다. 어떤 테스트가 느린지, 생성 파일은 어디인지, migration은 누가 승인하는지, 특정 디렉터리는 자동 생성물이므로 직접 수정하면 안 된다는 사실을 주변 맥락으로 배웁니다. 에이전트는 이런 암묵지를 매번 안정적으로 기억하지 못합니다. 컨텍스트에 없으면 추측하고, 추측은 저장소마다 다르게 실패합니다.

Repo-local policy의 목적은 에이전트를 더 많이 통제하는 것이 아니라, 추측해야 하는 영역을 줄이는 것입니다. 좋은 정책은 아래 질문에 짧게 답합니다.

• 이 저장소에서 기본 빌드·테스트 명령은 무엇인가?
• 변경 전 반드시 읽어야 하는 설계 문서나 모듈 경계는 무엇인가?
• 자동 생성 파일, vendored code, lockfile, migration 파일은 어떻게 다뤄야 하는가?
• 삭제, 대량 포맷팅, 외부 전송, credential 접근은 어떤 조건에서 멈춰야 하는가?
• 작업 완료 보고에 테스트 결과, 변경 파일, 남은 위험을 어떻게 써야 하는가?

이런 질문이 문서에 없으면 에이전트는 “일반적인 프로젝트"처럼 행동합니다. 하지만 운영 저장소는 일반적이지 않습니다. 팀의 배포 습관, 보안 경계, 레거시 제약, 비용 구조가 모두 다릅니다.

2) 정책은 프롬프트가 아니라 저장소의 실행 계약이다

많은 팀이 처음에는 agent instruction을 프롬프트처럼 씁니다. “친절하게 답하라”, “좋은 코드를 작성하라”, “테스트를 꼼꼼히 하라” 같은 문장은 나쁘지는 않지만 운영 기준으로는 약합니다. 실행 계약이 되려면 검증 가능한 문장이어야 합니다.

예를 들어 아래처럼 바꾸는 것이 좋습니다.

핵심은 “잘"이 아니라 어떤 조건에서 무엇을 해야 하는가입니다. 정책은 모델의 성격을 바꾸는 글이 아니라, 작업자의 행동을 제한하고 검증하는 계약입니다.

3) repo-local이어야 하는 이유는 저장소마다 위험이 다르기 때문이다

조직 공통 AI 정책은 필요합니다. 하지만 그것만으로는 부족합니다. 결제 서비스, 디자인 시스템, 데이터 파이프라인, 모바일 앱, 문서 사이트는 위험 기준이 다릅니다. 결제 서비스에서는 migration과 정합성 테스트가 중요하고, 디자인 시스템에서는 시각 회귀와 접근성이 중요합니다. 데이터 파이프라인에서는 backfill과 재처리 비용이 핵심이고, 문서 사이트에서는 링크와 frontmatter가 더 중요합니다.

그래서 정책은 두 계층으로 나누는 편이 좋습니다.

1. 조직 공통 정책: 비밀값, 외부 전송, 승인 경계, 감사 로그, 보안 기본값
2. 저장소 로컬 정책: 빌드 명령, 모듈 경계, 테스트 우선순위, 생성물 처리, 리뷰 증거

저장소 로컬 정책은 루트에 하나만 둘 수도 있고, 디렉터리별로 더 좁게 둘 수도 있습니다. 단, 너무 잘게 쪼개면 충돌합니다. 실무에서는 루트 policy 1개, 위험한 하위 영역 policy 2~5개 이내로 시작하는 편이 관리하기 쉽습니다.

4) 정책 drift는 생각보다 빨리 온다

에이전트 지침 파일이 늘어나면 drift가 생깁니다. README에는 npm test라고 되어 있고, CI는 pnpm test를 돌리며, 특정 도구 지침에는 yarn test가 남아 있는 식입니다. 사람은 대충 알아서 맞추지만 에이전트는 다른 명령을 실행할 수 있습니다.

drift를 줄이려면 canonical source를 정해야 합니다. 예를 들어 docs/agent-policy.md를 원본으로 두고, 도구별 instruction 파일은 “이 원본을 읽어라"와 도구 특화 주의점만 담는 방식입니다. 또는 정책을 YAML/JSON처럼 구조화하고 문서 페이지를 생성할 수도 있습니다. 중요한 것은 정책 변경이 코드 변경처럼 리뷰되어야 한다는 점입니다. 정책은 에이전트의 행동을 바꾸므로, 사실상 런타임 설정입니다.

실무 적용

1) 최소 정책은 4개 섹션이면 충분하다

처음부터 거대한 governance 문서를 만들 필요는 없습니다. 오히려 긴 문서는 에이전트 컨텍스트를 낭비하고, 사람이 업데이트하지 않게 됩니다. 최소 정책은 아래 4개 섹션으로 시작할 수 있습니다.

1. 작업 전 읽을 것: 아키텍처 문서, 모듈 경계, API 계약, 최근 migration 주의점
2. 허용/금지 행동: 자동 실행 가능한 명령, 승인 필요한 변경, 절대 출력하면 안 되는 값
3. 검증 게이트: 변경 유형별 테스트, lint, build, link check, screenshot, migration dry-run
4. 완료 보고 형식: 변경 파일, 테스트 결과, 미검증 항목, rollback/후속 작업

숫자 기준도 넣어야 합니다. 예를 들어 “대량 수정 주의"보다 “20개 이상 파일 변경, 500줄 이상 삭제, DB migration, CI workflow, secret provider 변경은 승인 필요"가 낫습니다. “테스트 실행"보다 “10분 안에 끝나는 최소 관련 테스트를 먼저 실행하고, 전체 테스트가 20분 이상이면 변경 모듈 테스트와 이유를 보고"가 낫습니다.

2) 정책을 CI와 PR 템플릿에 연결한다

정책 파일은 읽히기만 해서는 약합니다. 최소한 CI와 PR 템플릿이 정책의 일부를 확인해야 합니다.

• frontmatter, 링크, generated file 수정 금지처럼 정적 검증 가능한 항목은 CI로 확인
• migration, workflow, secret 관련 변경은 CODEOWNERS 또는 label gate로 reviewer 지정
• PR template에 “policy 준수 증거” 항목 추가
• 에이전트가 남긴 테스트 로그와 실패 이유를 review evidence로 보존
• 정책 파일 변경 자체는 platform 또는 repo owner 리뷰 필수로 지정

이 구조는 AI PR Review Backlog OS와도 연결됩니다. 에이전트가 PR을 많이 만들수록 리뷰어는 코드 전체를 처음부터 읽기보다, 정책 준수 증거와 위험 변경을 먼저 봐야 합니다. 정책은 리뷰 병목을 줄이는 색인 역할을 합니다.

3) 위험 행동은 allowlist보다 escalation rule로 관리한다

모든 위험 행동을 영구 금지하면 자동화가 쓸모없어집니다. 반대로 모두 허용하면 사고가 납니다. 좋은 정책은 위험 행동을 escalation rule로 나눕니다.

예시는 아래와 같습니다.

이 기준은 Agent Sandbox Egress Policy와 같은 방향입니다. 에이전트에게 필요한 능력을 주되, 외부 효과와 권한 확대는 별도 게이트로 빼야 합니다.

4) 정책 준수율을 관측한다

정책은 만들고 끝이 아닙니다. 에이전트가 실제로 지키는지 봐야 합니다. 모든 것을 자동 측정할 필요는 없지만, 최소한 아래 지표는 운영 회고에 유용합니다.

• 에이전트 PR 중 필수 테스트 증거가 빠진 비율
• 정책 위반으로 reviewer가 되돌린 PR 비율
• 승인 필요 action을 사전 보고하지 않고 수행하려 한 횟수
• 정책 파일 변경 후 관련 실패가 줄었는지 여부
• 도구별 instruction drift 발견 건수
• 정책 길이와 실제 준수율의 관계

출발 기준은 보수적으로 잡습니다. 에이전트 PR의 10% 이상에서 같은 정책 위반이 반복되면 모델 문제가 아니라 policy 또는 CI gate가 약한 것입니다. 반대로 정책 위반은 없지만 PR 처리 시간이 계속 늘면 정책이 너무 길거나 리뷰 증거 형식이 비효율적일 수 있습니다.

트레이드오프/주의점

Repo-local policy의 가장 큰 위험은 문서 비대화입니다. 모든 과거 사고와 모든 선호를 넣으면 에이전트가 중요한 규칙을 놓칩니다. 정책은 짧고 강해야 합니다. 권장 길이는 루트 정책 기준 150~300줄 이내, 하위 디렉터리 정책은 80줄 이내입니다. 더 길어지면 문서 본문과 실행 규칙을 분리하는 편이 낫습니다.

두 번째 위험은 도구 종속입니다. 특정 에이전트만 읽는 파일에 모든 정책을 넣으면 다른 도구는 같은 규칙을 모릅니다. 팀이 여러 도구를 쓴다면 canonical policy와 adapter를 분리하세요. 공통 정책은 저장소 표준 위치에 두고, 도구별 파일은 “이 파일을 우선 읽고, 충돌 시 공통 정책을 따른다” 정도로 얇게 유지합니다.

세 번째는 보안 착시입니다. 정책에 “비밀값 출력 금지"라고 적었다고 비밀값 유출이 막히는 것은 아닙니다. 실제 방어는 권한 분리, secret masking, egress 제한, 감사 로그, 승인 흐름이 함께 있어야 합니다. 정책은 중요한 시작점이지만 마지막 방어선은 아닙니다.

마지막으로 정책 변경은 제품 변경처럼 다뤄야 합니다. “테스트를 생략해도 된다"는 한 줄, “외부 API 호출 허용"이라는 한 줄이 자동화의 행동을 바꿉니다. 정책 파일은 가볍게 보이지만 실제로는 개발 런타임의 control plane입니다.

체크리스트 또는 연습

도입 체크리스트

• 저장소 루트에 에이전트가 반드시 읽을 canonical policy 위치가 있는가?
• 정책에 허용 작업, 승인 필요 작업, 금지 작업이 분리되어 있는가?
• 변경 유형별 최소 검증 게이트가 명령어 수준으로 적혀 있는가?
• 삭제 20개 파일 이상, 500줄 이상 제거, migration, secret, CI 권한 변경 같은 숫자 기준이 있는가?
• 정책 변경 자체가 CODEOWNERS 또는 필수 리뷰 대상인가?
• 도구별 instruction 파일이 서로 다른 명령을 가리키지 않는가?
• PR template에 테스트 증거, 미검증 항목, rollback 고려가 포함되어 있는가?
• 외부 전송과 권한 확대는 dry-run과 실제 실행이 분리되어 있는가?
• 정책 위반이 반복될 때 CI gate로 올릴 항목과 문서로 남길 항목을 구분했는가?
• 정책이 300줄을 넘는다면 실행 규칙과 배경 설명을 분리했는가?

연습

지금 팀의 저장소 하나를 골라 에이전트에게 맡길 수 있는 작업 5개와 맡기면 안 되는 작업 5개를 적어보세요. 그리고 각 작업에 대해 아래 네 가지를 채웁니다.

1. 작업 전 반드시 읽어야 할 파일
2. 수정 가능한 경로와 금지 경로
3. 완료 전 실행해야 할 검증 명령
4. 승인 없이 하면 안 되는 외부 효과

이 표를 만들면 repo-local policy의 초안이 거의 완성됩니다. 목표는 에이전트를 믿지 않는 것이 아니라, 믿을 수 있는 작업 단위를 작게 만들고 그 경계를 저장소 안에 남기는 것입니다. AI 코딩 시대의 좋은 저장소는 코드만 읽기 쉬운 저장소가 아니라, 자동화된 작업자가 안전하게 일할 수 있는 저장소입니다.