---
id: refactoring-playbook
title: "리팩토링 플레이북"
category: "Software_Engineering"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["refactoring playbook", "리팩토링", "기술 부채", "technical debt", "마이그레이션 경로", "확장 우려"]
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: ["refactoring", "technical-debt", "scaling", "migration", "connectai"]
raw_sources: ["ConnectAI/src/agent.ts", "ConnectAI/src/features/_shared/eventSourcedStore.ts", "ConnectAI/src/retrieval/index.ts", "ConnectAI/src/features/company/dispatcher.ts"]
applied_in: ["ConnectAI"]
github_commit: ""
---

# [[리팩토링 플레이북]]

## 🎯 한 줄 통찰 (One-line insight)
리팩토링은 "동작을 바꾸지 않고 구조를 개선" 하는 것이며, ConnectAI 의 실제 리팩터링(중복 통합·동적→정적·persona 단순화·god-class 추출)에서 *언제·어떻게 안전하게 진화시키는가* 의 절차를 뽑을 수 있다.

## 🧠 핵심 개념 (Core concepts)
- 현재 한계 → 기술 부채 → 리팩토링 기회 → 확장 우려 → 마이그레이션 경로.
- 안전 리팩토링 = 테스트로 동작 고정 → 작은 단계 → 회귀 격리.

## 📖 세부 내용 (Details)

### 현재 한계 (Current limitations)
- `agent.ts` orchestrator 가 여전히 큼(import 100+줄) — 모드 분기가 늘면 재비대.
- 파일 기반 저장은 brain 이 수만 파일로 커지면 스캔/인덱싱 비용 급증.
- 이벤트 JSONL 은 compaction 없어 단조 증가.
- 검색 동의어 사전이 수작업이라 도메인 확장 시 누락.
- 확신도/검증 가중치가 휴리스틱(데이터 보정 전).
- 순차 디스패치는 누적 지연 — 멀티 GPU 미활용.

### 기술 부채 (Technical debt)
- 일부 `as any` 캐스팅(외부 JSON 경계).
- 하드코딩 모델 목록(클라우드 어댑터) 노후화.
- 메모리 계층 경계 모호(장기 decision vs 프로젝트 ADR).

### 리팩토링 기회 (Refactoring opportunities)
1. **중복 → 제네릭/공통 모듈:** eventSourcedStore 처럼 반복 패턴을 팩토리로 흡수(이미 적용). 다음 후보: contextBuilders 의 유사 블록.
2. **동적 → 정적:** 이유가 사라진 `await import` 를 정적 import 로(이미 dispatcher 적용).
3. **god-class → 골격+추출:** 모드별 서브-오케스트레이터 분리(chat/agent/company).
4. **휴리스틱 → 학습:** 확신도/검색 가중치를 골든셋으로 보정.

### 확장 우려 (Scaling concerns)
- brain 파일 수 ↑ → 인덱싱 시간/메모리. → 파일 watch + 증분 인덱스, 또는 메타데이터 DB.
- 이벤트 수 ↑ → 재생 비용. → 스냅샷 + 증분.
- 사용자 수 ↑(멀티유저) → 파일 잠금/일관성 한계. → DB 이전.

### 마이그레이션 경로 (Suggested migration paths)
- **저장:** 파일 → (SQLite 메타 + 파일 본문 하이브리드) → 필요 시 벡터 DB 외부화. *본문 투명성은 유지.*
- **검색:** TF-IDF → +임베딩(이미) → +reranker 모델 → BM25/벡터 DB.
- **에이전트:** 순차 → (자원 감지) → 조건부 병렬(워커 풀). 환경을 런타임 감지해 전략 전환.
- **오케스트레이터:** 단일 → 모드별 분리 → 파이프라인/미들웨어 체인.

### 안전 절차 (How to refactor safely)
1. 동작을 테스트로 고정(특히 순수 함수 — chunker/scoring 처럼).
2. 회귀 위험을 *플래그로 격리*(예: `chunkLevelRetrieval` 처럼 새 경로를 분리).
3. 작은 단계로 커밋, 각 단계 후 평가 하니스(recall@k/회귀 리포트) 재실행.
4. 동일 scoring 경로 재사용으로 *측정 무결성* 유지(평가와 프로덕션이 같은 코드).

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
리팩토링은 가치지만 *동작 변경 없는* 범위를 지켜야 한다. 기능 추가와 섞으면 회귀 원인 추적이 어렵다 — 분리된 커밋이 원칙.

## 🛠️ 적용 사례 (Applied in summary)
중복 통합(eventSourcedStore), 동적→정적(dispatcher), persona 단순화(ChunkedWriter), 플래그 격리(chunkLevelRetrieval) [S1~S4].

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
- **관련 개념:** [[디버깅 플레이북]], [[안티패턴 카탈로그]], [[엔지니어링 트레이드오프 분석]], [[아키텍처 휴리스틱]]
- **참조 맥락:** 로컬 LLM 이 기존 코드를 개선/확장할 때 안전 절차와 마이그레이션 경로로 참조.

## 📚 출처 (Sources)
- [S1] ConnectAI/src/features/_shared/eventSourcedStore.ts — 중복 통합
- [S2] ConnectAI/src/features/company/dispatcher.ts — 동적→정적
- [S3] ConnectAI/src/agents/AgentWorkflowManager.ts — persona 단순화
- [S4] ConnectAI/src/retrieval/index.ts — 플래그 격리, 평가 무결성

## 📝 변경 이력 (Change history)
- 2026-06-13: ConnectAI 리팩터링 사례 기반 플레이북 초안.