---
id: adr-0010-orchestrator-skeleton-module-extraction
title: "ADR-0010 오케스트레이터 골격과 모듈 추출"
category: "Architecture_Decision"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["ADR orchestrator", "god class 분해 결정", "흐름 골격 유지", "모듈 추출"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.87
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["adr", "architecture", "refactoring", "decision", "connectai"]
raw_sources: ["ConnectAI/src/agent.ts", "ConnectAI/src/extension.ts"]
applied_in: ["ConnectAI"]
github_commit: ""
---

# [[ADR-0010 오케스트레이터 골격과 모듈 추출]]

## 🎯 한 줄 통찰 (One-line insight)
거대해지는 `agent.ts` 를 완전히 잘게 쪼개 흩어버리는 대신, **한 턴의 흐름 골격은 orchestrator 에 남기고 세부 구현만 모듈로 추출**하기로 결정했다 — "흐름을 한 곳에서 읽을 수 있음" 의 가치를 위해 [S1].

## 🧠 핵심 개념 (Core concepts)
- **결정:** handlePrompt/·llm/·actions/·sessions/·multiAgent/·contextBuilders/ 로 구현 추출, 흐름은 agent.ts 가 호출 순서로 표현.
- 구현은 [[Agent 오케스트레이터 분해]] 참조.

## 📖 세부 내용 (Details · ADR)
### Problem
한 턴 처리(컨텍스트 조립·라우팅·스트리밍·후처리·학습)가 한 파일에 쌓이면 수천 줄 god-class 가 된다. 반대로 전부 잘게 쪼개면 흐름이 파일 사이를 떠돌아 추적이 어렵다.

### Context
복잡한 단일 흐름(분기 많음), 다수 협력 모듈, 디버깅 시 "이 턴이 무슨 순서로 처리되나" 를 빨리 파악해야 함.

### Options Considered
1. **단일 god-class** — 흐름은 한눈, 그러나 거대·테스트 불가·병합 충돌.
2. **완전 분해(흐름도 분산)** — 모듈은 작으나 흐름 추적이 산만.
3. **골격 유지 + 세부 추출** — 흐름은 orchestrator, 구현은 순수/작은 모듈.

### Chosen Solution
3번. orchestrator 는 buildTurnContextBlocks→system prompt 빌드→budget→stream→processFinalAnswer→postAnswerHooks 순서를 *호출* 만 하고, 각 단계 구현은 추출된 함수/모듈 [S1].

### Why It Was Chosen
디버깅·온보딩 시 한 턴의 흐름을 orchestrator 한 곳에서 읽고, 세부가 궁금하면 해당 모듈로 내려간다. 추출된 함수는 순수해 테스트 가능.

### Benefits
흐름 가독성 + 모듈 테스트성, 병합 충돌 감소, 점진적 추출 가능.

### Drawbacks
orchestrator 가 여전히 큼(import 100+줄), 추출 경계 설정에 판단 필요, 과도하면 "얇은 래퍼 지옥".

### Future Risks
흐름 분기가 더 늘면 orchestrator 가 다시 비대 → 모드별 서브-오케스트레이터로 분할 필요.

### Alternative Approaches
파이프라인/미들웨어 체인으로 단계를 데이터로 표현, 또는 모드(chat/agent/company)별 orchestrator 분리.

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
"god-class 는 무조건 나쁘다" 는 단순 규칙과 다르다 — *흐름 가독성* 이라는 명확한 이득이 있으면 골격을 남기는 것이 합리적. 단, 크기 상한을 정하지 않으면 다시 비대해진다.

## 🛠️ 적용 사례 (Applied in summary)
`agent.ts` 의 import/호출 구조, `extension.ts` 의 얇은 조립 [S1][S2].

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
- **관련 개념:** [[Agent 오케스트레이터 분해]], [[리팩토링 플레이북]], [[안티패턴 카탈로그]]
- **참조 맥락:** 로컬 LLM 이 거대 함수/클래스를 리팩터링할 때 "어디까지 추출할지" 판단에 참조.

## 📚 출처 (Sources)
- [S1] ConnectAI/src/agent.ts — 골격 + 추출 모듈 import
- [S2] ConnectAI/src/extension.ts — 얇은 조립 entry point

## 📝 변경 이력 (Change history)
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
