ContextCov: Deriving and Enforcing Executable Constraints from Agent Instruction Files

1. 문제 정의 (Problem Statement)

대형 언어 모델 (LLM) 기반의 자율 에이전트들이 소프트웨어 엔지니어링 작업을 수행함에 따라, 개발자들은 AGENTS.md 와 같은 자연어 기반의 에이전트 지시문 (Agent Instructions) 을 사용하여 프로젝트의 코딩 규칙, 도구, 아키텍처 경계를 정의합니다. 그러나 이러한 지시문은 수동적인 텍스트일 뿐이며, 에이전트가 실행하는 과정에서 다음과 같은 심각한 문제가 발생합니다.

• 컨텍스트 드리프트 (Context Drift): 에이전트가 지시문을 무시하거나, 레거시 코드 패턴을 모방하거나, 컨텍스트 윈도우의 제한으로 인해 지시된 규칙에서 벗어나는 현상입니다.
• 현실 격차 (Reality Gap): 에이전트가 "해야 할 일"과 "실제로 수행한 일" 사이의 불일치입니다. 에이전트는 종종 시스템 지시문보다 즉각적인 작업 완성을 우선시하거나, 레거시 코드의 잘못된 패턴을 학습하여 이를 재생산합니다.
• 수동적 문서의 한계: 기존 지시문은 실행 가능한 명세가 아니므로, 위반 사항이 발생하더라도 실시간으로 감지되지 않고 기술 부채로 누적됩니다.

2. 방법론 (Methodology)

ContextCov는 수동적인 에이전트 지시문을 능동적이고 실행 가능한 가드레일 (Guardrails) 로 변환하는 프레임워크입니다. 이 프레임워크는 크게 제약 조건 추출 (Extraction) 과 런타임 강제 (Enforcement) 두 단계로 구성됩니다.

가. 제약 조건 추출 및 합성 (Constraint Extraction & Synthesis)

1. 계층적 경로 인식 슬라이싱 (Hierarchical Path-Aware Slicing):
   • 마크다운 지시문 파일을 AST(추상 구문 트리) 로 파싱합니다.
   • 단순한 텍스트 추출이 아닌, 헤더 계층 구조 (Heading hierarchy) 를 유지하며 각 제약 조건의 범위 (Scope) 를 명확히 합니다. (예: "백엔드 테스트" 하위의 "pytest 사용" 규칙을 전체 프로젝트에 적용하지 않도록 구분)
   • LLM 을 사용하여 맥락이 포함된 명확한 제약 조건 문장으로 재작성 (Refinement) 합니다.
2. 도메인 라우팅 및 코드 합성 (Domain-Routed Policy Synthesis):
   • 추출된 제약 조건을 4 가지 도메인으로 분류하여 각각 전문화된 코드 생성기 (Expert Generator) 로 전달합니다.
     • 프로세스 (Process): 빌드 명령어, 패키지 관리자 등 (예: npm 금지).
     • 소스 (Source): 코딩 스타일, 네이밍 컨벤션, 금지된 패턴 (예: 화살표 함수의 불필요한 괄호).
     • 아키텍처 결정론적 (Architectural Deterministic): 모듈 의존성, 레이어 위반, 사이클 감지.
     • 아키텍처 의미론적 (Architectural Semantic): 설계 원칙, 캡슐화 위반 등 LLM 판단이 필요한 복잡한 규칙.
   • 생성된 결과는 실행 가능한 Python 체크 코드로 변환되어 JSON 파일에 저장됩니다.

나. 런타임 강제 (Runtime Enforcement)

생성된 체크 코드는 에이전트 실행 중 실시간으로 적용됩니다.

1. 프로세스 인터셉터 (Process Interceptor):
   • $PATH 조작을 통해 쉘 명령어 (예: npm, yarn) 를 가로채는 래퍼 스크립트 (Shim) 를 사용합니다.
   • 금지된 명령어가 실행되기 직전에 차단하고 에이전트에게 위반 사유를 피드백합니다.
2. 범용 정적 린터 (Universal Static Linter):
   • Tree-sitter를 사용하여 소스 코드를 파싱하고 AST 를 분석합니다.
   • 다중 언어 (Python, TypeScript, Go, Rust 등) 를 지원하며, 정해진 패턴 위반을 파일/라인 단위로 감지합니다.
3. 아키텍처 유효성 검사기 (Architectural Validator):
   • NetworkX를 사용하여 의존성 그래프를 구성하고, 레이어 경계 위반이나 순환 의존성을 탐지합니다.
4. 의미론적 유효성 검사 (Semantic Architectural Validator):
   • 정적 분석으로 판단하기 어려운 설계 원칙 위반 (예: 다른 컴포넌트의 스토리지 키 직접 접근) 에 대해 LLM-as-a-Judge 방식을 사용합니다.
   • 이는 하드 차단이 아닌 경고 (Warning) 로 처리하여 인간 검토를 유도합니다.

3. 주요 기여 (Key Contributions)

1. 컨텍스트 드리프트의 체계화: 에이전트 중심 소프트웨어 엔지니어링에서 발생하는 위반 유형을 분석하고, 이를 해결하기 위한 분류 체계를 제시했습니다.
2. 계층적 제약 추출 알고리즘: 마크다운 문서의 계층적 구조를 보존하며 의미 있는 범위를 가진 실행 가능한 제약 조건을 추출하는 알고리즘을 개발했습니다.
3. ContextCov 아키텍처: 도메인별 전문화된 코드 합성 (Process, Source, Architectural) 과 다중 레이어 런타임 강제 메커니즘을 통합한 프레임워크를 제안했습니다.
4. 대규모 실증 평가: 723 개의 오픈소스 리포지토리를 대상으로 한 평가를 통해 시스템의 유효성을 입증했습니다.

4. 평가 결과 (Evaluation Results)

• 데이터셋: 723 개의 GitHub 오픈소스 리포지토리 (별점 기준 상위 선정).
• 추출 및 합성 품질:
  • 총 46,316 개의 실행 가능한 체크를 생성했습니다.
  • 구문 유효성 (Syntax Validity) 이 99.997% (34,373/34,374) 로 매우 높았으며, 이는 생성된 코드가 즉시 실행 가능함을 의미합니다.
  • 도메인별 분포: Source(28%), Process(26%), Architectural Semantic(26%), Architectural Deterministic(20%).
• 위반 감지 능력:
  • 생성된 체크 중 24% (10,927 개) 가 실제 리포지토리에서 최소 한 번 이상의 위반을 감지했습니다.
  • 총 50 만 건 이상의 위반이 발견되었으며, 81% 의 리포지토리에서 적어도 하나의 위반이 존재했습니다.
  • 위반은 소수 (4%) 의 체크에서 대다수 (80%) 를 차지하는 긴 꼬리 (Long-tail) 분포를 보였습니다.

5. 의의 및 시사점 (Significance)

• 문서화 (Documentation) 의 패러다임 전환: 에이전트 지시문을 단순한 설명서 (Descriptive) 가 아닌 실행 가능한 명세 (Executable Specification) 로 재정의합니다. 이는 문서와 코드가 함께 진화해야 함을 의미합니다.
• 에이전트 피드백 루프: 에이전트가 규칙 위반으로 차단될 때, 이를 학습하여 지시문 자체를 더 명확하게 수정하거나 에이전트의 행동을 교정하는 피드백 루프를 형성합니다.
• 실제적 안전성 보장: 보안 샌드박스와는 달리, ContextCov 는 의도는 좋지만 환각 (Hallucination) 이나 실수로 인해 리포지토리의 무결성을 해치는 에이전트의 행동을 방지합니다.
• 해석 가능성 (Interpretability): 자연어 지시가 어떻게 구체적인 코드 체크 (Tree-sitter 쿼리, 그래프 알고리즘 등) 로 변환되었는지 개발자가 직접 검증할 수 있어, 프롬프트 엔지니어링의 투명성을 높입니다.

결론적으로, ContextCov 는 자율 에이전트 시대에 발생하는 '현실 격차'를 해소하고, 프로젝트의 아키텍처와 코딩 표준을 자동으로 준수하도록 보장하는 필수적인 자동화 레이어를 제공합니다.