AI 에이전트 시스템 아키텍처 개선: 640줄 모놀리식 설정을 45줄로 줄인 방법

## 들어가며 대규모 AI 에이전트 시스템을 운영하다 보면 각 에이전트마다 공통 설정과 지침을 관리하는 일이 점점 복잡해집니다. 특히 수십 개의 에이전트가 동일한 640줄짜리 설정 파일을 공유한다면, 유지보수는 악몽이 될 수 있습니다. 이 글에서는 모놀리식 설정 파일을 모듈화된 45줄 라우팅 템플릿으로 전환하여 관리 효율성을 93% 향상시킨 경험을 공유합니다. ## 문제 상황: 모놀리식 설정의 한계 ### 기존 아키텍처의 문제점 - **640줄의 공통 설정 파일**: 모든 에이전트가 동일한 거대한 설정 파일 사용 - **불필요한 정보 로딩**: 특정 작업에 필요 없는 설정까지 매번 로드 - **수동 봇 생성**: 새 에이전트 추가 시 6단계의 수동 작업 필요 - **메모리 부재**: 과거 실패 사례나 의사결정 이력 추적 불가 ## 해결책: Progressive Disclosure 패턴 ### 1. 모듈 시스템 도입 7개의 독립적인 모듈로 분리했습니다: - **deploy**: 배포 관련 지침 - **comms**: 통신 프로토콜 - **infra**: 인프라 설정 - **safety**: 안전 가이드라인 - **remote-worker**: 원격 작업 처리 - **memory**: 메모리 관리 - **sub-agents**: 서브 에이전트 관리 ```markdown # Agent Routing Template ## Task Keywords → Module Mapping - deploy, 배포 → modules/deploy.md - network, API → modules/comms.md - docker, k8s → modules/infra.md ``` ### 2. 작업 기반 동적 로딩 에이전트는 작업 키워드를 분석하여 필요한 모듈만 로드합니다: ```python def load_modules(task_description): keywords = extract_keywords(task_description) modules = [] if any(k in keywords for k in ['deploy', '배포']): modules.append('deploy.md') if any(k in keywords for k in ['docker', 'k8s']): modules.append('infra.md') return modules ``` ### 3. 에피소딕 메모리 시스템 JSONL 형식으로 3가지 메모리 파일 관리: ```jsonl {"schema": ["timestamp", "task", "decision", "rationale"]} {"timestamp": "2026-03-15T09:30:00", "task": "api-deployment", "decision": "use-blue-green", "rationale": "zero-downtime required"} ``` - **decisions.jsonl**: 의사결정 이력 - **failures.jsonl**: 실패 사례와 해결책 - **experiences.jsonl**: 일반 작업 경험 ### 4. 구조화된 데이터 관리 ```yaml # services.yaml 예시 services: - id: api-gateway port: 8080 dependencies: [auth-service, db-proxy] - id: auth-service port: 8081 dependencies: [redis-cache] ``` ## 구현 결과 | 지표 | 개선 전 | 개선 후 | 개선율 | |------|---------|---------|--------| | 공통 설정 크기 | 640줄 | 45줄 | 93% 감소 | | 봇 생성 단계 | 6단계(수동) | 1명령어 | 83% 감소 | | 메모리 구조 보유 봇 | 0개 | 전체 | 100% 향상 | ## 실용적인 적용 방법 ### Step 1: 설정 파일 분석 현재 설정 파일에서 카테고리별로 그룹화 가능한 섹션 식별 ### Step 2: 모듈 분리 각 카테고리를 독립적인 파일로 분리 (예: auth.md, logging.md) ### Step 3: 라우팅 템플릿 작성 키워드 기반 모듈 매핑 로직 구현 ### Step 4: 자동화 도구 개발 봇 생성, 설정 동기화를 위한 CLI 도구 개발 ## 핵심 교훈 1. **Progressive Disclosure**: 필요한 정보만 필요할 때 로드 2. **Schema-First 메모리**: 첫 줄에 스키마 선언으로 데이터 일관성 확보 3. **자동화 우선**: 수동 작업은 스크립트로 전환 4. **구조화된 데이터**: YAML/JSONL로 기계 가독성과 사람 가독성 모두 확보 ## 마치며 대규모 AI 에이전트 시스템에서 설정 관리는 성능과 직결됩니다. 모놀리식 접근에서 모듈화된 아키텍처로 전환함으로써, 유지보수성과 확장성을 크게 개선할 수 있었습니다. 다음 단계로는 메모리 시스템의 자동 학습 기능 추가와 모듈 간 의존성 최적화를 계획하고 있습니다. 여러분의 AI 시스템은 어떤 설정 관리 전략을 사용하고 계신가요?