connectai/docs/refactoring_roadmap.md

🛠️ ConnectAI 아키텍처 리팩토링 로드맵

Important

본 문서는 Astra v2.80.18 기준의 기술 부채 진단을 바탕으로 작성되었습니다. 모든 향후 기능 추가 시 아래 로드맵의 하위 과제를 병행하여 수행하는 것을 원칙으로 합니다.

1. 최우선 과제: Webview 계층 분리 (UI/UX 결합도 제거)

• 현상: sidebarProvider.ts 내부에 3,000줄 이상의 HTML/JS/CSS 문자열 혼재.
• 해결:
  • webview-ui/ 디렉토리 신설.
  • React 또는 순수 TS/JS 기반의 프론트엔드 프로젝트로 분리.
  • 빌드 타임에 리소스를 로드하고 postMessage 통신 프로토콜을 타입화하여 정의.
• 기대효과: 신택스 하이라이팅, 린팅 가능, UI 테스트 가능성 확보.

2. 엔진 추상화: EngineClient 추출

• 현상: agent.ts와 sidebarProvider.ts에 중복된 엔진 선택 및 API 호출 로직.
• 해결:
  • src/core/engine/ 디렉토리에 BaseEngineClient, OllamaClient, LMStudioClient 구현.
  • 전략 패턴(Strategy Pattern)을 사용하여 엔진별 통신 규격 캡슐화.
  • agent.ts는 더 이상 fetch나 API URL 조립에 관여하지 않음.

3. 지식 데이터 분리: 프롬프트 관리 시스템

• 현상: utils.ts에 하드코딩된 100줄 이상의 시스템 프롬프트.
• 해결:
  • prompts/ 디렉토리에 .md 파일 형식으로 프롬프트 관리.
  • PromptLoader를 통해 런타임에 지연 로딩.
  • 유저 피드백 기반의 프롬프트 버전 관리 체계 도입.

4. God Object 해체: AgentExecutor SRP 적용

• 현상: 한 클래스가 프롬프트 조립, 액션 실행, 트랜잭션, 메모리 관리를 모두 수행.
• 해결:
  • PromptOrchestrator: PromptBuilder 패턴을 사용하여 컨텍스트별 프롬프트 조립 및 로깅 담당.
  • ActionDispatcher: CREATE/EDIT/READ 등 에이전트 액션의 실제 실행 로직 분리.
  • ContextManager: 프로젝트 경로, 브레인 인벤토리 등 컨텍스트 추출 전담.

5. 단일 진실 원천 (SSoT) 확보

• 현상: globalState, localStorage, webview 간의 상태 동기화 부재로 인한 Race Condition.
• 해결:
  • 중앙 집중식 상태 관리자(StateManager) 도입.
  • VS Code ConfigurationTarget과 웹뷰 상태 간의 단방향 데이터 흐름(Unidirectional Data Flow) 강제.

6. 테스트 자동화 도입

• 현상: 테스트 코드 전무, 회귀 버그 검출 불가.
• 해결:
  • security.ts (보안 로직), utils.ts (유틸리티) 단위 테스트 작성.
  • 새로 추출할 EngineClient 및 ActionDispatcher에 대한 Mock 테스트 구현.

---

📊 현재 아키텍처 건전성 지표 (Self-Audit)

• SRP (단일 책임 원칙): 🔴 2/10 (파일당 3,000줄 초과)
• DIP (의존성 역전 원칙): 🟡 5/10 (Bridge에서 시도 중)
• OCP (개방-폐쇄 원칙): 🔴 3/10 (엔진 추가 시 모든 파일 수정 필요)
• 테스트 커버리지: 🔴 0%