0. 왜 「AI 에이전트 군단」인가

「ChatGPT에게 코드를 작성하게 하는 것」만으로는 프로덕션 품질의 코드가 탄생하지 않습니다.

리뷰, 테스트, 보안 검사, 요구사항 명확화——인간 개발자가 당연하게 수행하는 일들을 AI 개발에서도 실현하기 위해서는 전문화된 에이전트의 협력이 필요합니다.

NexusCore는 14개의 전문 에이전트가 소프트웨어 개발 라이프사이클(Software Development Lifecycle) 전체를 자율적으로 실행하는 오픈 소스 프레임워크입니다.

• 235개의 Python 모듈, 4624개의 테스트 케이스
• 8개의 LLM 프로바이더를 통합하는 태스크 기반 라우터(Task-based Router)
• 2단계 품질 게이트 (정적 분석 + 뮤테이션 테스트)
• Constitutional AI에 의한 거버넌스 자동화

이 기사에서는 NexusCore의 아키텍처 설계와 구현상의 노하우를 해설합니다.

1. 시스템 전체 아키텍처

NexusCore는 5개의 레이어로 구성되어 있습니다.

레이어의 책임

레이어	역할	대표 모듈
Interface	사용자와의 접점	api/ , webapp/ , ui/
Orchestration	에이전트의 조정 및 상태 관리	orchestrator/ , core/
Agent	전문 영역의 자율 실행	agents/ (14개 모듈)
Infrastructure	LLM · 품질 · 거버넌스 기반	llm/ , guard/ , npe/
Provider	각 LLM API 호출	llm/providers/ (8종)

포인트: 각 레이어는 상위 레이어에만 의존하며, 하위 레이어의 구현 상세를 알지 못합니다. 이를 통해 LLM 프로바이더의 추가 및 교체가 상위 레이어에 영향을 주지 않습니다.

2. 멀티 에이전트 협력 메커니즘

Orchestrator에 의한 페이즈 관리

NexusCore의 개발 플로우는 Orchestrator가 페이즈(Phase) 단위로 에이전트를 기동합니다.

Authority Runner — 권한 레벨에 의한 실행 제어

에이전트의 자율도를 3단계로 제어합니다:

레벨	이름	동작	용도
0	HUMAN_CONTROLLED	각 페이즈에서 인간의 승인 필수	운영 환경
1	PARTIALLY_AUTONOMOUS	저위험 변경은 자동, 고위험은 승인	스테이징 환경
2	FULLY_AUTONOMOUS	모든 페이즈 자동 실행	개발 환경

# orchestrator/authority_runner.py 의 코어 로직
def run_with_authority(orchestrator, user_requirement, authority_level, language):
    if authority_level == "HUMAN_CONTROLLED":
        ...

BaseAgent — 모든 에이전트의 통합 인터페이스(IF)

14개의 에이전트는 모두 BaseAgent를 상속하며, 공통의 LLM 호출 인터페이스를 가집니다:

class BaseAgent:
    SYSTEM_PROMPT: str = "You are a helpful assistant."
    def execute_llm_task(self, prompt, as_json=False):
        ...

이를 통해 새로운 에이전트의 추가는 클래스 상속 + system_prompt 정의만으로 충분합니다:

class ArchitectAgent(BaseAgent):
    SYSTEM_PROMPT = "You are a senior software architect..."
    def design_architecture(self, requirement):
        ...

3. LLM 라우팅 설계

태스크 기반의 모델 선택

「코드 생성에는 GPT-5.5」, 「리뷰에는 Sonnet」, 「분석에는 GLM」——태스크에 따라 최적의 모델을 자동으로 선택합니다.

프로필 레지스트리

9개의 프로필이 용도별로 정의되어 있습니다:

PROFILE_REGISTRY = {
# 품질 티어(코드·추론·설계)
"gpt_codex": LLMProfile(provider="openai", model="gpt-5.5"),
...

3단계 폴백 (3-Stage Fallback)

각 태스크에는 primary → secondary → fallback의 3단계가 설정되어 있습니다:

TASK_MODEL_CONFIGS = {
"code_generate": TaskModelConfig(
primary="gpt_codex", # 1st: GPT-5.5
...

API 키 미설정, 속도 제한 (Rate Limit), 타임아웃 등의 에러 발생 시, 자동으로 다음 후보로 폴백 (Fallback) 합니다. 이를 통해 「API 키가 하나도 없는」 경우를 제외하고는 시스템 전체가 중단되지 않도록 설계되었습니다.

예산 관리

일일 LLM 이용료를 상한 관리합니다:

class BudgetManager:
def check_budget(self, estimated_cost_usd):
if self.daily_spent + estimated_cost_usd > self.daily_limit:
...

4. 다층 품질 게이트 (Multi-layer Quality Gates)

Guardian Agent가 2단계의 품질 검증을 실행합니다. Tier 1을 통과하지 못하면 Tier 2로 진행할 수 없습니다.

Tier 1: 정적 분석 (4종 병렬)

도구	임계값	탐지 내용
pytest-cov	80%	테스트 커버리지 부족
...

Tier 2: 뮤테이션 테스트 (Mutation Testing)

「테스트가 통과한다」는 것만으로는 불충분합니다. 테스트가 정말로 버그를 탐지할 수 있는지를 검증합니다.

@dataclass
class MutationReport:
passed: bool
...

MutationTester Agent가 코드의 일부를 의도적으로 파괴하여, 테스트가 이를 탐지할 수 있는지 확인합니다. survived (생존한 변이체)가 많은 테스트는 「테스트의 품질이 낮다」고 판정됩니다.

5. 구현의 노하우와 지견

5-1. God Class 분할의 교훈

NexusCore의 개발 과정에서 가장 큰 기술적 부채는 God Class (모든 것을 수행하는 거대 클래스)였습니다.

파일	분할 전	분할 후	접근 방식
llm_router.py	789행	280 + 2개 파일	RoutedLLM·utils 분리
guardian_auto_reviewer.py	412행	151 + 309행	체커 함수 추출
self_healing_service.py	423행	240 + 3개 파일	God Method 해체
constitutional_council_agent.py	607행	338 + 2개 파일	정책 조작 분리

분할의 포인트:

• 하위 호환성 위임 (Backward Compatibility Delegation) — 추출 대상 모듈 레벨 함수를 기존 클래스의 얇은 메서드가 호출합니다. 기존 테스트가 깨지지 않습니다.

# guardian_auto_reviewer.py (분할 후)
class GuardianAutoReviewer:
def _check_sandbox_violations(self, diff, rules):
...

• 순환 참조 (Circular Import) 회피 — 분할된 모듈이 기존 모듈을 import 하는 경우, re-export가 아니라 호출 측의 import 경로를 업데이트합니다.
• 테스트 재작성 불필요 — 위임 패턴 (Delegate Pattern)을 통해 기존 테스트는 기존 클래스의 메서드를 계속 호출합니다.

5-2. Constitutional AI — 거버넌스의 자동화

NexusCore는 「AI가 마음대로 규칙을 바꾸는 것」을 방지하기 위해, **헌법적 거버넌스 (Constitutional Governance)**를 채택하고 있습니다.

• Postmortem Agent가 실패를 분석하고, 개선안을 amendment (수정안)로서 제안
• Constitutional Council이 amendment를 검증 (허가된 키만, 올바른 형식)
• 승인된 amendment만 Policy Store에 반영

5-3. 테스트 전략

4624개의 테스트 케이스를 안정적으로 유지하기 위한 노하우:

1. 외부 의존성의 모킹 (CI-safe)

@patch("subprocess.run")
def test_run_tests_via_subprocess(mock_run):
...

결과: 4624 passed / 5 failed (0.11%, 전체 비재현성 플래키 (Flaky))

6. 요약

NexusCore의 설계 사상은 세 가지로 집약됩니다:

• 전문화와 협업— 단일 만능 AI가 아닌, 전문 에이전트 (Agent) 간의 협업을 통한 고품질 결과물
• 계층화와 폴백 (Fallback)— LLM 라우터 (Router)의 3단계 폴백, 품질 게이트 (Quality Gate)의 2단계 검증
• 자율과 통제의 균형— Authority Runner를 통한 권한 제어, Constitutional Council을 통한 거버넌스 (Governance)

코드는 모두 GitHub에 공개되어 있습니다 (Apache 2.0). 멀티 에이전트 시스템 (Multi-agent System) 설계에 관심 있는 분들에게 참고가 되기를 바랍니다.

프로젝트 정보:

• GitHub: https://github.com/fukukei23/NexusCore
• 테스트 커버리지 (Test Coverage): 85%+
• Python 3.12+ / FastAPI / Flask / 8 LLM providers