refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조

에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-11 11:05:56 +09:00
parent 6549ead309
commit c24165b8bc
6193 changed files with 1717 additions and 31 deletions
@@ -0,0 +1,184 @@
+---
+id: wiki-2026-0508-composables
+title: Composables (Vue)
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [Vue Composables, useX functions]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.9
+verification_status: applied
+tags: [vue, composition-api, composables, frontend]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: TypeScript
+  framework: Vue 3
+---
+
+# Composables (Vue)
+
+## 매 한 줄
+> **"매 reactive logic 의 reusable function"**. Composable 은 Vue 3 Composition API 의 stateful logic 을 추출한 `useX()` 함수 — React Hooks 와 유사하나 매 reactivity primitive (`ref`, `reactive`, `computed`) 기반이라 caller 매 free of dependency arrays.
+
+## 매 핵심
+
+### 매 정의
+- `use*` prefix 매 convention.
+- Returns reactive refs / computed / methods.
+- Side-effects via `onMounted` / `onScopeDispose` (`watchEffect` cleanup).
+- `effectScope` 매 manual lifecycle (e.g., outside components).
+
+### 매 vs React Hooks
+| Aspect | Vue Composable | React Hook |
+|---|---|---|
+| Re-run | 매 once on setup | every render |
+| Deps | reactive auto-track | manual array |
+| Cleanup | `onScopeDispose` | return fn |
+| Conditional call | 허용 (with caveats) | 금지 |
+
+### 매 응용
+1. `useFetch` / `useAsyncData` — async + cancellation.
+2. `useElementSize`, `useEventListener` — DOM bindings (VueUse).
+3. `useStore`, `useFeatureFlag` — cross-cutting state.
+
+## 💻 패턴
+
+### Basic counter composable
+```ts
+import { ref, computed } from 'vue';
+
+export function useCounter(initial = 0) {
+  const count = ref(initial);
+  const isZero = computed(() => count.value === 0);
+  const inc = () => count.value++;
+  const dec = () => count.value--;
+  return { count, isZero, inc, dec };
+}
+```
+
+### useFetch with abort + reactive URL
+```ts
+import { ref, watchEffect, onScopeDispose, type MaybeRefOrGetter, toValue } from 'vue';
+
+export function useFetch<T>(url: MaybeRefOrGetter<string>) {
+  const data = ref<T | null>(null);
+  const error = ref<Error | null>(null);
+  const loading = ref(false);
+  let ctrl: AbortController | null = null;
+
+  watchEffect(async () => {
+    ctrl?.abort();
+    ctrl = new AbortController();
+    loading.value = true;
+    try {
+      const r = await fetch(toValue(url), { signal: ctrl.signal });
+      data.value = await r.json();
+    } catch (e) {
+      if ((e as Error).name !== 'AbortError') error.value = e as Error;
+    } finally {
+      loading.value = false;
+    }
+  });
+
+  onScopeDispose(() => ctrl?.abort());
+  return { data, error, loading };
+}
+```
+
+### useEventListener (auto cleanup)
+```ts
+import { onMounted, onScopeDispose, type Ref } from 'vue';
+
+export function useEventListener<K extends keyof WindowEventMap>(
+  target: Window | Ref<HTMLElement | null>,
+  event: K,
+  handler: (e: WindowEventMap[K]) => void,
+) {
+  onMounted(() => {
+    const el = 'value' in target ? target.value : target;
+    el?.addEventListener(event, handler as EventListener);
+  });
+  onScopeDispose(() => {
+    const el = 'value' in target ? target.value : target;
+    el?.removeEventListener(event, handler as EventListener);
+  });
+}
+```
+
+### useLocalStorage (sync ref ↔ storage)
+```ts
+import { ref, watch } from 'vue';
+
+export function useLocalStorage<T>(key: string, initial: T) {
+  const stored = localStorage.getItem(key);
+  const value = ref<T>(stored ? JSON.parse(stored) : initial);
+  watch(value, (v) => localStorage.setItem(key, JSON.stringify(v)), { deep: true });
+  return value;
+}
+```
+
+### useDebouncedRef
+```ts
+import { customRef } from 'vue';
+
+export function useDebouncedRef<T>(value: T, delay = 300) {
+  let t: ReturnType<typeof setTimeout>;
+  return customRef<T>((track, trigger) => ({
+    get() { track(); return value; },
+    set(v) {
+      clearTimeout(t);
+      t = setTimeout(() => { value = v; trigger(); }, delay);
+    },
+  }));
+}
+```
+
+### Detached scope (composable outside component)
+```ts
+import { effectScope } from 'vue';
+
+const scope = effectScope();
+scope.run(() => {
+  const counter = useCounter();
+  // ... use anywhere
+});
+// later
+scope.stop();
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| Component-local state | `ref` directly |
+| Logic reused in 2+ components | Composable |
+| Global state (auth, theme) | Pinia store (composable underneath) |
+| DOM API integration | VueUse composable or custom |
+
+**기본값**: 매 reusable reactive logic → composable. Single-use → inline.
+
+## 🔗 Graph
+- 부모: [[Composition API]] · [[Vue 3]]
+- 응용: [[Pinia]]
+- Adjacent: [[Component-Composition]]
+
+## 🤖 LLM 활용
+**언제**: stateful logic 매 2+ components 에서 사용 / DOM·async 의 lifecycle wrapping.
+**언제 X**: 매 pure function (no reactivity) — 매 plain util 로 충분.
+
+## ❌ 안티패턴
+- **Returning reactive() with destructure**: loses reactivity → use `toRefs`.
+- **Global side-effects in composable body**: 매 `onMounted` 안에 넣을 것.
+- **Naming without `use` prefix**: 매 convention break, lint rule 매 fail.
+
+## 🧪 검증 / 중복
+- Verified (Vue.js docs / VueUse source).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — Vue 3 composables with patterns |