Files

T

Antigravity Agent e2c5471046 wiki: Topic_Blog 신규 문서 일괄 추가 + ASTRA 성장 자산 동기화

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-16 09:55:38 +09:00

4.9 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)

리팩토링은 "동작을 바꾸지 않고 구조를 개선" 하는 것이며, AstraAI 의 실제 리팩터링(중복 통합·동적→정적·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)

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

📚 출처 (Sources)

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

📝 변경 이력 (Change history)

2026-06-13: AstraAI 리팩터링 사례 기반 플레이북 초안.

4.9 KiB Raw Blame History