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,122 @@
+---
+id: module-system-project-structure
+title: "모듈 시스템과 프로젝트 구성"
+category: "Programming_Language"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["import", "export", "모듈", "barrel", "side-effect import", "dynamic import", "esbuild", "번들링"]
+duplicate_of: ""
+source_trust_level: "A"
+confidence_score: 0.92
+created_at: 2026-06-13
+updated_at: 2026-06-13
+review_reason: ""
+merge_history: []
+tags: ["typescript", "module", "import", "esbuild", "project-structure", "astraai"]
+raw_sources: ["AstraAI/src/extension.ts", "AstraAI/src/memory/index.ts", "AstraAI/src/retrieval/index.ts", "AstraAI/package.json", "AstraAI/tsconfig.json"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[모듈 시스템과 프로젝트 구성]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+모듈 시스템은 "무엇을 공개하고(`export`) 무엇을 가져올지(`import`)"로 코드 경계를 긋는 것이며, AstraAI 는 **barrel(index.ts) 재수출·side-effect import 자기등록·동적 import 지연로딩**을 조합해 308개 파일을 esbuild 단일 번들로 묶는다 [S1][S4].
+
+## 🧠 핵심 개념 (Core concepts)
+1. **ES Module 문법:** `import { x } from './m'` / `export function x()`. TypeScript 는 이 문법을 쓰고, tsconfig `module: commonjs` 로 CommonJS 로 컴파일된다 [S5].
+2. **named vs default export:** AstraAI 는 거의 전부 *named export* 만 쓴다 — 자동완성·일관된 이름·리팩터링 안전성 때문. default export 는 사실상 배제 [S2].
+3. **Barrel 파일 (index.ts):** 하위 모듈을 한 곳에서 재수출(`export * from './types'`)해 외부가 깔끔한 진입점 하나만 import 하게 한다 [S2][S3].
+4. **Side-effect import:** `import './features/teamops/handlers'` — 값을 가져오지 않고 *모듈 로드의 부수효과*(핸들러 자기등록)만 노린다 [S1].
+5. **Dynamic import (`await import(...)`):** 무겁거나 드물게 쓰는 모듈을 실제 호출 시점에 지연 로딩 — 활성화 시간 단축 [S1].
+6. **번들링 (esbuild):** 모든 모듈을 `out/extension.js` 하나로 묶되 `vscode` 는 external (런타임 제공) [S4].
+
+## 🧩 추출된 패턴 (Extracted patterns)
+- **상대경로 import + 명확한 트리:** `../config`, `./types` 같은 상대경로로 모듈을 참조하고, 폴더 구조가 곧 도메인 경계(`features/`, `core/`, `memory/`, `retrieval/`, `intelligence/`).
+- **barrel 재수출로 진입점 단일화:** `src/memory/index.ts` 가 5개 메모리 클래스 + distillation API + `export * from './types'` 를 한 번에 노출 [S3].
+- **side-effect import 로 핸들러 자기등록:** entry point 가 `import './features/system/handlers'` 만 하면 그 모듈이 slashRouter 에 자기를 등록 — 등록 코드를 한 곳에 모으지 않는 분산 등록 [S1].
+- **동적 import 로 무거운 기능 지연:** `const { runDatacollectSetup } = await import('./features/setup/datacollectSetup')` — 명령 실행 시에만 로드 [S1].
+- **타입 전용 import:** `import type { ChatMessage } from '../../agent'` — 컴파일 후 사라지는 타입만 가져와 순환참조·번들 부담 회피 [S6].
+
+## 📖 세부 내용 (Details)
+### 폴더 = 도메인 경계
+```
+src/
+  core/         공통 인프라 (lock, queue, transaction, errors, services, events)
+  features/     기능 도메인 (각 폴더가 독립 기능: stocks, calendar, company, datacollect…)
+  memory/       5계층 메모리
+  retrieval/    RAG 검색
+  intelligence/ 검증·자기평가 (critic, confidence, correctionLoop)
+  lib/          순수 헬퍼 + contextBuilders (프롬프트 컨텍스트 조립)
+  agent/        에이전트 실행 세부 (handlePrompt/, llm/, actions/, multiAgent/)
+```
+각 폴더 안에 `index.ts`(barrel)가 있으면 외부는 그 하나만 import 한다.
+
+### import 순서·스타일
+실제 코드는 (1) Node 표준(`fs`, `path`), (2) vscode, (3) 내부 모듈 순으로 import 하며, 내부는 도메인별로 묶어 가독성을 유지한다. 거대한 orchestrator(agent.ts)는 import 가 100줄을 넘는데, 이는 *기능을 작은 모듈로 추출하고 다시 끌어모으는* 구조의 자연스러운 결과다 [S1].
+
+### side-effect import 의 순서 민감성
+```typescript
+// slashRouter 가 먼저 로드된 뒤 핸들러가 자기 등록되도록 entry point 에서 import
+import './features/teamops/handlers';
+import './features/system/handlers';
+import './features/datacollect/handlers';
+```
+주석이 "왜 여기서 import 하는지"(로드 순서 보장)를 명시한다 — side-effect import 는 순서가 동작에 영향을 주므로 의도를 적는 것이 필수 [S1].
+
+### 번들/빌드
+- `compile`: `esbuild src/extension.ts --bundle --platform=node --external:vscode --outfile=out/extension.js` — 단일 파일 번들 [S4].
+- `watch`: `tsc -watch` (타입 체크용), `test`: `jest`. 런타임 의존성은 `@lmstudio/sdk`, `pdf-parse` 둘뿐이고 axios 대신 native `fetch` 사용 [S4].
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+- **barrel 의 양날:** index.ts 재수출은 진입점을 깔끔히 하지만, 과하면 순환참조와 "한 줄 import 가 거대한 그래프를 끌어옴" 문제를 낳는다. AstraAI 는 무거운 기능을 동적 import 로 분리해 이를 완화 [S1].
+- **commonjs vs ESM:** tsconfig 는 `commonjs` 로 컴파일하지만 소스는 ESM 문법으로 작성한다 — VS Code 확장 런타임(Node)이 CJS 를 기대하기 때문. 새 프로젝트라면 ESM 출력도 가능하나 호환성 고려 필요 [S5].
+
+## 🛠️ 적용 사례 (Applied in summary)
+- `AstraAI/src/extension.ts` — side-effect import, 동적 import, 100+줄 named import 의 실제 예 [S1].
+- `AstraAI/src/memory/index.ts`, `src/retrieval/index.ts` — barrel 재수출 [S2][S3].
+
+## 💻 코드 패턴 (Code patterns)
+```typescript
+// 1) side-effect import — 핸들러 자기등록 (순서 주석 필수) (src/extension.ts)
+import './features/teamops/handlers';
+import './features/system/handlers';
+
+// 2) barrel 재수출로 진입점 단일화 (src/memory/index.ts)
+export { ShortTermMemory } from './ShortTermMemory';
+export { LongTermMemory } from './LongTermMemory';
+export * from './types';
+
+// 3) 동적 import 로 무거운 기능 지연 (src/extension.ts)
+vscode.commands.registerCommand('g1nation.setupDatacollect', async () => {
+    const { runDatacollectSetup } = await import('./features/setup/datacollectSetup');
+    await runDatacollectSetup();
+});
+
+// 4) 타입 전용 import — 런타임 부담/순환참조 회피
+import type { AgentExecutorOptions, ChatMessage } from '../../agent';
+```
+
+## ✅ 검증 상태 및 신뢰도
+- **상태:** draft
+- **검증 단계:** applied
+- **출처 신뢰도:** A
+- **신뢰 점수:** 0.92
+- **중복 검사 결과:** 신규 생성 (New discovery)
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[TypeScript 기초와 타입 시스템]]
+- **관련 개념:** [[AstraAI 아키텍처 개요]], [[VSCode 확장 구조와 생명주기]], [[코딩 컨벤션과 주석 철학]]
+- **참조 맥락:** 로컬 LLM 이 파일을 나누고 import/export 를 구성할 때 참조.
+
+## 📚 출처 (Sources)
+- [S1] AstraAI/src/extension.ts — side-effect/동적 import, named import 구성
+- [S2] AstraAI/src/features/providers/index.ts — named export, 재수출
+- [S3] AstraAI/src/memory/index.ts, src/retrieval/index.ts — barrel(export *) 패턴
+- [S4] AstraAI/package.json — esbuild 번들 스크립트, 의존성
+- [S5] AstraAI/tsconfig.json — module/target 설정
+- [S6] AstraAI/src/agent/multiAgent/workflow.ts — import type
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: AstraAI 코드 분석 기반 초안 생성.