wiki: Topic_Blog 신규 문서 일괄 추가 + ASTRA 성장 자산 동기화
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,87 @@
|
||||
---
|
||||
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 리팩터링 사례 기반 플레이북 초안.
|
||||
Reference in New Issue
Block a user