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

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 09:55:38 +09:00
parent d77ff5c625
commit e2c5471046
444 changed files with 88916 additions and 231 deletions
@@ -0,0 +1,71 @@
+---
+id: pattern-agent-orchestration
+title: "Agent Orchestration Pattern"
+category: "Pattern_AI"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["Agent Orchestration", "에이전트 오케스트레이션 패턴", "multi-agent", "pipeline"]
+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: ["pattern", "ai", "agent", "orchestration", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/agents/*, src/features/company/dispatcher.ts (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[Agent Orchestration Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+에이전트 오케스트레이션은 "큰 작업을 단계/역할로 쪼개 LLM 을 여러 번 호출·조율" 하는 패턴이며, *에이전트 수를 늘리는 것 자체가 목적이 되면 실패* 한다 — 정보 손실과 자원을 먼저 따져라.
+
+## 🧠 핵심 개념 (Core concepts)
+1. **분해:** 작업 → 단계(outline/draft/polish) 또는 역할(planner/specialist/reporter).
+2. **조율:** 흐름 골격이 호출 순서·데이터 전달을 관리.
+3. **상태 전달:** 앞 단계 출력을 다음에 전달(peer-context), 단 손실 주의.
+4. **자원 모델:** 병렬 vs 순차는 하드웨어가 결정.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **Problem (언제 쓰나):** 단일 호출로는 품질/길이/전문성이 부족한 복합 작업.
+- **사용 조건:** 단계 분해가 명확; 단계 간 인터페이스 정의 가능; 자원이 선택한 동시성 모델을 감당.
+- **장점:** 단계별 최적화, 긴 산출물, 역할 전문화, 검증 단계 삽입 용이.
+- **단점:** 지연·비용 증가, hop 마다 컨텍스트 누적/원본 손실, 디버깅 복잡.
+- **대안:** 단일 프롬프트(짧은 작업), 단일 작성자 다중 역할(자원 제약), 도구 호출.
+- **실패 사례:** 에이전트 남발로 "방법론만 생성"; 병렬 다중 모델 상주 OOM; orchestrator 재비대.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+# 자원 제약: 순차 + 한 모델 상주
+plan = planner(prompt)
+peer = ""
+for task in plan.tasks:
+    out = specialist(task, peer); persist(out); peer += truncate(out)
+report = synthesizer(prompt, peer)
+
+# 단일 작성자 다중 역할 (작은 모델 친화)
+outline = M("outline", prompt); body = [M("section", o, source) for o in outline]; M("polish", body)
+```
+적용 예: [[Agent 오케스트레이터 분해]], [[AITRAIN 에이전트 오케스트레이션]], 결정 [[ADR-0003 단일작성자 다중역할 멀티에이전트]]·[[ADR-0004 순차 디스패치 채택]].
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+"멀티에이전트가 항상 낫다" 는 자원 제약 하에서 거짓 — 잘 만든 단일 작성자가 어설픈 병렬 파이프라인을 이긴다.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI company dispatcher(순차), ChunkedWriter(단일 다중역할).
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Reflection Pattern]], [[Critic Pattern]], [[Tool Calling Pattern]], [[Background Worker Pattern]]
+- **참조 맥락:** 작은 모델이 복합 작업을 단계화할 때 과설계 회피와 함께 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 멀티에이전트 지식
+- [S2] AstraAI/src/agents/*, features/company/dispatcher.ts — 적용 예
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
@@ -0,0 +1,63 @@
+---
+id: pattern-critic
+title: "Critic Pattern"
+category: "Pattern_AI"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["Critic", "LLM judge", "검수자 패턴", "verifier"]
+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: ["pattern", "ai", "critic", "verification", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/intelligence/criticAgent.ts (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[Critic Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+Critic 패턴은 "별도의 검수자(보통 LLM)가 산출물을 비판적으로 평가" 하는 것으로, 생성자와 검수자를 분리하면 환각·누락을 잡지만 *검수 출력도 결국 LLM 이라 강건 파싱·근거 강제가 필수* 다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. 생성자와 검수자 역할 분리. 2. 검수 기준 명시(요구 충족·근거·미결 구분·지어냄 금지). 3. 구조화 출력(JSON) + 강건 파싱. 4. 검수 결과를 보완 카드/재작성 입력으로.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **Problem (언제 쓰나):** 산출물의 사실성/완결성이 중요하고, 생성자 자체 점검만으론 부족할 때.
+- **사용 조건:** 검수 기준을 명문화 가능; 검수 호출 비용 감당; 출력 파싱 방어.
+- **장점:** 독립 시각으로 오류 포착, 근거 없는 단정 차단, 보완 제안.
+- **단점:** 추가 LLM 비용, 검수자도 환각 가능, JSON 형식 위반.
+- **대안:** 결정론 규칙 검증, 다수결(여러 검수자), 사람 검수.
+- **실패 사례:** 검수자가 원문에 없는 내용을 "보완" 으로 지어냄; JSON.parse 직접 호출로 파싱 실패; 무조건 검수로 비용 폭증.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+critique = LLM_critic(system="검수자. 근거 없는 단정/지어냄은 major. JSON만 출력", user=task+draft)
+result   = parseBalancedJson(critique) or heuristicFallback()  # 잡설 내성
+if not result.pass: attach(footer(result.issues, result.supplement))
+# 규칙: supplement 도 원문 근거 한정, 없으면 "(확인 필요)"
+```
+적용 예: [[Intelligence 검증 레이어]] 의 criticAgent(조건부 1-pass + 균형 괄호 파서), 결정 [[ADR-0009 결정론 항상 LLM검증 조건부]].
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+검수자가 생성자보다 똑똑하지 않으면 효과가 제한적 — 작은 모델끼리는 *결정론 신호 + 근거 강제* 가 LLM-judge 보다 안정적일 수 있다.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI Critic(조건부), regression LLM-judge.
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Reflection Pattern]], [[프롬프트 엔지니어링 패턴]], [[소프트웨어 실패 라이브러리]]
+- **참조 맥락:** 작은 모델이 산출물 품질 게이트를 둘 때 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 LLM critic/judge 지식
+- [S2] AstraAI/src/intelligence/criticAgent.ts — 적용 예
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
@@ -0,0 +1,63 @@
+---
+id: pattern-memory
+title: "Memory Pattern"
+category: "Pattern_AI"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["Memory Pattern", "에이전트 메모리 패턴", "agent memory"]
+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: ["pattern", "ai", "memory", "agent", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/memory/* (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[Memory Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+에이전트 메모리 패턴은 "대화/세션을 넘어 지식을 보존·회수" 하며, 단일 버퍼가 아니라 *수명·용도별 계층* 으로 나누고 관련도로 선별 주입할 때 작은 모델의 일관성이 크게 오른다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. **단기:** 현재 대화(FIFO). 2. **장기:** 안정적 사실/선호(만료 가능). 3. **작업/프로젝트:** 작업 종속 지식. 4. **절차:** 반복 작업 방법. 5. **일화:** 과거 세션 요약. 회수 시 관련도순 선별.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **Problem (언제 쓰나):** 에이전트가 세션을 넘어 사용자/프로젝트를 기억해야 할 때, 컨텍스트 한도가 빠듯할 때.
+- **사용 조건:** 영속 저장 가능; 관련도 점수화 가능; 무엇을 어느 계층에 넣을지 분류 규칙 존재.
+- **장점:** 일관성·개인화, 컨텍스트 정밀 선별, 시한부/영구 공존, 자동 정리(증류).
+- **단점:** 분류 결정 비용, 저장/검색 인프라, 잘못된 회수 시 노이즈.
+- **대안:** 무상태(매번 새로), 전체 이력 투입(짧을 때), 외부 RAG 로만 대체.
+- **실패 사례:** 만료 없는 영구 저장으로 옛 사실 재현; 관련도 오선별로 핵심 누락; 계층 경계 모호로 중복.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+buildContext(query):
+  layers = [shortTerm, longTerm(query), project(query), procedural(query), episodic(query)]
+  return sort_by_relevance(layers).join()   # 빈 계층 제외
+onSessionEnd(): extract -> persist -> distill(stale -> longterm digest)
+```
+적용 예: [[5계층 메모리 시스템]], [[AITRAIN 메모리 시스템]], 결정 [[ADR-0002 5계층 메모리 분리]].
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+계층이 많을수록 표현력↑ 결정 비용↑ — 명확한 분류 규칙이 없으면 단순 3계층(작업/세션/영구)이 낫다.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI MemoryManager.
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[RAG Pattern]], [[Local Storage Pattern]], [[Offline Sync Pattern]]
+- **참조 맥락:** 작은 모델이 기억하는 에이전트를 만들 때 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 에이전트 메모리 지식
+- [S2] AstraAI/src/memory/* — 적용 예
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
@@ -0,0 +1,66 @@
+---
+id: pattern-rag
+title: "RAG Pattern"
+category: "Pattern_AI"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["RAG", "Retrieval-Augmented Generation", "검색 증강 생성 패턴"]
+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: ["pattern", "ai", "rag", "retrieval", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/retrieval/* (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[RAG Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+RAG 는 "모델이 답하기 전에 외부 지식에서 관련 조각을 검색해 프롬프트에 주입" 하는 패턴으로, 모델의 학습되지 않은/최신/사적 지식을 *재학습 없이* 활용하고 환각을 줄인다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. **인덱싱:** 문서를 청크로 나눠 검색 인덱스(키워드/임베딩)에 저장.
+2. **검색:** 질의로 top-k 관련 청크 회수(sparse/dense/하이브리드).
+3. **증강:** 회수 청크를 컨텍스트로 프롬프트에 삽입(토큰 예산 내).
+4. **생성:** 모델이 근거를 보고 답하고 출처를 인용.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **Problem (언제 쓰나):** 모델이 모르는 사적/최신/대용량 지식이 필요하고, 파인튜닝은 비싸거나 자주 바뀔 때. 출처 인용·환각 감소가 필요할 때.
+- **사용 조건:** 검색 가능한 지식 베이스 존재; 청킹/인덱싱 가능; 컨텍스트 한도 내 주입 가능.
+- **장점:** 재학습 불필요, 지식 즉시 갱신, 출처 추적, 환각↓, 작은 모델도 강화.
+- **단점:** 검색 품질에 답이 좌우(garbage in), 인덱싱/저장 비용, 컨텍스트 토큰 소비, 청킹 경계 손실.
+- **대안:** 파인튜닝(지식이 안정적·대규모일 때), 긴 컨텍스트에 전체 투입(소량일 때), 도구 호출로 실시간 조회.
+- **실패 사례:** 청크가 너무 커 정밀도↓; 부분 정규화로 하이브리드 편향; 동의어 미확장으로 recall↓; stale 인덱스; 운영 로그를 지식으로 오염.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+index   = chunk(docs) -> tokenize/embed -> store
+query   -> expand(synonyms) -> score(sparse + α·dense) -> normalize -> rerank
+context = selectWithinTokenBudget(top_chunks)
+answer  = LLM(system + context + question)  # "근거 없으면 모른다고"
+```
+적용 예: AstraAI 의 [[RAG 검색 파이프라인]]·[[TF-IDF 이중언어 스코어링]] (하이브리드+섹션 청킹+토큰 예산).
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+"임베딩만 쓰면 된다" 는 가용성·설명가능성을 잃는다 — 결정론(키워드) 바닥선 + 임베딩 가산이 견고([[ADR-0007 하이브리드 검색 결정론 우선]]).
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI 전체 검색이 이 패턴. → [[AITRAIN RAG 검색]].
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Memory Pattern]], [[Caching Pattern]], [[Tool Calling Pattern]], [[소프트웨어 실패 라이브러리]]
+- **참조 맥락:** 작은 모델이 지식 기반 응답 시스템을 만들 때 1순위 패턴.
+
+## 📚 출처 (Sources)
+- [S1] 일반 RAG 공학 지식
+- [S2] AstraAI/src/retrieval/* — 적용 예
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
@@ -0,0 +1,65 @@
+---
+id: pattern-reflection
+title: "Reflection Pattern"
+category: "Pattern_AI"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["Reflection", "자기성찰 패턴", "self-reflection", "self-critique"]
+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: ["pattern", "ai", "reflection", "self-improvement", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/intelligence/*, src/features/selfReflector/* (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[Reflection Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+Reflection 은 "모델이 자기 출력을 다시 점검·수정" 하는 패턴으로, 작은 모델의 1-pass 오류를 줄이지만 *호출이 늘어 비용/지연이 증가* 하므로 조건부로 써야 한다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. **생성 → 점검 → (필요시) 재생성** 루프. 2. 점검은 *결정론 신호* 또는 *LLM 자기비판*. 3. 자기검토 지시를 시스템 프롬프트에 주입. 4. 무한 루프 방지(최대 라운드).
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **Problem (언제 쓰나):** 1-pass 정확도가 부족하고, 오류 비용이 재검토 비용보다 클 때.
+- **사용 조건:** 점검 신호(규칙/요구사항/근거) 정의 가능; 추가 호출 latency 감당.
+- **장점:** 정확도·완결성↑, 누락/모순 발견, 불확실성 표면화.
+- **단점:** 지연·비용↑, 과도하면 헤지 남발, 무한 루프 위험.
+- **대안:** 결정론 검증만(무LLM), 외부 검증기, 더 큰 모델 1-pass.
+- **실패 사례:** 매 턴 무조건 reflect 로 latency 폭증; 자기비판이 오히려 정답을 망침; 종료 조건 없어 루프.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+draft = LLM(task)
+signals = deterministicChecks(draft)        # 커버리지/근거/확신도 — 항상(저비용)
+if signals.risky:                           # 조건부로만 LLM 점검
+    issues = LLM_critique(task, draft)
+    if issues: draft = revise(draft, issues)  # 최대 N라운드
+emit(draft + confidence_footer)
+```
+적용 예: [[Intelligence 검증 레이어]] (사전 자기검토 블록 + 조건부 critic), 결정 [[ADR-0009 결정론 항상 LLM검증 조건부]].
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+"항상 성찰하면 좋다" 는 비용을 무시한 통념 — *위험 신호가 있을 때만* 깊은 성찰이 비용 대비 효과적.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI selfReflector + 조건부 Critic.
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Critic Pattern]], [[Agent Orchestration Pattern]], [[프롬프트 엔지니어링 패턴]]
+- **참조 맥락:** 작은 모델의 자기개선 루프 설계 시 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 reflection/self-critique 지식
+- [S2] AstraAI/src/intelligence/*, features/selfReflector/* — 적용 예
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
@@ -0,0 +1,65 @@
+---
+id: pattern-tool-calling
+title: "Tool Calling Pattern"
+category: "Pattern_AI"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["Tool Calling", "function calling", "도구 호출 패턴", "action tag"]
+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: ["pattern", "ai", "tool-calling", "function-calling", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/agent/actions/* (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[Tool Calling Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+Tool Calling 은 "모델이 자연어 대신 구조화된 호출(함수/태그)로 외부 도구를 실행" 하게 해 실제 행동(파일 생성·명령 실행·검색)을 가능케 하며, *모델 출력을 신뢰 경계로 보고 검증·승인* 하는 것이 안전의 핵심이다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. 도구 스키마 정의(이름·인자). 2. 모델이 호출 의도를 구조화 출력(JSON function call 또는 `<action>` 태그). 3. 실행기가 파싱→검증→실행→결과 반환. 4. 위험 동작은 승인 게이트.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **Problem (언제 쓰나):** 모델이 텍스트를 넘어 *행동* 해야 할 때(파일/명령/API/검색).
+- **사용 조건:** 도구 인터페이스 명확; 출력 파싱 가능; 권한/검증 체계.
+- **장점:** 실제 작업 자동화, 결정론 도구로 환각 보완, 확장성(도구 추가).
+- **단점:** 보안 위험(임의 명령), 파싱 실패, 잘못된 인자, 무한 호출.
+- **대안:** 사람이 실행, 고정 워크플로(모델 미개입), 제한된 화이트리스트 액션.
+- **실패 사례:** 모델 출력을 검증 없이 실행(주입 공격); 경로 미검증으로 임의 파일 접근; 승인 없는 파괴적 명령.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+output = LLM(system + tools_schema + task)
+for call in parseToolCalls(output):       # <create_file>, <run_command> ...
+    if !validate(call): skip/log
+    if dangerous(call): await approval()  # 승인 게이트
+    result = execute(call)                # 실행기로 라우팅
+    feed(result -> next turn)
+```
+적용 예: AstraAI 의 action tag 실행기(src/agent/actions/*) + 승인 큐(approval) + 경로 검증(security.validatePath). 라우팅은 [[Agent 오케스트레이터 분해]] 참조.
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+"모델이 시키는 대로 실행" 은 위험 — 모델 출력은 *신뢰되지 않은 입력* 으로 다뤄 검증·샌드박스·승인을 거쳐야 한다.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI action tags + approval gate + validatePath/sanitizeCommand.
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Agent Orchestration Pattern]], [[API Client Pattern]], [[Command Pattern]], [[소프트웨어 실패 라이브러리]]
+- **참조 맥락:** 작은 모델이 행동하는 에이전트를 만들 때 안전 경계와 함께 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 function/tool calling 지식
+- [S2] AstraAI/src/agent/actions/*, security.ts — 적용 예
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.