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,52 @@
|
||||
---
|
||||
id: platform-guides-index
|
||||
title: "플랫폼 개발 가이드 인덱스"
|
||||
category: "Index"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["platform guides", "플랫폼 가이드", "플랫폼별 개발 패턴", "platform development index"]
|
||||
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: ["index", "platform", "guide", "navigation"]
|
||||
raw_sources: ["Platform_Guides 전체"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[플랫폼 개발 가이드 인덱스]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
플랫폼별 가이드는 [[프로젝트 독립 설계 원칙]] 과 [[패턴 카탈로그 인덱스]] 를 *각 플랫폼의 구체적 폴더 구조·핵심 컴포넌트·테스트·확장 전략* 으로 구체화한 것 — 경험 많은 엔지니어가 플랫폼을 가로질러 어떻게 설계하는지를 작은 모델에 가르친다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
각 가이드 12-field: Problem / Recommended Architecture / Folder Structure / Core Components / State Management / Error Handling / Testing / Scaling / Common Mistakes / Refactoring / Tradeoffs / Heuristics.
|
||||
|
||||
## 📖 세부 내용 (Details · 가이드 목록)
|
||||
- [[웹 개발 가이드]]
|
||||
- [[데스크탑 앱 개발 가이드]] (AstraAI 실증)
|
||||
- [[모바일 개발 가이드]]
|
||||
- [[백엔드 API 개발 가이드]]
|
||||
- [[AI 에이전트 개발 가이드]] (AstraAI 실증)
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
가이드의 "Recommended" 는 *기본값* 이며, 프레임워크/스택 선택은 팀·생태계·규모로 조정. 공통 원리는 [[프로젝트 독립 설계 원칙]] 으로 수렴.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
데스크탑·AI 에이전트 가이드는 AstraAI 가 실제 구현한 사례로 뒷받침된다.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[Topic Programming 인덱스]]
|
||||
- **관련 개념:** [[패턴 카탈로그 인덱스]] · [[프로젝트 독립 설계 원칙]] · [[소프트웨어 실패 라이브러리]]
|
||||
- **참조 맥락:** 작은 모델이 특정 플랫폼 프로젝트를 시작할 때의 상위 설계 가이드.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] Platform_Guides 전체 + 일반 공학 지식 + AstraAI 실증
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 플랫폼 개발 가이드 인덱스 생성.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
id: platform-ai-agent-development
|
||||
title: "AI 에이전트 개발 가이드"
|
||||
category: "Platform_Engineering"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["AI agent development", "AI 에이전트 개발", "LLM app", "agent architecture", "RAG agent"]
|
||||
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: ["platform", "ai", "agent", "llm", "guide", "platform-independent"]
|
||||
raw_sources: ["일반 AI 에이전트 공학 지식", "AstraAI 전체 (실증 사례)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[AI 에이전트 개발 가이드]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
AI 에이전트 개발의 핵심은 "**검색(RAG)·기억(Memory)·도구(Tool)·검증(Critic)·오케스트레이션**" 을 자원 제약에 맞게 조합하는 것 — 특히 작은 로컬 모델에선 *결정론 우선·강한 grounding·자기검증* 이 품질을 가른다. AstraAI 전체가 이 가이드의 실증이다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
컨텍스트 조립, RAG, 다계층 메모리, 도구 호출, 자기검증/critic, 프롬프트 엔지니어링, 멀티에이전트 오케스트레이션, 모델 라우팅/폴백.
|
||||
|
||||
## 📖 세부 내용 (Details · 12-field)
|
||||
- **Problem:** LLM(특히 작은 모델)으로 신뢰 가능·근거 있는·행동하는 시스템을 만들기.
|
||||
- **Recommended Architecture:** 턴 파이프라인(컨텍스트 조립 → 라우팅 → 생성 → 후처리/검증 → 학습) + RAG + 메모리 + 도구 + 검증 레이어. 흐름 골격은 한 곳([[Agent 오케스트레이터 분해]]).
|
||||
- **Folder Structure:** `src/{retrieval/, memory/, intelligence/(검증), agent/(handlePrompt,llm,actions), providers/, lib/contextBuilders/}` — AstraAI 구조.
|
||||
- **Core Components:** RAG([[RAG Pattern]]), 메모리([[Memory Pattern]]), 도구 실행([[Tool Calling Pattern]]), 검증([[Critic Pattern]]/[[Reflection Pattern]]), 프롬프트 빌더([[프롬프트 엔지니어링 패턴]]), 프로바이더([[LLM 프로바이더 추상화]]).
|
||||
- **State Management:** 대화=단기 메모리, 지식=RAG/장기, 작업 상태=세션 store. 컨텍스트는 토큰 예산 내 선별.
|
||||
- **Error Handling:** 엔진 폴백, 빈 응답 soft failure, JSON 강건 파싱, 환각 가드([[Error Handling Pattern]], [[Intelligence 검증 레이어]]).
|
||||
- **Testing Strategy:** 순수 함수 단위(토크나이저/스코어/파서), 검색 평가 하니스(recall@k/MRR), 회귀 케이스(정정 재검사), 프롬프트 골든셋.
|
||||
- **Scaling Strategy:** 인덱스 캐시(mtime), 토큰 예산, 순차/자원 인지 동시성, sleep-time 사전소화, 클라우드 폴백.
|
||||
- **Common Mistakes:** 에이전트 남발(hop 손실), 임베딩 단독 의존, 매 턴 LLM 검수(비용), JSON 직접 파싱, 모델 출력 무검증 실행, system 없는 호출(작은 모델 거절).
|
||||
- **Refactoring Patterns:** 5-persona→단일 작성자([[ADR-0003 단일작성자 다중역할 멀티에이전트]]), 동적→정적, 휴리스틱→골든셋 보정, 프롬프트 블록화.
|
||||
- **Real-world Tradeoffs:** 로컬(프라이버시/비용 ↔ 품질) vs 클라우드, 결정론(가용/설명 ↔ 의미) vs 임베딩, 검증 깊이(정확 ↔ latency), 멀티에이전트(다양성 ↔ 자원/손실).
|
||||
- **Design Heuristics:** "결정론 우선, 의미는 가산", "작은 모델엔 강한 system+명시 규칙", "근거 없으면 모른다", "검증 비용은 위험에 비례", "에이전트 추가 전 정보 손실 점검", "동시성은 하드웨어가 결정".
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"더 큰 모델·더 많은 에이전트" 가 답이 아니다 — 자원 제약 하에선 *잘 설계된 RAG+메모리+검증* 이 작은 모델을 크게 끌어올린다. 이 위키 자체가 그 전략(제2뇌)의 산물.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI(Astra) — RAG/메모리/검증/멀티에이전트의 통합 실증. 본 위키 [[AstraAI 아키텍처 개요]] 및 AI_Training 시리즈.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[플랫폼 개발 가이드 인덱스]]
|
||||
- **관련 개념:** [[RAG Pattern]], [[Memory Pattern]], [[Agent Orchestration Pattern]], [[Critic Pattern]], [[Tool Calling Pattern]], [[Intelligence 검증 레이어]]
|
||||
- **참조 맥락:** 작은 모델이 *자기 같은* AI 에이전트 시스템을 설계할 때 최상위 가이드로 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 AI 에이전트/LLM 앱 공학 지식
|
||||
- [S2] AstraAI 전체 — 실증 사례
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 플랫폼 독립 AI 에이전트 개발 가이드 초안.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
id: platform-desktop-development
|
||||
title: "데스크탑 앱 개발 가이드"
|
||||
category: "Platform_Engineering"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["desktop development", "데스크탑 개발", "Electron", "VS Code extension", "native app"]
|
||||
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: ["platform", "desktop", "electron", "guide", "platform-independent"]
|
||||
raw_sources: ["일반 데스크탑 공학 지식", "AstraAI(VS Code 확장) 적용 예"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[데스크탑 앱 개발 가이드]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
데스크탑 앱의 핵심은 "**프로세스 분리(UI↔백그라운드)·생명주기/자원 관리·확장성·로컬 저장**" 이며, AstraAI(VS Code 확장)가 이 원리들의 실증 사례다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
메인/렌더러 프로세스, IPC, 생명주기(activate/dispose), 로컬 파일/설정/시크릿, 플러그인 확장, 백그라운드 워커.
|
||||
|
||||
## 📖 세부 내용 (Details · 12-field)
|
||||
- **Problem:** OS 자원 접근·장시간 실행·로컬 데이터·반응적 UI 를 안정적으로.
|
||||
- **Recommended Architecture:** 얇은 entry(조립) + 계층 분리(인프라/도메인/기능) + IPC 로 UI 분리 + 플러그인 확장 지점. ([[AstraAI 아키텍처 개요]])
|
||||
- **Folder Structure:** `src/{core/(인프라), lib/도메인, features/<기능>, ui|webview, integrations}` + entry(activate/main).
|
||||
- **Core Components:** entry point, IPC 브리지([[IPC Pattern]]), 명령 레지스트리([[Command Pattern]]), 이벤트 버스([[Event Bus Pattern]]), 워커 큐([[Background Worker Pattern]]), 로컬 저장([[Local Storage Pattern]]).
|
||||
- **State Management:** 메인 프로세스가 진실 소유, UI 는 메시지로 변경 요청([[State Management Pattern]]). 설정은 단일 getConfig.
|
||||
- **Error Handling:** 사용자 친화 번역, 부가 작업 격리(빈 catch+이유), 보상 트랜잭션([[Error Handling Pattern]]).
|
||||
- **Testing Strategy:** 순수 도메인 단위 테스트(핵심), IPC/통합 테스트, UI 스모크. (AstraAI: jest + 순수 함수 격리)
|
||||
- **Scaling Strategy:** 무거운 작업 워커/순차([[ADR-0004 순차 디스패치 채택]]), 지연 로드(동적 import), 인덱스 캐시([[Caching Pattern]]).
|
||||
- **Common Mistakes:** disposable 미등록(누수), UI 스레드 무거운 작업, 외부 IPC 입력 미검증, 동적 import 남발, 전역 상태 산재.
|
||||
- **Refactoring Patterns:** entry 얇게(조립만), god-class 골격+추출([[ADR-0010 오케스트레이터 골격 모듈추출]]), 동적→정적 import, 중복→공통 모듈.
|
||||
- **Real-world Tradeoffs:** Electron(생산성·크로스플랫폼 ↔ 메모리·번들 크기), 네이티브(성능 ↔ 플랫폼별 코드), 프로세스 분리(격리·보안 ↔ 직렬화 비용).
|
||||
- **Design Heuristics:** "모든 자원은 dispose 등록", "한 번에 한 모델/무거운 자원", "외부 입력은 신뢰 안 함", "흐름 골격은 한 곳".
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
Electron 은 편하지만 무겁다 — 경량이 중요하면 Tauri/네이티브. 자원 제약(메모리/GPU)이 동시성·아키텍처를 좌우한다(AstraAI 의 핵심 교훈).
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI(Astra) VS Code 확장 — 본 위키 [[AstraAI 아키텍처 개요]] 전체가 실증.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[플랫폼 개발 가이드 인덱스]]
|
||||
- **관련 개념:** [[IPC Pattern]], [[Event Bus Pattern]], [[Command Pattern]], [[Plugin Architecture Pattern]], [[Background Worker Pattern]], [[VSCode 확장 구조와 생명주기]]
|
||||
- **참조 맥락:** 작은 모델이 데스크탑/확장 앱을 설계할 때 상위 가이드로 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 데스크탑(Electron/확장) 공학 지식
|
||||
- [S2] AstraAI — 실증 사례
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 플랫폼 독립 데스크탑 개발 가이드 초안.
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
id: platform-mobile-development
|
||||
title: "모바일 개발 가이드"
|
||||
category: "Platform_Engineering"
|
||||
status: "draft"
|
||||
verification_status: "conceptual"
|
||||
canonical_id: ""
|
||||
aliases: ["mobile development", "모바일 개발", "iOS", "Android", "React Native", "Flutter"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.85
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["platform", "mobile", "guide", "platform-independent"]
|
||||
raw_sources: ["일반 모바일 공학 지식"]
|
||||
applied_in: []
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[모바일 개발 가이드]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
모바일 개발의 고유 제약은 "**불안정 네트워크·제한된 자원·OS 백그라운드 제약·생명주기**" 이며, 이를 *오프라인 우선·로컬 저장·백그라운드 작업·내비게이션* 패턴으로 다루는 것이 핵심이다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
앱 생명주기(foreground/background), 오프라인 우선, 로컬 저장, 푸시, 내비게이션 스택, 권한.
|
||||
|
||||
## 📖 세부 내용 (Details · 12-field)
|
||||
- **Problem:** 끊기는 네트워크·제한 메모리/배터리·OS 제약 하에서 반응적이고 신뢰 가능한 앱.
|
||||
- **Recommended Architecture:** 오프라인 우선(로컬 저장이 진실) + 동기화 계층 + 화면/도메인 분리(MVVM/Clean) + 내비게이션 라우터.
|
||||
- **Folder Structure:** `lib|src/{features/<feature>/{ui,viewmodel,data}, core/(network,storage,di), navigation}`.
|
||||
- **Core Components:** 로컬 DB([[Local Storage Pattern]]), 동기화([[Offline Sync Pattern]]), API 클라이언트([[API Client Pattern]]), 푸시([[Push Notification Pattern]]), 내비게이션([[Navigation Pattern]]), 백그라운드([[Background Task Pattern]]).
|
||||
- **State Management:** ViewModel/store(Bloc/Riverpod/Redux) + 서버 상태 분리 + 화면 상태 복원([[State Management Pattern]]).
|
||||
- **Error Handling:** 네트워크 실패 우아 처리(오프라인 표시·재시도), 낙관적 업데이트 롤백([[Error Handling Pattern]]).
|
||||
- **Testing Strategy:** 단위(ViewModel/로직), 위젯/컴포넌트, 통합/E2E(Detox/Espresso). 디바이스 매트릭스.
|
||||
- **Scaling Strategy:** 이미지/리스트 가상화, 지연 로드, 배터리/네트워크 인지 동기화, 모듈화.
|
||||
- **Common Mistakes:** 메인 스레드 무거운 작업(jank), 토큰 평문 저장, 알림 전달 가정, 생명주기 무시(누수), offset 페이징.
|
||||
- **Refactoring Patterns:** UI-로직 분리(ViewModel 추출), 동기화 계층 분리, 거대 위젯 분해, 네트워크 클라이언트 통합.
|
||||
- **Real-world Tradeoffs:** 크로스플랫폼(RN/Flutter: 생산성 ↔ 네이티브 한계), 네이티브(성능/플랫폼 기능 ↔ 2벌 개발), 오프라인(UX ↔ 충돌 복잡도).
|
||||
- **Design Heuristics:** "로컬을 진실로, 서버는 동기화", "메인 스레드를 비워라", "민감정보는 보안 저장소", "알림은 유도, 데이터는 동기화".
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
크로스플랫폼이 항상 답은 아니다 — 고성능/플랫폼 특화 기능이 중요하면 네이티브. OS 백그라운드 제약은 "정시 실행" 가정을 깬다.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
일반 모바일 앱. AstraAI 직접 사례 없으나 오프라인/저장/백그라운드 원리는 [[패턴 카탈로그 인덱스]] 공유.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[플랫폼 개발 가이드 인덱스]]
|
||||
- **관련 개념:** [[Offline Sync Pattern]], [[Local Storage Pattern]], [[Background Task Pattern]], [[Push Notification Pattern]], [[Navigation Pattern]]
|
||||
- **참조 맥락:** 작은 모델이 모바일 앱을 설계할 때 상위 가이드로 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 모바일(iOS/Android/RN/Flutter) 공학 지식
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 플랫폼 독립 모바일 개발 가이드 초안.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
id: platform-backend-api-development
|
||||
title: "백엔드 API 개발 가이드"
|
||||
category: "Platform_Engineering"
|
||||
status: "draft"
|
||||
verification_status: "conceptual"
|
||||
canonical_id: ""
|
||||
aliases: ["backend development", "백엔드 개발", "API design", "REST", "서버 아키텍처", "microservices"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.86
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["platform", "backend", "api", "guide", "platform-independent"]
|
||||
raw_sources: ["일반 백엔드 공학 지식", "AstraAI/src/bridge.ts (소규모 서버 적용 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[백엔드 API 개발 가이드]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
백엔드의 핵심은 "**계층 분리·명확한 API 계약·데이터 일관성·복원력(재시도/멱등/한도)·관측성**" 이며, 화려한 프레임워크보다 이 기본기가 신뢰성을 만든다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
계층(라우터→서비스→리포지토리), API 계약(REST/GraphQL/RPC), 트랜잭션, 인증/인가, 멱등성, 레이트 리밋, 로깅/메트릭.
|
||||
|
||||
## 📖 세부 내용 (Details · 12-field)
|
||||
- **Problem:** 동시 다수 클라이언트에 일관·안전·확장 가능한 데이터/로직 제공.
|
||||
- **Recommended Architecture:** 계층형(라우터/컨트롤러 → 서비스(도메인) → 리포지토리(데이터)) + DTO 경계 + 의존성 주입. ([[Architecture Separation Pattern]])
|
||||
- **Folder Structure:** `src/{routes|controllers, services, repositories, domain/models, middleware, infra(db,cache,queue), config}`.
|
||||
- **Core Components:** 라우터/미들웨어, 서비스, 리포지토리([[Repository Pattern]]), 인증([[JWT Authentication Pattern]]), 캐시([[Caching Pattern]]), 큐/워커([[Background Worker Pattern]]), 에러 핸들러.
|
||||
- **State Management:** 상태는 DB/캐시(서버는 가급적 무상태), 세션/토큰, 분산 락. SSOT.
|
||||
- **Error Handling:** 표준 에러 응답(코드/메시지), 재시도(backoff)/서킷 브레이커, 멱등 키, 트랜잭션 롤백([[Error Handling Pattern]]).
|
||||
- **Testing Strategy:** 단위(서비스/도메인), 통합(DB/리포), 계약 테스트(API), 부하 테스트.
|
||||
- **Scaling Strategy:** 수평 확장(무상태), 캐시 계층, 읽기 복제/샤딩, 비동기 큐, 레이트 리밋, CDN.
|
||||
- **Common Mistakes:** 컨트롤러에 비즈니스 로직, N+1 쿼리, 멱등성 부재(중복 처리), 트랜잭션 경계 오류, 검증 누락, 무한 재시도.
|
||||
- **Refactoring Patterns:** 컨트롤러→서비스 로직 이동, 쿼리→리포지토리 캡슐화, 공통→미들웨어, 동기→큐 비동기화.
|
||||
- **Real-world Tradeoffs:** 모놀리스(단순·일관 ↔ 확장/배포 결합) vs 마이크로서비스(독립 확장 ↔ 분산 복잡도/일관성), SQL(일관성 ↔ 확장) vs NoSQL(확장 ↔ 일관성), REST vs GraphQL.
|
||||
- **Design Heuristics:** "서버 무상태로", "쓰기는 멱등하게", "경계에서 검증", "느린 작업은 큐로", "관측 가능하게(로그/메트릭/트레이스)".
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
마이크로서비스가 기본값은 아니다 — 대부분 모놀리스(또는 모듈러 모놀리스)로 시작해 *필요할 때* 분리하는 것이 안전(분산은 비싸다).
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI BridgeServer(로컬 HTTP, 서비스 레이어로 로직 분리 — 소규모 백엔드의 계층 분리 예) [S2].
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[플랫폼 개발 가이드 인덱스]]
|
||||
- **관련 개념:** [[Repository Pattern]], [[API Client Pattern]], [[JWT Authentication Pattern]], [[Caching Pattern]], [[Event Bus Pattern]], [[이벤트 소싱 스토어 패턴]]
|
||||
- **참조 맥락:** 작은 모델이 서버/API 를 설계할 때 상위 가이드로 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 백엔드/API 공학 지식
|
||||
- [S2] AstraAI/src/bridge.ts — 소규모 서버 계층 분리 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 플랫폼 독립 백엔드 개발 가이드 초안.
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
id: platform-web-development
|
||||
title: "웹 개발 가이드"
|
||||
category: "Platform_Engineering"
|
||||
status: "draft"
|
||||
verification_status: "conceptual"
|
||||
canonical_id: ""
|
||||
aliases: ["web development", "웹 개발", "frontend", "SPA", "프런트엔드 아키텍처"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.86
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["platform", "web", "frontend", "guide", "platform-independent"]
|
||||
raw_sources: ["일반 웹 공학 지식"]
|
||||
applied_in: []
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[웹 개발 가이드]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
웹 개발의 본질은 프레임워크가 아니라 "**상태·비동기·데이터 흐름·에러·계층 분리**" 라는 반복 문제를 푸는 것 — 도구는 바뀌어도 원리는 [[패턴 카탈로그 인덱스]] 의 cross-cutting 패턴으로 수렴한다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
선언형 UI, 컴포넌트, 단방향 데이터, 서버/클라 상태 분리, 라우팅, 번들링/코드 분할.
|
||||
|
||||
## 📖 세부 내용 (Details · 12-field)
|
||||
- **Problem:** 다양한 디바이스/브라우저에서 반응적이고 유지보수 가능한 UI 와 데이터 동기화.
|
||||
- **Recommended Architecture:** 컴포넌트 기반 + 단방향 데이터 + 서버 상태 라이브러리(react-query) + 기능별 폴더(feature-sliced). 무거운 로직은 도메인 계층으로 분리.
|
||||
- **Folder Structure:** `src/{features/<feature>/{ui,api,model}, shared/{ui,lib,api}, app/(라우팅·프로바이더)}`. 기능 슬라이스 + 공유 계층.
|
||||
- **Core Components:** 라우터, 데이터 페칭 계층([[API Client Pattern]]), 상태 store([[State Management Pattern]]/[[React State Pattern]]), 디자인 시스템, 에러 바운더리.
|
||||
- **State Management:** 지역=useState, 서버=쿼리 캐시, 공유 도메인=가벼운 store, 공유 가능 상태=URL. (SSOT·단방향)
|
||||
- **Error Handling:** 에러 바운더리(렌더 에러), 쿼리 에러/리트라이, 사용자 친화 메시지([[Error Handling Pattern]]).
|
||||
- **Testing Strategy:** 단위(순수 로직)·컴포넌트(Testing Library)·E2E(Playwright). 피라미드(단위 多, E2E 少).
|
||||
- **Scaling Strategy:** 코드 분할/지연 로드, 가상화([[Infinite Scroll Pattern]]), CDN/캐시, SSR/SSG(초기 로드·SEO), 이미지 최적화.
|
||||
- **Common Mistakes:** 서버 데이터를 로컬 상태에 복사(stale), 전역 store 남용(리렌더), prop drilling, 거대 컴포넌트, 무분별 useEffect.
|
||||
- **Refactoring Patterns:** 거대 컴포넌트 분해, 로직→커스텀 훅 추출, 페칭→쿼리 계층 이동, prop drilling→context/store.
|
||||
- **Real-world Tradeoffs:** SSR(성능·SEO ↔ 복잡도), 전역 상태(편의 ↔ 결합), 마이크로프런트엔드(독립 배포 ↔ 운영 부담).
|
||||
- **Design Heuristics:** "상태는 가장 낮은 곳, 공유되면 올린다", "서버 상태와 UI 상태 분리", "파생은 계산", "경계에서 검증".
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
프레임워크(React/Vue/Svelte)는 수단 — 채용/생태계로 고르되, 위 원리는 공통. "최신 프레임워크" 추종보다 상태/데이터 흐름 설계가 품질을 가른다.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
일반 SPA/웹앱. AstraAI 웹뷰 UI 도 상태/메시지 원리는 동일.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[플랫폼 개발 가이드 인덱스]]
|
||||
- **관련 개념:** [[State Management Pattern]], [[React State Pattern]], [[API Client Pattern]], [[JWT Authentication Pattern]], [[Infinite Scroll Pattern]]
|
||||
- **참조 맥락:** 작은 모델이 웹 프로젝트를 설계/구현할 때 상위 가이드로 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 웹/프런트엔드 공학 지식
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 플랫폼 독립 웹 개발 가이드 초안.
|
||||
Reference in New Issue
Block a user