Files

T

Antigravity Agent 9148c358d0 docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거

Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를
Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류.

- 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로
  자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거,
  동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거.
- 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming,
  Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business,
  Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로,
  나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는
  title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백).
  원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지.
- 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서.
- 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는
  지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지.
- Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경.
- 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.

2026-07-05 00:33:48 +09:00

5.0 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

리팩토링 플레이북

🎯 한 줄 통찰 (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)

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

확장 우려 (Scaling concerns)

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

마이그레이션 경로 (Suggested migration paths)

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

안전 절차 (How to refactor safely)

동작을 테스트로 고정(특히 순수 함수 — chunker/scoring 처럼).
회귀 위험을 플래그로 격리(예: chunkLevelRetrieval 처럼 새 경로를 분리).
작은 단계로 커밋, 각 단계 후 평가 하니스(recall@k/회귀 리포트) 재실행.
동일 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 리팩터링 사례 기반 플레이북 초안.

5.0 KiB Raw Blame History