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,84 @@
|
||||
---
|
||||
id: adr-0001-event-sourcing
|
||||
title: "ADR-0001 이벤트 소싱 채택"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR event sourcing", "왜 이벤트 소싱", "append-only 결정", "JSONL 결정"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.9
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["adr", "event-sourcing", "decision", "persistence", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/features/_shared/eventSourcedStore.ts", "ConnectAI/src/memory/types.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0001 이벤트 소싱 채택]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
도메인 데이터(고객·채용·런웨이·피드백)를 "상태 덮어쓰기" 대신 **append-only JSONL 이벤트**로 저장하기로 결정했다 — 이력 보존·내결함·중복 제거(제네릭 팩토리)를 한 번에 얻기 위해 [S1].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정:** `createEventStore<E>` 제네릭 팩토리로 모든 도메인 스토어를 append-only JSONL 위에 구현.
|
||||
- **상태:** 현재 상태는 이벤트 재생(`computeStates`)으로 도출, 저장은 이벤트만.
|
||||
- 자세한 구현은 [[이벤트 소싱 스토어 패턴]] 참조.
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem (문제)
|
||||
customers/hire/runway/feedback 4개 도메인이 각자 `getXFilePath/readX/appendX/countX` 를 복붙해 ~240줄 byte-for-byte 중복. 동시에 "언제 무엇이 바뀌었나" 이력이 필요한 도메인인데 마지막 상태만 저장하면 그 정보를 잃는다 [S1].
|
||||
|
||||
### Context (맥락)
|
||||
- 단일 사용자 로컬 VS Code 확장 — 무거운 DB 운영 비용을 감당할 이유가 적다.
|
||||
- 데이터 규모가 작고(수백~수천 행), 사람이 직접 파일을 열어보는 투명성이 가치.
|
||||
- 부분 손상(파일 1줄 깨짐)에도 나머지를 살려야 한다.
|
||||
|
||||
### Options Considered (고려한 대안)
|
||||
1. **상태 JSON 1개 덮어쓰기** — 단순하지만 이력 손실·동시쓰기 시 전체 덮어쓰기 위험.
|
||||
2. **SQLite** — 쿼리/인덱스 강력하지만 의존성·마이그레이션·운영 복잡도 추가.
|
||||
3. **append-only JSONL 이벤트 + 제네릭 팩토리** — 이력 보존 + 한 줄 추가의 단순함 + 내결함.
|
||||
|
||||
### Chosen Solution (선택)
|
||||
3번. `createEventStore<E>({ relPath, validate })` 가 read/append/count/getFilePath 를 제공하고, 도메인은 이벤트 타입 `E` 와 `computeStates` 만 정의 [S1].
|
||||
|
||||
### Why It Was Chosen (선택 이유)
|
||||
- 이력이 그 자체로 가치 있는 도메인에 자연스럽다.
|
||||
- 제네릭으로 4벌 중복을 1벌로 — BOM/인코딩 fix 도 한 곳에서 전파.
|
||||
- 한 줄 손상이 전체를 무력화하지 않는 내결함(파싱 실패 줄 skip).
|
||||
- 외부 의존 0 (Node fs 만) — 번들 가벼움 유지.
|
||||
|
||||
### Benefits (장점)
|
||||
이력 감사·재현·디버깅 용이, 단순한 append I/O, 사람이 읽고 고칠 수 있는 투명성, 타입 안전한 재사용.
|
||||
|
||||
### Drawbacks (단점)
|
||||
파일이 단조 증가(compaction 없음), 현재 상태를 매번 재생하는 비용, 멀티프로세스 동시 append 는 별도 잠금 필요.
|
||||
|
||||
### Future Risks (미래 위험)
|
||||
- 이벤트 수가 수만을 넘으면 재생 비용/메모리 증가 → 스냅샷+증분 compaction 필요.
|
||||
- 이벤트 스키마 진화 시 구버전 이벤트 호환(버전 필드/업캐스팅) 관리 부담.
|
||||
|
||||
### Alternative Approaches (대안 접근)
|
||||
규모가 커지면 SQLite(+WAL)로 이전하거나, 이벤트는 유지하되 주기적 스냅샷을 도입. 읽기 빈도가 매우 높으면 메모리 캐시 + 파일 watch.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"이력 보존" 이 목표가 아니라면(마지막 값만 중요) 이 결정은 과설계다. 그 경우 상태 1개 파일이 더 단순하다.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
`ConnectAI/src/features/_shared/eventSourcedStore.ts` — 결정의 구현체 [S1].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[이벤트 소싱 스토어 패턴]], [[Event Bus Pattern]], [[ADR-0005 파일 기반 저장 채택]], [[엔지니어링 트레이드오프 분석]]
|
||||
- **참조 맥락:** 로컬 LLM 이 "이력 저장 vs 상태 저장" 을 결정할 때 판단 근거로 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/features/_shared/eventSourcedStore.ts — 제네릭 이벤트 스토어, 중복 통합 배경 주석
|
||||
- [S2] ConnectAI/src/memory/types.ts — 버전 필드 직렬화 스토어
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
id: adr-0002-memory-layer-separation
|
||||
title: "ADR-0002 5계층 메모리 분리"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR memory layers", "왜 메모리를 분리", "메모리 계층 결정"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.9
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["adr", "memory", "decision", "ai", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/memory/index.ts", "ConnectAI/src/memory/types.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0002 5계층 메모리 분리]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
에이전트의 "기억"을 단일 저장소가 아니라 **시간 범위·용도가 다른 5계층(단기·장기·프로젝트·절차·일화)**으로 분리하기로 결정했다 — 계층마다 검색·만료·승급 정책이 달라야 하기 때문 [S1].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정:** MemoryManager 가 5개 독립 계층을 보유, 각 계층이 query 에 대해 관련도를 매겨 컨텍스트에 합침.
|
||||
- 구현 상세는 [[5계층 메모리 시스템]] 참조.
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem
|
||||
모든 기억을 한 통에 넣으면 "현재 대화"·"사용자 영구 취향"·"프로젝트 결정"·"반복 절차"·"과거 세션 요약"이 같은 정책으로 다뤄진다. 그러나 이들은 수명·만료·우선순위·검색 방식이 전부 다르다 [S1].
|
||||
|
||||
### Context
|
||||
- 로컬 작은 모델은 컨텍스트 한도가 작아, 무엇을 넣을지 *정교한 선별* 이 필수.
|
||||
- 시한부 지식(분기 계획)과 영구 지식(사용자 선호)이 공존.
|
||||
- 과거 세션을 "지난번에 한 일"로 떠올릴 수 있어야 한다.
|
||||
|
||||
### Options Considered
|
||||
1. **단일 메모리 버퍼(최근 N 메시지)** — 단순하나 장기·프로젝트·절차 기억 불가.
|
||||
2. **벡터 DB 단일 저장** — 의미 검색은 좋지만 만료·승급·계층별 정책 표현이 어렵고 인프라 부담.
|
||||
3. **역할별 5계층 분리 + 통합 매니저** — 계층별 정책 + 단일 진입점.
|
||||
|
||||
### Chosen Solution
|
||||
3번. 단기(FIFO)·장기(category/confidence/expiresAt)·프로젝트(workspace별 ADR/버그)·절차(trigger→steps)·일화(세션 요약, distillation 승급) [S1][S2].
|
||||
|
||||
### Why It Was Chosen
|
||||
계층마다 다른 정책을 자연스럽게 표현(만료, 승급, lazy 생성). 컨텍스트 예산이 빠듯한 작은 모델에 "관련도 높은 계층부터" 선별 주입 가능. 인간 인지 메타포로 이해·확장 용이.
|
||||
|
||||
### Benefits
|
||||
정밀한 컨텍스트 선별, 시한부/영구 지식 공존, 일화→장기 증류로 자동 정리, RAG 소스로 통합 가능.
|
||||
|
||||
### Drawbacks
|
||||
계층 경계의 모호성(장기 decision vs 프로젝트 ADR), 매니저 조립 복잡도, 계층별 저장 파일 증가.
|
||||
|
||||
### Future Risks
|
||||
계층이 더 늘면(예: 감정/사회적 기억) 관리 폭증. 관련도 점수가 휴리스틱이라 잘못 선별 시 핵심 기억 누락 가능.
|
||||
|
||||
### Alternative Approaches
|
||||
의미 검색이 핵심이면 각 계층 *내부* 에 임베딩을 도입(하이브리드)하거나, 계층 수를 3개(작업·세션·영구)로 단순화. 대규모면 벡터 DB + 메타데이터 필드로 계층을 표현.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
계층이 많을수록 표현력은 커지나 "어디에 저장할지" 결정 비용도 커진다 — 명확한 분류 규칙([[아키텍처 휴리스틱]])이 없으면 오히려 혼란.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
`ConnectAI/src/memory/index.ts`, `types.ts` [S1][S2].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[5계층 메모리 시스템]], [[Memory Pattern]], [[아키텍처 휴리스틱]], [[엔지니어링 트레이드오프 분석]]
|
||||
- **참조 맥락:** 로컬 LLM 이 에이전트 메모리 구조를 설계할 때 "한 통 vs 계층 분리" 판단에 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/memory/index.ts — MemoryManager 5계층 통합
|
||||
- [S2] ConnectAI/src/memory/types.ts — 계층별 타입·만료·승급 필드
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
+82
@@ -0,0 +1,82 @@
|
||||
---
|
||||
id: adr-0003-single-writer-multi-role
|
||||
title: "ADR-0003 단일작성자 다중역할 멀티에이전트"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR multi-agent", "왜 병렬 persona 를 버렸나", "ChunkedWriter 결정", "멀티에이전트 결정"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.88
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["adr", "multi-agent", "decision", "ai", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/agents/AgentWorkflowManager.ts", "ConnectAI/src/features/company/dispatcher.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0003 단일작성자 다중역할 멀티에이전트]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
"여러 persona 를 병렬/직렬로 줄세우는 멀티에이전트" 대신, 일반 작성 작업은 **단일 작성자가 outline→section→polish 역할을 번갈아 수행**하고, 진짜 다중 전문가가 필요한 회사 모드는 **순차 디스패치(한 번에 한 모델 상주)**로 가기로 결정했다 [S1][S2].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정 1:** 5-persona 파이프라인 폐기 → 단일 `ChunkedWriter` 다중 역할.
|
||||
- **결정 2:** 다중 전문가는 병렬이 아니라 순차 + peer-context 전달.
|
||||
- 구현은 [[Agent 오케스트레이터 분해]] 참조.
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem
|
||||
초기 planner/researcher/reflector/writer/synthesizer 5-persona 파이프라인은 (1) hop 마다 컨텍스트가 누적되고 (2) 원본 본문이 추상화로 손실돼, 사용자가 본문 분석을 요청해도 "분석 방법론" 만 만들어내는 사고가 났다 [S1]. 또 병렬 에이전트는 단일 GPU/제한 RAM 에서 여러 모델을 동시 상주시켜야 한다 [S2].
|
||||
|
||||
### Context
|
||||
- 타깃 환경: 단일 GPU/CPU, 제한된 RAM, 로컬 작은 모델(gemma 등).
|
||||
- LM Studio lifecycle 매니저가 모델 load/unload 를 관리 — "한 번에 하나" 가 자연스럽다.
|
||||
- 작업 종류: 대부분 단일 문서 작성, 일부만 진짜 다중 전문가 협업(회사 모드).
|
||||
|
||||
### Options Considered
|
||||
1. **병렬 멀티에이전트(persona N개 동시)** — 빠르지만 모델 다중 상주·자원 폭주, 컨텍스트/본문 손실.
|
||||
2. **직렬 5-persona 파이프라인** — 자원은 낫지만 hop 누적·본문 추상화 손실(실제 발생한 사고).
|
||||
3. **단일 작성자 다중 역할(+필요 시 순차 전문가)** — 컨텍스트 작고 본문 직접 전달, 한 모델만 상주.
|
||||
|
||||
### Chosen Solution
|
||||
3번. 일반 작성은 `ChunkedWriter`(outline/section/polish 한 모델 번갈아). 다중 전문가는 company `dispatcher` 가 CEO 플래너→전문가 순차(peer-context 잘라 전달)→CEO 리포터 [S1][S2].
|
||||
|
||||
### Why It Was Chosen
|
||||
- 본문이 매 호출에 직접 전달돼 손실 없음(초기 사고의 직접 해결).
|
||||
- 각 호출이 작아 작은 모델의 컨텍스트 한도를 지킴.
|
||||
- "정확히 한 모델만 상주" 로 VRAM 안전 + lifecycle 단순.
|
||||
|
||||
### Benefits
|
||||
자원 안전, 본문 보존, 컨텍스트 폭증 방지, 디버깅 단순(한 번에 한 단계).
|
||||
|
||||
### Drawbacks
|
||||
총 응답 시간이 길다(순차). 단일 모델 품질에 결과가 좌우된다. 병렬로 얻는 다양성·속도를 포기.
|
||||
|
||||
### Future Risks
|
||||
작업이 진짜 병렬성을 요구하거나(대규모 리서치), 멀티 GPU 환경이 표준이 되면 이 결정이 병목이 된다.
|
||||
|
||||
### Alternative Approaches
|
||||
자원이 충분하면 병렬 persona + 합의(judge panel). 또는 역할별로 작은 특화 모델을 동시에. 속도가 critical 하면 outline/section 을 병렬화하고 polish 만 직렬.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"멀티에이전트가 항상 낫다" 는 통념과 반대다 — *자원 제약 하에서는* 잘 구성된 단일 작성자가 어설픈 병렬 파이프라인보다 낫다는 실측 교훈. 환경이 바뀌면 재평가 대상.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
`AgentWorkflowManager.ts`(ChunkedWriter), `company/dispatcher.ts`(순차) [S1][S2].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[Agent 오케스트레이터 분해]], [[Agent Orchestration Pattern]], [[ADR-0004 순차 디스패치 채택]], [[엔지니어링 트레이드오프 분석]]
|
||||
- **참조 맥락:** 로컬 LLM 이 멀티에이전트를 도입할지/어떻게 구성할지 자원 제약 하에 판단할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/agents/AgentWorkflowManager.ts — 5-persona 폐기 post-mortem, ChunkedWriter
|
||||
- [S2] ConnectAI/src/features/company/dispatcher.ts — 순차 디스패치 근거
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
id: adr-0004-sequential-dispatch
|
||||
title: "ADR-0004 순차 디스패치 채택"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR sequential dispatch", "왜 순차 실행", "한 번에 한 모델"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.9
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["adr", "concurrency", "decision", "resource", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/features/company/dispatcher.ts", "ConnectAI/src/lmstudio/lifecycleManager.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0004 순차 디스패치 채택]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
다중 에이전트/모델 작업을 **순차로 실행하고 한 번에 정확히 하나의 모델만 메모리에 상주**시키기로 결정했다 — 단일 GPU/제한 RAM 에서 병렬은 여러 모델 동시 로드를 강요해 OOM·스왑을 부르기 때문 [S1].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정:** company 턴은 전문가를 순차 실행, LM Studio lifecycle 가 이전 모델 unload → 다음 load.
|
||||
- 무거운 LLM 작업은 `missionId` 락으로도 직렬화.
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem
|
||||
병렬 에이전트는 동시에 여러 모델을 상주시켜야 하는데, 타깃 사용자는 단일 GPU/제한 RAM 으로 Astra 를 돌린다 → 동시 로드 시 메모리 초과/스왑/로드 실패 [S1].
|
||||
|
||||
### Context
|
||||
로컬 우선 설계, 작은 모델, LM Studio SDK 의 load/unload 수명관리. 응답 지연보다 *동작 보장* 이 우선.
|
||||
|
||||
### Options Considered
|
||||
1. **병렬 실행** — 빠르지만 다중 모델 상주 필요(자원 초과).
|
||||
2. **순차 + 매번 같은 모델** — 단순하나 역할별 특화 모델 사용 불가.
|
||||
3. **순차 + 에이전트별 모델 override(lifecycle unload/load)** — 한 번에 하나, 역할별 모델 가능.
|
||||
|
||||
### Chosen Solution
|
||||
3번. 전문가마다 모델 override 가능, 디스패처가 순차로 돌며 lifecycle 가 교체. peer-context 를 잘라 다음 에이전트에 전달 [S1].
|
||||
|
||||
### Why It Was Chosen
|
||||
"한 모델만 상주" 불변식이 자원 안전을 보장하고, 그러면서도 단계별 최적 모델을 쓸 수 있다.
|
||||
|
||||
### Benefits
|
||||
OOM 회피, 예측 가능한 메모리, 역할별 모델 유연성, 진행 단계 가시화 용이.
|
||||
|
||||
### Drawbacks
|
||||
총 시간이 길다(모델 교체 오버헤드 포함). 병렬 처리량 포기.
|
||||
|
||||
### Future Risks
|
||||
멀티 GPU/대용량 RAM 이 표준이 되면 과도한 제약. 작업 수가 많으면 누적 지연이 사용자 인내를 초과.
|
||||
|
||||
### Alternative Approaches
|
||||
자원 충분 시 워커 풀 + 모델 핀닝으로 병렬. 또는 빠른 단계는 작은 모델로 병렬, 합성만 큰 모델로 직렬(하이브리드).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
처리량 최적화와 정면 충돌하는 결정 — 환경(자원)이 전제이므로, 서버 배포 시엔 [[엔지니어링 트레이드오프 분석]] 기준으로 재검토.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
`company/dispatcher.ts` 의 순차 루프 + lifecycle [S1].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[ADR-0003 단일작성자 다중역할 멀티에이전트]], [[동시성 제어 Lock Queue Transaction]], [[Background Worker Pattern]]
|
||||
- **참조 맥락:** 로컬 LLM 이 자원 제약 환경에서 병렬 vs 순차를 결정할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/features/company/dispatcher.ts — "Why sequential?" 근거 주석
|
||||
- [S2] ConnectAI/src/lmstudio/lifecycleManager.ts — 모델 load/unload 수명관리
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
id: adr-0005-file-based-storage
|
||||
title: "ADR-0005 파일 기반 저장 채택"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR storage", "왜 DB 안 쓰나", "Markdown JSONL 저장", "파일 저장 결정"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.89
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["adr", "storage", "decision", "filesystem", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/core/services.ts", "ConnectAI/src/features/_shared/eventSourcedStore.ts", "ConnectAI/src/intelligence/correctionLoop.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0005 파일 기반 저장 채택]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
지식·메모리·로그를 DB 가 아니라 **Markdown(.md) + JSON/JSONL 파일**로 저장하기로 결정했다 — 사람이 직접 열어 읽고/고치는 투명성(Permission Based Learning)과 무의존성이 단일 사용자 로컬 도구에 최적이기 때문 [S1][S3].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정:** brain 지식=Markdown(frontmatter), 이벤트/케이스=JSONL, 설정/프로필=JSON.
|
||||
- 검색은 파일 위 TF-IDF/임베딩 인덱스([[RAG 검색 파이프라인]]).
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem
|
||||
지식/메모리/학습 데이터를 어디에 저장할 것인가. DB 는 강력하지만 단일 사용자 로컬 확장에 운영·마이그레이션·불투명성 비용을 더한다.
|
||||
|
||||
### Context
|
||||
- 사용자가 두뇌 내용을 직접 보고 수정/삭제할 수 있어야 한다(투명성·신뢰).
|
||||
- VS Code/에디터로 그대로 열람 가능해야(Markdown).
|
||||
- 번들 의존성 최소화(런타임 deps 2개).
|
||||
|
||||
### Options Considered
|
||||
1. **SQLite/임베디드 DB** — 쿼리·트랜잭션 강력, 그러나 불투명·의존성·스키마 관리.
|
||||
2. **벡터 DB** — 의미 검색 최적, 그러나 인프라·운영 부담, 사람이 못 읽음.
|
||||
3. **파일 기반(Markdown + JSONL + JSON)** — 투명·무의존·버전관리(git) 친화.
|
||||
|
||||
### Chosen Solution
|
||||
3번. 지식은 frontmatter 달린 Markdown, 이벤트/정정 케이스는 append-only JSONL, 프로필/설정은 JSON. 검색은 파일 위 인덱스로 보강 [S1][S2][S3].
|
||||
|
||||
### Why It Was Chosen
|
||||
사람이 읽고 고치는 투명성이 신뢰의 핵심(특히 자기학습 시스템). git diff 로 변경 추적. 의존성 0 으로 배포 단순.
|
||||
|
||||
### Benefits
|
||||
투명성, 무의존, git 친화, 에디터 직접 열람, 백업/이동 단순(폴더 복사).
|
||||
|
||||
### Drawbacks
|
||||
복잡한 쿼리/조인 불가, 대량 데이터에서 스캔 비용, 동시쓰기 잠금 직접 관리, 인덱스를 직접 구축해야 함.
|
||||
|
||||
### Future Risks
|
||||
brain 이 수만 파일로 커지면 파일 스캔/인덱싱 비용 급증. 트랜잭션이 약해 다중 파일 일관성은 보상 트랜잭션에 의존.
|
||||
|
||||
### Alternative Approaches
|
||||
규모 확대 시 SQLite(메타데이터) + 파일(본문) 하이브리드, 또는 임베딩만 벡터 DB 로 외부화하고 본문은 파일 유지.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"검색·쿼리 성능" 만 보면 DB 가 우위다. 이 결정은 *투명성·무의존* 을 성능보다 우선한 가치 판단 — 멀티유저/대규모면 뒤집힌다.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
brain Markdown(BrainService.inject), JSONL 이벤트 스토어, corrections.jsonl / weakness-profile.json [S1][S2][S3].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[ADR-0001 이벤트 소싱 채택]], [[이벤트 소싱 스토어 패턴]], [[Local Storage Pattern]], [[Caching Pattern]]
|
||||
- **참조 맥락:** 로컬 LLM 이 "DB vs 파일" 저장 방식을 결정할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/core/services.ts — BrainService Markdown 저장
|
||||
- [S2] ConnectAI/src/features/_shared/eventSourcedStore.ts — JSONL 이벤트
|
||||
- [S3] ConnectAI/src/intelligence/correctionLoop.ts — JSONL/JSON 케이스·프로필(투명성)
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
---
|
||||
id: adr-0006-manual-di-interface-services
|
||||
title: "ADR-0006 수동 의존성주입과 인터페이스 서비스"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR DI", "왜 DI 컨테이너 안 쓰나", "수동 주입 결정", "인터페이스 서비스 결정"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.89
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["adr", "dependency-injection", "decision", "architecture", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/extension.ts", "ConnectAI/src/core/services.ts", "ConnectAI/src/intelligence/criticAgent.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0006 수동 의존성주입과 인터페이스 서비스]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
의존성 주입을 **DI 프레임워크 없이 entry point(`activate`)에서 손으로 조립**하고, 외부 효과를 가진 협력자는 **인터페이스/함수 타입으로 추상화**해 주입하기로 결정했다 — 조립 지점이 하나뿐이라 컨테이너의 비용이 불필요하기 때문 [S1][S2].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정:** 수동 생성자/함수/getter 주입 + IAIService/IBrainService/CritiqueLlmCall 추상화.
|
||||
- 구현 상세는 [[의존성 주입과 서비스 인터페이스]] 참조.
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem
|
||||
협력자(AI 서비스, 스트리머, 큐, LLM 호출)를 객체가 직접 생성하면 결합이 강해지고 테스트가 어렵다. 그러나 DI 컨테이너는 학습·설정·런타임 마법 비용이 있다.
|
||||
|
||||
### Context
|
||||
조립 지점이 사실상 `activate` 한 곳. 모듈 수는 많지만 의존 그래프는 명시적. 테스트는 순수 함수 + 가짜 주입으로 충분.
|
||||
|
||||
### Options Considered
|
||||
1. **DI 컨테이너(tsyringe 등)** — 자동 해석/수명관리, 그러나 의존성·매직·디버깅 비용.
|
||||
2. **싱글톤 남발** — 간단하나 테스트 격리 불가, 숨은 결합.
|
||||
3. **수동 주입 + 인터페이스/함수 추상화** — 명시적, 무의존, 테스트 용이.
|
||||
|
||||
### Chosen Solution
|
||||
3번. 생성자 옵션 객체(`new AgentExecutor(ctx, {...})`), 함수 타입 주입(`CritiqueLlmCall`), getter 주입(`getProvider`). 전역이 본질인 자원만 싱글톤(lock/queue) [S1][S2].
|
||||
|
||||
### Why It Was Chosen
|
||||
조립이 한 곳이라 컨테이너의 이득이 작고, 수동 주입이 흐름을 가장 투명하게 만든다. 함수 주입으로 검증 모듈을 순수하게 유지(테스트 시 가짜 LLM).
|
||||
|
||||
### Benefits
|
||||
무의존·투명한 조립, 뛰어난 테스트성, 명시적 의존 그래프, 교체 용이.
|
||||
|
||||
### Drawbacks
|
||||
조립 코드가 장황(activate 가 큼), 의존이 늘면 수동 배선 부담, 수명관리 직접.
|
||||
|
||||
### Future Risks
|
||||
모듈/조립 지점이 폭증하면 수동 배선이 한계 → 부분적 컨테이너 도입 필요. 싱글톤은 테스트 격리를 점점 어렵게.
|
||||
|
||||
### Alternative Approaches
|
||||
규모 확대 시 경량 컨테이너 또는 팩토리 레이어. 또는 기능별 "composition root" 를 여러 개로 분리.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"엔터프라이즈엔 DI 컨테이너" 통념과 다르다 — 단일 composition root 소규모에선 수동 주입이 더 단순·명확. 규모가 결정 인자.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
`extension.ts`(수동 조립), `services.ts`(인터페이스), `criticAgent.ts`(함수 주입) [S1][S2][S3].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[의존성 주입과 서비스 인터페이스]], [[Repository Pattern]], [[엔지니어링 트레이드오프 분석]]
|
||||
- **참조 맥락:** 로컬 LLM 이 "DI 컨테이너 vs 수동 주입" 을 규모 기준으로 결정할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/extension.ts — activate 수동 조립, getter/옵션 주입
|
||||
- [S2] ConnectAI/src/core/services.ts — IAIService/IBrainService
|
||||
- [S3] ConnectAI/src/intelligence/criticAgent.ts — CritiqueLlmCall 함수 주입
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
+77
@@ -0,0 +1,77 @@
|
||||
---
|
||||
id: adr-0007-hybrid-retrieval-deterministic-first
|
||||
title: "ADR-0007 하이브리드 검색과 결정론 우선"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR retrieval", "왜 TF-IDF 먼저", "하이브리드 검색 결정", "결정론 우선"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.9
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["adr", "rag", "retrieval", "decision", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/retrieval/index.ts", "ConnectAI/src/retrieval/scoring.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0007 하이브리드 검색과 결정론 우선]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
검색의 기본은 **TF-IDF(sparse)로 항상 동작**하게 하고, 임베딩(dense)은 *가용할 때만 가산 혼합* 하기로 결정했다 — 임베딩 엔진이 없거나 미색인이어도 검색이 절대 망가지지 않게 하기 위해 [S1].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정:** TF-IDF 기본 + 임베딩 blend(α). 벡터 없는 문서는 순수 sparse 유지.
|
||||
- 구현은 [[RAG 검색 파이프라인]], [[TF-IDF 이중언어 스코어링]] 참조.
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem
|
||||
의미 검색(임베딩)은 강력하지만 임베딩 모델 가용성·색인 상태에 의존한다. 그것에만 의존하면 모델이 없을 때 검색이 죽는다. 반대로 키워드만 쓰면 환언/동의를 놓친다.
|
||||
|
||||
### Context
|
||||
로컬 환경에서 임베딩 모델이 있을 수도/없을 수도. brain 은 한/영 혼용. "검색은 언제나 동작" 이 신뢰의 기본.
|
||||
|
||||
### Options Considered
|
||||
1. **임베딩 단독(dense only)** — 의미 강하나 가용성·비용 의존, 무관 문서도 높은 cos.
|
||||
2. **키워드 단독(sparse only)** — 항상 동작·설명가능하나 환언 놓침.
|
||||
3. **하이브리드(결정론 우선 + 임베딩 가산)** — 기본 보장 + 의미 보강.
|
||||
|
||||
### Chosen Solution
|
||||
3번. TF-IDF 로 점수, 임베딩이 있으면 `(1-α)·sparse + α·dense`. 모든 후보를 maxTfidf 로 정규화(벡터 있는 것만 줄이면 안 됨), cosine 은 후보군 min-max 정규화 [S1].
|
||||
|
||||
### Why It Was Chosen
|
||||
가용성 보장(임베딩 없어도 동작), 설명가능(왜 매치됐는지), 그러면서 의미 검색의 이득을 더한다. 실측 버그(스케일 불일치)를 정규화로 해결.
|
||||
|
||||
### Benefits
|
||||
무중단 검색, 점진 도입(임베딩 색인이 늘수록 좋아짐), 설명가능, 한/영 교차 매칭(동의어 확장).
|
||||
|
||||
### Drawbacks
|
||||
스케일 정규화가 까다로움(2건의 실측 버그), 수작업 동의어 사전 유지, 형태소 분석 부재.
|
||||
|
||||
### Future Risks
|
||||
brain 규모↑ 시 sparse 인덱스 메모리·시간 증가. 동의어 사전 누락이 recall 을 갉아먹음.
|
||||
|
||||
### Alternative Approaches
|
||||
대규모면 BM25 + 벡터 DB 하이브리드, 또는 reranker 모델 도입. 한국어 정밀도가 critical 하면 형태소 분석기.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"임베딩이 최신이고 우월" 통념과 달리, *가용성·설명가능성* 을 위해 결정론을 1순위로 둔다 — 단, 의미 검색을 버리지 않고 가산.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
`retrieval/index.ts`(하이브리드 blend), `scoring.ts`(TF-IDF/토크나이저) [S1].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[RAG 검색 파이프라인]], [[TF-IDF 이중언어 스코어링]], [[RAG Pattern]], [[Caching Pattern]]
|
||||
- **참조 맥락:** 로컬 LLM 이 검색을 설계할 때 "dense only vs 하이브리드" 와 가용성 보장을 판단할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/retrieval/index.ts — 하이브리드 blend, 스케일 정규화 버그 기록
|
||||
- [S2] ConnectAI/src/retrieval/scoring.ts — TF-IDF, 이중언어 토크나이저, 동의어
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
+77
@@ -0,0 +1,77 @@
|
||||
---
|
||||
id: adr-0008-local-first-llm-cloud-fallback
|
||||
title: "ADR-0008 로컬 우선 LLM과 클라우드 폴백"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR local-first", "엔진 폴백 결정", "로컬 LLM 우선", "프로바이더 라우팅 결정"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.9
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["adr", "llm", "provider", "decision", "fallback", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/core/services.ts", "ConnectAI/src/features/providers/types.ts", "ConnectAI/src/features/providers/index.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0008 로컬 우선 LLM과 클라우드 폴백]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
기본은 **로컬 엔진(LM Studio/Ollama)을 우선**하고 로컬끼리 폴백하며, 클라우드(OpenRouter/Anthropic/Gemini)는 **model id prefix 로 옵션 선택**하기로 결정했다 — 프라이버시·비용·오프라인을 기본값으로, 필요 시 클라우드 품질을 끌어쓰기 위해 [S1][S2].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정:** prefix 없으면 로컬, 있으면 클라우드 어댑터. 로컬은 LM Studio↔Ollama 자동 폴백.
|
||||
- 구현은 [[LLM 프로바이더 추상화]] 참조.
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem
|
||||
어떤 LLM 을 어떻게 선택/실패 처리할 것인가. 로컬은 무료·프라이버시·오프라인이지만 품질·가용성이 들쭉날쭉. 클라우드는 품질↑ 비용·프라이버시 우려.
|
||||
|
||||
### Context
|
||||
제2뇌는 개인 지식을 다룸 → 프라이버시 중요. 로컬 엔진은 가끔 빈 응답/전송 오류. 사용자가 작업별로 품질을 올리고 싶을 때가 있음.
|
||||
|
||||
### Options Considered
|
||||
1. **클라우드 전용** — 품질·간편, 그러나 비용·프라이버시·오프라인 불가.
|
||||
2. **로컬 전용** — 프라이버시·무료, 그러나 실패 시 대안 없음.
|
||||
3. **로컬 우선 + 로컬 폴백 + 클라우드 옵션(prefix)** — 기본 안전 + 선택적 품질.
|
||||
|
||||
### Chosen Solution
|
||||
3번. `AIService.chat` 이 설정 엔진→다른 로컬 엔진 폴백(빈 응답=soft failure). 클라우드는 `parseModelPrefix` 로 라우팅, 어댑터가 SSE 정규화 [S1][S2].
|
||||
|
||||
### Why It Was Chosen
|
||||
프라이버시·비용·오프라인을 기본으로 보장하면서, 로컬 불안정을 폴백으로 메우고, 필요 시 클라우드 품질을 prefix 하나로 선택.
|
||||
|
||||
### Benefits
|
||||
프라이버시 기본, 가용성↑(폴백), 유연성(작업별 클라우드), 호출부 공급자 무관.
|
||||
|
||||
### Drawbacks
|
||||
폴백이 지연을 더함, 로컬/클라우드 응답 형식 차이를 어댑터가 흡수해야 함, 클라우드 키 관리.
|
||||
|
||||
### Future Risks
|
||||
클라우드 모델 id/형식 변경 시 어댑터 유지보수, 로컬 모델 품질이 작업을 못 받치면 사용자 불만.
|
||||
|
||||
### Alternative Approaches
|
||||
품질이 절대 우선이면 클라우드 기본 + 로컬 폴백(역순). 또는 작업 난이도 자동 분류로 라우팅(쉬운 건 로컬, 어려운 건 클라우드).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"좋은 클라우드 모델을 쓰면 되지" 라는 입장과 충돌 — 이 결정은 *프라이버시·비용·오프라인* 을 품질보다 우선한 가치 판단. 사용은 prefix 로 자유.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
`services.ts`(폴백), `providers/types.ts`+`index.ts`(prefix 라우팅) [S1][S2].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[LLM 프로바이더 추상화]], [[API Client Pattern]], [[Tool Calling Pattern]]
|
||||
- **참조 맥락:** 로컬 LLM 이 다중 추론 백엔드 전략(로컬/클라우드/폴백)을 설계할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/core/services.ts — 로컬 엔진 폴백, soft failure
|
||||
- [S2] ConnectAI/src/features/providers/types.ts, index.ts — prefix 라우팅, 어댑터 dispatch
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
---
|
||||
id: adr-0009-deterministic-always-llm-conditional
|
||||
title: "ADR-0009 결정론 항상, LLM 검증 조건부"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR verification", "왜 조건부 critic", "결정론 우선 검증", "확신도 결정론"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.9
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["adr", "verification", "intelligence", "decision", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/intelligence/confidenceEngine.ts", "ConnectAI/src/intelligence/criticAgent.ts", "ConnectAI/src/intelligence/epistemicGuardBlock.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0009 결정론 항상, LLM 검증 조건부]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
답변 검증에서 **저렴한 결정론적 검사(정규식/카운트/그라운딩 신호)는 매 턴 실행**하고, **비싼 LLM 검수(Critic)는 결정론 검사가 문제를 신호할 때만** 돌리기로 결정했다 — 로컬 모델의 latency 비용 안에서 신뢰를 확보하기 위해 [S1][S2].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정:** Epistemic Guard(사전, 무비용) + Confidence Engine(결정론, 무LLM) 항상 / Critic(LLM) 조건부 1-pass.
|
||||
- 구현은 [[Intelligence 검증 레이어]] 참조.
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem
|
||||
작은 로컬 모델은 환각이 잦다. 매 답변을 LLM 으로 재검수하면 정확하지만 latency·비용이 2배 이상으로 사용성이 무너진다.
|
||||
|
||||
### Context
|
||||
로컬 Gemma 류, 단일 GPU. 매 턴 추가 LLM 호출은 체감 지연이 큼. 그러나 사실오류/근거누락은 잡아야 함.
|
||||
|
||||
### Options Considered
|
||||
1. **항상 LLM 재검수(full debate)** — 가장 정확, 그러나 latency·비용 폭증.
|
||||
2. **검증 없음** — 빠르나 환각 방치.
|
||||
3. **결정론 항상 + LLM 조건부** — 비용 통제 + 위험 신호 시 정밀 검수.
|
||||
|
||||
### Chosen Solution
|
||||
3번. 매 턴 Epistemic Guard 주입 + 결정론 Confidence(0~100) 산출. "커버리지 누락 또는 확신도 <70" 일 때만 Critic LLM 1회 호출, 보완 카드 표시. 다회전 debate 는 knob 만 준비 [S1][S2].
|
||||
|
||||
### Why It Was Chosen
|
||||
대부분의 답변은 결정론 신호로 충분히 걸러지고, 진짜 위험할 때만 비싼 검수를 써 비용 대비 신뢰를 극대화. "모름 인정이 오답보다 낫다" 를 사전 가드로 구조화.
|
||||
|
||||
### Benefits
|
||||
낮은 평균 latency, 위험 시 정밀 검수, 설명가능한 확신도, 사용자 검토 유도(에스컬레이션).
|
||||
|
||||
### Drawbacks
|
||||
조건 임계가 잘못되면 위험 답변을 놓치거나 불필요 검수. 확신도 가중치가 휴리스틱(보정 필요). 1-pass 는 다회전보다 약함.
|
||||
|
||||
### Future Risks
|
||||
임계/가중치가 데이터 없이 고정되면 오탐/미탐. 모델 교체 시 신호 분포가 바뀌어 재보정 필요.
|
||||
|
||||
### Alternative Approaches
|
||||
골든셋으로 가중치 학습, 위험 도메인만 다회전 debate, 또는 작은 전용 검증 모델 상시 가동.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"항상 검증해야 안전" 과 "검증은 비싸다" 의 균형점 — 환경(로컬 latency)이 임계를 정한다. 서버/대형 모델이면 더 자주 LLM 검수가 합리적.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
`confidenceEngine.ts`(결정론), `criticAgent.ts`(조건부), `epistemicGuardBlock.ts`(사전) [S1][S2][S3].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[Intelligence 검증 레이어]], [[Critic Pattern]], [[Reflection Pattern]], [[엔지니어링 트레이드오프 분석]]
|
||||
- **참조 맥락:** 로컬 LLM 이 자기검증 비용/정확도 균형을 설계할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/intelligence/confidenceEngine.ts — 결정론 확신도(매 턴)
|
||||
- [S2] ConnectAI/src/intelligence/criticAgent.ts — 조건부 1-pass 검수
|
||||
- [S3] ConnectAI/src/intelligence/epistemicGuardBlock.ts — 사전 가드
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
+77
@@ -0,0 +1,77 @@
|
||||
---
|
||||
id: adr-0010-orchestrator-skeleton-module-extraction
|
||||
title: "ADR-0010 오케스트레이터 골격과 모듈 추출"
|
||||
category: "Architecture_Decision"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["ADR orchestrator", "god class 분해 결정", "흐름 골격 유지", "모듈 추출"]
|
||||
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: ["adr", "architecture", "refactoring", "decision", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/agent.ts", "ConnectAI/src/extension.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[ADR-0010 오케스트레이터 골격과 모듈 추출]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
거대해지는 `agent.ts` 를 완전히 잘게 쪼개 흩어버리는 대신, **한 턴의 흐름 골격은 orchestrator 에 남기고 세부 구현만 모듈로 추출**하기로 결정했다 — "흐름을 한 곳에서 읽을 수 있음" 의 가치를 위해 [S1].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- **결정:** handlePrompt/·llm/·actions/·sessions/·multiAgent/·contextBuilders/ 로 구현 추출, 흐름은 agent.ts 가 호출 순서로 표현.
|
||||
- 구현은 [[Agent 오케스트레이터 분해]] 참조.
|
||||
|
||||
## 📖 세부 내용 (Details · ADR)
|
||||
### Problem
|
||||
한 턴 처리(컨텍스트 조립·라우팅·스트리밍·후처리·학습)가 한 파일에 쌓이면 수천 줄 god-class 가 된다. 반대로 전부 잘게 쪼개면 흐름이 파일 사이를 떠돌아 추적이 어렵다.
|
||||
|
||||
### Context
|
||||
복잡한 단일 흐름(분기 많음), 다수 협력 모듈, 디버깅 시 "이 턴이 무슨 순서로 처리되나" 를 빨리 파악해야 함.
|
||||
|
||||
### Options Considered
|
||||
1. **단일 god-class** — 흐름은 한눈, 그러나 거대·테스트 불가·병합 충돌.
|
||||
2. **완전 분해(흐름도 분산)** — 모듈은 작으나 흐름 추적이 산만.
|
||||
3. **골격 유지 + 세부 추출** — 흐름은 orchestrator, 구현은 순수/작은 모듈.
|
||||
|
||||
### Chosen Solution
|
||||
3번. orchestrator 는 buildTurnContextBlocks→system prompt 빌드→budget→stream→processFinalAnswer→postAnswerHooks 순서를 *호출* 만 하고, 각 단계 구현은 추출된 함수/모듈 [S1].
|
||||
|
||||
### Why It Was Chosen
|
||||
디버깅·온보딩 시 한 턴의 흐름을 orchestrator 한 곳에서 읽고, 세부가 궁금하면 해당 모듈로 내려간다. 추출된 함수는 순수해 테스트 가능.
|
||||
|
||||
### Benefits
|
||||
흐름 가독성 + 모듈 테스트성, 병합 충돌 감소, 점진적 추출 가능.
|
||||
|
||||
### Drawbacks
|
||||
orchestrator 가 여전히 큼(import 100+줄), 추출 경계 설정에 판단 필요, 과도하면 "얇은 래퍼 지옥".
|
||||
|
||||
### Future Risks
|
||||
흐름 분기가 더 늘면 orchestrator 가 다시 비대 → 모드별 서브-오케스트레이터로 분할 필요.
|
||||
|
||||
### Alternative Approaches
|
||||
파이프라인/미들웨어 체인으로 단계를 데이터로 표현, 또는 모드(chat/agent/company)별 orchestrator 분리.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"god-class 는 무조건 나쁘다" 는 단순 규칙과 다르다 — *흐름 가독성* 이라는 명확한 이득이 있으면 골격을 남기는 것이 합리적. 단, 크기 상한을 정하지 않으면 다시 비대해진다.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
`agent.ts` 의 import/호출 구조, `extension.ts` 의 얇은 조립 [S1][S2].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[Agent 오케스트레이터 분해]], [[리팩토링 플레이북]], [[안티패턴 카탈로그]]
|
||||
- **참조 맥락:** 로컬 LLM 이 거대 함수/클래스를 리팩터링할 때 "어디까지 추출할지" 판단에 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/agent.ts — 골격 + 추출 모듈 import
|
||||
- [S2] ConnectAI/src/extension.ts — 얇은 조립 entry point
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
|
||||
Reference in New Issue
Block a user