Fix: Restore unified Topics folder and reorganize specialized category folders

10_Wiki/Topics/system_analysis_and_improvement_plan.md

@@ -0,0 +1,66 @@
+## 📌 Brief Summary
+G1nation 프로젝트의 기술적 부채를 해결하고 시스템의 근본적인 안정성(Stability)과 사용자 경험(UX)을 고도화하기 위한 전략적 실행 계획이다. 트랜잭션 관리 부재, 상태 관리의 휘발성, 테스트 부재 등 현재의 핵심 병목 지점을 진단하고, 원자적 작업 단위 확보와 구조화된 오류 보고 시스템 구축을 통해 에이전트의 신뢰성을 'Zero-Friction' 수준으로 끌어올리는 것을 목표로 한다.
+
+## 📖 Core Content
+1. **신뢰성 기반 트랜잭션 시스템 (Atomicity & Rollback)**
+   - **문제**: 작업 중단 시 부분적 변경으로 인한 데이터 오염.
+   - **해결**: `TransactionManager` 도입. `begin()` 단계에서 상태 스냅샷을 생성하고, 실패 시 `rollback()`을 통해 초기 상태로 복구하는 원자성 확보.
+2. **영속적 상태 관리 (Persistence & Context)**
+   - **문제**: 세션 중단 시 작업 맥락 소실.
+   - **해결**: `SessionState` 스키마 정의 및 디스크 기반 실시간 업데이트. 중단 지점부터 즉시 재개 가능한 '신뢰할 수 있는 기억 장치' 구현.
+3. **구조화된 오류 진단 및 보고**
+   - **문제**: 모호한 에러 메시지로 인한 디버깅 효율 저하.
+   - **해결**: 커스텀 에러 클래스(`AgentExecutionError` 등) 정의 및 오류 유형, 위치, 원인을 포함한 정형화된 보고서 생성.
+4. **알고리즘적 비효율성 개선 (Performance P1)**
+   - **문제**: `DataProcessor.aggregate()` 등 핵심 집계 함수의 $O(N^2)$ 복잡도로 인한 지수적 성능 저하.
+   - **해결**: 해시 맵(Hash Map) 기반 인덱싱 도입을 통해 시간 복잡도를 $O(N)$으로 최적화하고 CPU 부하 최소화.
+5. **유지보수성 및 복잡도 관리 (Architecture P2)**
+   - **문제**: 라우팅 로직의 높은 순환 복잡도(CC > 15) 및 인프라-비즈니스 로직의 강한 결합.
+   - **해결**: 단일 책임 원칙(SRP)에 따른 도메인 서비스 분리 및 인터페이스 기반의 느슨한 결합 구현.
+6. **품질 게이트 및 환경 규격화**
+   - **문제**: 테스트 부재 및 환경 설정 파편화.
+   - **해결**: Jest 기반 테스트 수트 구축(Mocking 필수), `config/` 모듈화를 통한 환경별 설정 분리 및 실행 전 유효성 검사(Validator) 수행.
+7. **사용자 경험 고도화 (Transparency & Control)**
+   - **문제**: 내부 작동 과정의 불투명성 및 제어권 부족.
+   - **해결**: 실시간 진행률 위젯 제공 및 `Dry Run Mode` 도입을 통한 사전 승인 프로세스 강화.
+
+## ⚖️ Trade-offs & Caveats
+- **구현 복잡도 증가**: 트랜잭션 및 상태 영속화 로직 도입 시 코드 베이스의 베이스라인 복잡도가 상승하며, 스냅샷 생성에 따른 미세한 성능 오버헤드가 발생할 수 있다.
+- **테스트 유지보수 비용**: Mocking 기반의 테스트는 실제 시스템 변경 시 테스트 코드도 함께 업데이트해야 하는 관리 비용이 발생한다.
+- **사용자 간섭의 양날의 검**: `Dry Run` 및 승인 단계가 많아질수록 안전성은 높아지나, 자동화의 속도와 흐름(Flow)이 끊길 수 있으므로 적절한 밸런스가 필요하다.
+
+### Phase 1 & 2: 진단 및 알고리즘 최적화 (Performance Focus)
+- **알고리즘 전환**: $O(N^2) \rightarrow O(N)$ 단일 패스 집계(Single-Pass Accumulation) 방식 채택.
+- **데이터 분포 민감성 (Critical Insight)**: 입력 데이터가 Sparse/Clustered하거나 키 연속성이 없는 경우, 단순 해시 맵 대신 **트라이(Trie)나 스킵 리스트(Skip List)**를 도입하여 최적의 인덱싱 전략 수립.
+- **성능 상충 관계 (Constant Factor)**: 작은 $N$ 값에 대한 단순성과 큰 $N$에 대한 복잡성 사이의 **Sweet Spot**을 식별하여 상수 인자(Constant Factor) 영향 최소화.
+
+### Phase 3: 아키텍처 분리 (Maintainability Focus)
+- **결합도 해소 (DIP)**: `IDataSource` 인터페이스 도입을 통해 비즈니스 로직과 데이터 저장 방식을 분리. 테스트 시 Mocking을 용이하게 하여 신뢰도 확보.
+- **복잡도 감소 (SRP)**: 라우팅 로직의 순환 복잡도를 **CC ≤ 10** 수준으로 관리하여 코드 가독성 및 디버깅 효율 극대화.
+
+### Phase 4: 검증 및 반복 (Validation Focus)
+- **오류 처리 정밀도 (Error Handling Granularity)**: 파싱 오류, 형식 불일치 등 예외 상황에 대한 명확한 처리 프로세스 검증.
+- **성공 기준**: 안정적인 처리량(Stable Throughput) 유지 및 피크 로드 상황에서의 견고성 입증.
+
+## 🔗 Knowledge Connections
+... (이후 기존 내용)
+### Related Concepts
+- **ACID 원칙**: 트랜잭션 설계의 근본 철학 (관계: 구현 모델)
+- **State Machine Architecture**: 상태 전환의 명확성을 위한 설계 패턴 (관계: 확장 방향)
+- **Observability**: 시스템 내부 상태를 외부에서 파악하는 능력 (관계: UX 개선)
+
+### Deeper Research Questions
+1. 분산 환경에서의 트랜잭션 롤백을 파일 시스템 수준에서 어떻게 최적화할 것인가?
+2. 에이전트의 '기억'을 벡터 DB와 로컬 세션 상태 사이에서 어떻게 효율적으로 분배할 것인가?
+3. 가상 파일 시스템(VFS)을 이용한 Dry Run 시뮬레이션의 정확도를 어떻게 보장할 것인가?
+4. 설정 유효성 검사(Config Validation)를 런타임이 아닌 빌드 타임에 수행할 수 있는 방안은?
+5. 사용자 개입(Human-in-the-loop)의 최소화와 시스템 안정성 사이의 정량적 임계점은 어디인가?
+
+### Practical Application Contexts
+- **ConnectAI Extension**: VS Code 내에서 에이전트의 작업 진행 상황을 시각화하고 사용자 승인을 받는 인터페이스 설계 시 적용.
+- **CI/CD Pipeline**: PR 생성 시 테스트 커버리지 및 정적 분석 결과를 게이트로 활용하는 운영 맥락.
+
+### Adjacent Topics
+- **Error Boundary Pattern in React**
+- **Git Internals (Snapshot & Rollback)**
+- **Event-Driven Microservices Architecture**