린터(Linter)처럼 코드베이스 내 AI 에이전트를 관리하기

이 글에서는 소프트웨어 개발 프로젝트에서 AI 에이전트를 관리하기 위한 프레임워크인 **Agent Governance as Code (코드로서의 에이전트 거버넌스)**를 소개합니다. 이 접근 방식은 Infrastructure as Code (IaC, 코드로서의 인프라) 및 Policy as Code (PaC, 코드로서의 정책)의 원칙을 에이전트의 행동에 적용하여, 에이전트가 정의된 경계 내에서 작동하고 그 행동이 감사(auditable) 및 제어(controllable) 가능하도록 보장합니다.

기본 개념: Infrastructure as Code 및 Policy as Code와 유사하게, 이 글에서는 소프트웨어 개발 프로젝트에서 AI 에이전트를 관리하기 위한 프레임워크인 Agent Governance as Code를 소개합니다. 이 접근 방식은 Infrastructure as Code 및 Policy as Code의 원칙을 에이전트의 행동에 적용하여, 에이전트가 정의된 경계 내에서 작동하고 그 행동이 감사 가능하며 제어 가능하도록 보장합니다.

1. 서론 — 에이전트의 자유와 코드베이스 안전성 사이의 긴장

ESLint는 .js 파일을 스캔하여 console.log가 보이면 경고를 보냅니다. Biome은 any 타입을 발견하면 컴파일을 중단합니다. 이러한 도구들은 인간이 작성한 코드를 감사하고 정의된 규칙 내에 유지합니다.

하지만 AI 에이전트가 코드를 작성할 때 — 단 몇 초 만에, 수천 줄의 규모로 작성할 때 — 누가 그 감사를 수행할까요?

이 질문은

3. 4계층 아키텍처 (Four-Layer Architecture)

╔══════════════════════════════════════════════════════════════╗
║                    AI AGENT REQUEST                          ║
╚══════════════════════════╦═══════════════════════════════════╝
...

각 계층은 독립적으로 작동할 수 있지만, 함께 모여 **심층 방어 (defense in depth)**를 구축합니다.

4. 계층 1 — AGENTS.md: 사람이 읽을 수 있는 규칙 세트 (Human-Readable Rule Set)

왜 별도의 파일인가?

시스템 프롬프트 (system prompt)에 내장된 규칙은 버전 관리 (versioning)를 할 수 없고, PR 리뷰 (PR review)를 거칠 수 없으며, 차이점 비교 (diff)를 할 수 없습니다. AGENTS.md는 저장소 (repository) 내부에 존재하므로, 모든 변경 사항을 관찰하고 되돌릴 (revert) 수 있습니다.

핵심 구조 (Core Structure)

# [Project Name] Agent Rules

## 1) 시작 조건 (Hard Gate)
...

예외 사례: 여러 개의 AGENTS.md 파일

모노레포 (monorepo) 설정에서는 각 패키지/서비스가 자체적인 AGENTS.md를 가질 수 있습니다. 에이전트가 어떤 규칙을 우선시해야 하는지는 명시적으로 정의되어야 합니다:

/
├── AGENTS.md                    ← 전역 규칙 (Global rules)
├── packages/
...

전역 정책 (global policy) 충돌이 발생하는 경우, 가장 제한적인 규칙이 적용됩니다.

5. 계층 2 — AGENTS.policy.json: 기계가 읽을 수 있는 제약 조건 (Machine-Readable Constraints)

AGENTS.md는 사람과 에이전트가 모두 읽을 수 있는 텍스트 문서입니다. AGENTS.policy.json은 CI/CD 시스템, 자동화 훅 (automation hooks), 그리고 다양한 에이전트 런타임 (agent runtimes)에 의해 프로그래밍 방식으로 읽히고 검증될 수 있는 규칙 형식입니다.

전체 스키마 (Full Schema)

{
  "$schema": "https://your-org.com/schemas/agents-policy/v2.json",
  "version": 2,
...

예외 사례: 정책 상속 (Policy Inheritance)

대규모 조직에서는 각 팀이 별도의 규칙을 가질 수 있지만, 모든 규칙은 "조직 수준 (org-level)" 정책으로부터 상속받습니다:

{
  "extends": "https://policies.your-org.com/base-policy/v2.json",
  "version": 2,
...

예외 사례: 시간 기반 정책 (Temporal Policies)

{
  "temporal_constraints": {
    "freeze_windows": [
...

예외 사례: 역할 기반 제약 조건 (RBAC)

{
  "agent_roles": {
    "junior-agent": {
...

6. 계층 3 — agent-guard.sh: 포괄적인 런타임 강제 적용 (Comprehensive Runtime Enforcement)

이곳이 모든 계층이 실제로 강제 적용되는 지점입니다. 아래 스크립트는 모든 예외 상황(edge cases)을 다루는 프로덕션 준비 완료(production-ready)된 포괄적인 버전입니다:

(전체 주석이 달린 스크립트는 위의 터키어 섹션을 참조하세요 — 로직은 동일하며 주석만 다릅니다.)

스크립트가 수행하는 주요 검사 항목:

검사 항목	검증 내용	실패 시
필수 파라미터 (Required parameters)	`--issue`, `--status` 존재 여부	`exit 1`
...

우회 방법 (Bypass Methods)

# 방법 1: 환경 변수 (로컬 개발 / 긴급 상황)
AGENT_BYPASS=1 scripts/agent-guard.sh --issue PROJ-123 --status "Hotfix"

...

7. 계층 4 — PR / MR 템플릿 (PR / MR Template)

## 🤖 에이전트 준수 체크리스트 (Agent Compliance Checklist)

### 전제 조건 (Preconditions)
...

8. 생태계 비교 (Ecosystem Comparison)

도구 / 방법	강제 적용 수준 (Enforcement Level)	버전 관리 가능 (Versionable)	CI 통합 (CI Integration)	에이전트 무관 (Agent-Agnostic)	우회 메커니즘 (Bypass Mechanism)
이 방식 (AGENTS.md + policy.json + guard.sh)	저장소 (Repository)	✅	✅	✅	✅
...

핵심 차별점: 이 방식의 모든 계층은 저장소 내부에 존재합니다. 모든 에이전트 시스템 (Claude, Gemini, Codex, Devin, OpenCode, Cursor)은 동일한 정책 파일(policy file)을 읽고 동일한 bash 스크립트를 실행할 수 있습니다.

10. 위협 모델 (Threat Model)

모든 보안 시스템은 어떤 위협을 해결하는지, 그리고 — 똑같이 중요한 점으로서 — 어떤 위협을 해결하지 않는지를 명시적으로 문서화해야 합니다. 이러한 투명성이 없다면 시스템은 잘못된 보안 의식(false sense of security)을 심어줄 수 있습니다.

이 시스템은 무엇으로부터 보호하는가?

위협	포함 여부	비고
범위 확장 (Scope creep) (범위 외 파일 변경)	✅ 전체	`--files` 범위 검사 + 보호된 경로 목록
...

범위 외 위협에 대한 권장 보완 도구

이 시스템 (This system)              보완 시스템 (Complementary system)
──────────────────────   ──────────────────────────────────────
범위 제어 (Scope control)         +  Semgrep / CodeQL (로직 버그 탐지)
...

기업용 참고 사항 (Enterprise note): 이 표는 규제 대상인 핀테크, 헬스케어 및 국방 분야의 컴플라이언스 감사(SOC 2, ISO 27001)에서 **통제 증거 참조 (control evidence reference)**로 직접 사용할 수 있습니다.

11. 역량 및 도구 거버넌스 (Capability & Tool Governance)

문제점: 현대적 에이전트의 리스크는 코드 출력물이 아닌 도구 사용에서 발생한다

전통적인 사고방식:

리스크 (Risk) = 나쁜 코드

현대적 현실:

리스크 (Risk) = 도구 접근 권한 (Tool access) × 권한 범위 (Permission breadth)

만약 에이전트가 rm -rf /를 실행할 수 있다면, 에이전트가 생성하는 코드의 품질은 무의미해집니다.

만약 에이전트가 psql production -c "DROP TABLE users"를 실행할 수 있다면, 사후에 모든 정책 인프라가 무용지물이 됩니다.

이러한 이유로, 도구 제한 (tool restriction)은 정책의 네 번째 차원입니다.

역량 거버넌스 스키마 (Capability Governance Schema)

{
  "capabilities": {
    "filesystem": {
...

역량 강제 수준 (Capability Enforcement Levels)

레벨 0 — 제한 없음 (Unrestricted) (권장되지 않음)
  에이전트가 무엇이든 할 수 있습니다. 어떤 운영 시스템 (production system)에서도 수용되어서는 안 됩니다.

...