Codified Context: Infrastructure for AI Agents in a Complex Codebase

1. 문제 정의 (Problem)

LLM 기반의 에이전트 코딩 어시스턴트 (GitHub Copilot, Cursor, Claude Code 등) 는 광범위한 프로그래밍 지식을 보유하고 있지만, 지속적인 기억 (Persistent Memory) 이 부재하다는 치명적인 한계가 있습니다.

• 세션 간 일관성 상실: 각 세션이 시작될 때마다 이전 세션의 맥락, 프로젝트 관례 (Conventions), 과거 실수를 잊어버립니다.
• 확장성 부족: 단일 파일 매니페스트 (.cursorrules, CLAUDE.md 등) 는 소규모 프로젝트에는 효과적이지만, 10 만 줄 이상의 대규모 코드베이스에서는 정보가 과부하되거나 누락되어 에이전트가 반복적인 실수를 저지르게 됩니다.
• 지식 전달의 공백: 에이전트에게 프로젝트가 어떻게 작동하는지, 어떤 패턴을 따라야 하며 무엇을 피해야 하는지를 반복적이고 신뢰할 수 있는 형태로 전달하는 것은 여전히 해결되지 않은 상호작용 설계 문제입니다.

2. 방법론 (Methodology)

저자는 108,000 줄 규모의 C# 분산 시스템 (MonoGame 및 ECS 라이브러리 기반의 실시간 멀티플레이어 시뮬레이션) 을 개발하는 과정에서 **3 단계 계층 구조 (Three-tier Architecture)**를 가진 '코디피드 컨텍스트 인프라 (Codified Context Infrastructure)'를 설계하고 구현했습니다. 이 인프라는 문서를 단순한 기록이 아닌 AI 에이전트가 의존하는 **부하를 견디는 인프라 (Load-bearing Artifacts)**로 취급합니다.

3 단계 계층 구조:

1. Tier 1: 프로젝트 헌법 (Project Constitution, Hot Memory)

   • 특징: 모든 AI 세션에 자동으로 로드되는 단일 Markdown 파일 (약 660 줄).
   • 내용: 코드 품질 표준, 네이밍 컨벤션, 빌드 명령어, 아키텍처 패턴 요약, 일반 작업 체크리스트, 알려진 실패 모드, 그리고 특수 에이전트로 작업을 라우팅하는 **오케스트레이션 프로토콜 (Trigger Tables)**을 포함합니다.
   • 목적: "무엇을 항상 따라야 하는가?"에 대한 규칙을 정의하여 컨텍스트 윈도우를 효율적으로 사용합니다.

2. Tier 2: 전문화된 에이전트 (Specialized Agents, Domain Experts)

   • 특징: 코드베이스의 특정 영역을 담당하는 19 개의 도메인 전문가 에이전트 (총 약 9,300 줄).
   • 구조: 8 개의 고기능 에이전트 (네트워킹, 아키텍처 등) 와 11 개의 표준 기능 에이전트로 구성됩니다.
   • 지식 임베딩: 각 에이전트 명세서의 50% 이상은 행동 지침이 아닌 프로젝트 도메인 지식 (코드 팩트, 공식, 패턴, 실패 모드) 으로 채워져 있습니다. 이는 에이전트가 복잡한 도메인에서 즉각적인 맥락을 갖도록 하여 오류를 줄입니다.
   • 동작: Tier 1 의 트리거 테이블에 따라 파일 변경 신호에 기반하여 자동으로 호출됩니다.

3. Tier 3: 코디피드 컨텍스트 베이스 (Codified Context Base, Cold Memory)

   • 특징: 34 개의 서브시스템별 명세서 문서 (총 약 16,250 줄).
   • 내용: AI 소비를 위해 작성된 구조화된 문서 (파일 경로, 매개변수, 예상 동작 명시).
   • 검색: MCP (Model Context Protocol) 검색 서버를 통해 온디맨드 (On-demand) 로 검색 및 조회됩니다. 키워드 매칭을 기반으로 하며, 필요 시 관련 문서를 에이전트에 제공합니다.

3. 주요 기여 (Key Contributions)

1. 계층적 아키텍처 제안: 단일 파일 매니페스트를 확장하여 도메인 전문가 에이전트, 자동 라우팅 트리거 테이블, 핫/콜드 메모리 분리 (Hot/Cold Memory Separation) 를 포함한 다단계 지식 조직 구조를 제시했습니다.
2. 정량적 평가 및 사례 연구: 283 개의 개발 세션 (70 일간) 에 걸친 인프라 성장 지표, 상호작용 패턴 (2,801 개의 인간 프롬프트, 1,197 개의 에이전트 호출, 16,522 개의 에이전트 턴) 을 분석하고, 4 가지 관찰 사례 연구를 통해 컨텍스트가 세션 간 어떻게 전파되어 실패를 방지하는지 입증했습니다.
3. 오픈소스 프레임워크 공개: 대표 에이전트 명세, MCP 검색 서버, 예시 문서, 부트스트래핑을 위한 팩토리 에이전트, 분석 스크립트 등을 포함한 전체 인프라를 오픈소스로 공개했습니다.

4. 결과 (Results)

• 인프라 규모: 108,256 줄의 C# 소스 코드에 비해 컨텍스트 인프라는 약 26,200 줄 (코드 대비 24.2%) 에 달했습니다. 이는 프로젝트의 복잡성과 도메인 특성 (실시간 분산 시스템) 을 반영합니다.
• 상호작용 효율성:
  • 인간 프롬프트의 80% 이상이 100 단어 미만이었으며, 사전 로드된 컨텍스트가 프롬프트 내 설명 필요성을 줄였음을 시사합니다.
  • 에이전트 호출 중 57% 가 프로젝트 특화 전문가 에이전트였으며, 가장 빈번하게 사용된 것은 코드 리뷰어와 네트워크 프로토콜 디자이너였습니다.
• 사례 연구 성과:
  1. 저장 시스템 (Save System): 74 개의 독립 세션에서 저장 시스템 명세서를 참조하여 데이터 손상이나 버그 없이 일관된 지속성 (Persistence) 동작을 구현했습니다.
  2. UI 동기화 (UI Sync Routing): 이전 세션의 실수를 명세서로 포착하여, 다음 UI 기능 구현 시 시행착오 없이 올바른 전달 패턴을 적용했습니다.
  3. 드롭 시스템 (Drop System): 문서가 없다는 'Null 결과'를 감지하여 리팩토링 전에 명세서를 먼저 생성함으로써, 이후 모든 하위 작업의 속도를 가속화했습니다.
  4. 결정적 RNG (Deterministic RNG): 에이전트의 내장 도메인 지식 (결정성 이론) 을 활용하여 5 번의 시도에서 발견되지 않았던 미세한 동기화 버그를 해결했습니다.

5. 의의 및 결론 (Significance & Conclusion)

• 문서를 인프라로 재정의: 이 연구는 문서를 단순한 기록이 아니라 AI 에이전트가 올바른 코드를 생성하기 위해 의존하는 살아있는 인프라로 간주합니다.
• 규모 확장성: 단일 개발자가 70 일의 부분 시간 근무로 10 만 줄 이상의 복잡한 분산 시스템을 AI 에이전트만을 사용하여 구축할 수 있게 했습니다.
• 도메인 전문가를 위한 도구: 소프트웨어 엔지니어링 전문 지식이 부족한 도메인 전문가 (예: 화학자) 가 AI 에이전트를 통해 전문 영역을 넘어 소프트웨어를 구축할 수 있는 새로운 패러다임을 제시합니다.
• 유지보수 비용: 명세서 업데이트는 코드 변경과 함께 수행되며, 주당 약 1~2 시간의 유지보수 오버헤드가 발생하지만, 이는 에이전트의 일관성과 오류 방지를 통해 상쇄됩니다.

이 논문은 대규모 AI 지원 소프트웨어 개발에서 지식 관리의 구조화가 에이전트의 성능과 신뢰성을 결정하는 핵심 요소임을 입증하며, 향후 AI 에이전트 아키텍처 설계에 중요한 기준을 제시합니다.