@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/fe/principles/react.md

@@ -0,0 +1,183 @@
+---
+title: React 19 + Next.js 16 원칙
+version: 2026-05-18
+sources:
+  - sources/react/
+  - sources/perf/06-nextjs-caching.md
+  - sources/perf/07-server-components.md
+  - sources/perf/08-ppr.md
+---
+
+# React 19 + Next.js 16 원칙
+
+> [공통 원칙](./common.md)을 먼저 따르고, 아래는 React/Next 특화.
+
+## R0. 의사결정 우선순위
+
+1. **Server Component 기본, Client는 필요할 때만** (Next.js App Router)
+2. **React Compiler가 자동 메모이제이션** — `useMemo`/`useCallback` 수동 작성 지양
+3. **Effect 회피** — `useEffect`는 *외부 시스템 동기화* 용도. 데이터 변환/이벤트 처리에 쓰지 않는다.
+4. **Action + form 통합** — `<form action={...}>` 와 `useActionState` 우선, 수동 상태 관리 지양
+
+---
+
+## R1. Server vs Client Components
+
+근거: `sources/perf/07-server-components.md`, `sources/react/server-components.md`
+
+### Server Component 기본값
+
+- 모든 컴포넌트는 RSC가 기본. `'use client'` 안 붙이면 서버.
+- 서버에서만: `async`/`await` 직접 사용, DB 접근, 환경변수, 대용량 라이브러리(markdown/syntax-highlight 등)
+
+### Client Component 가 필요한 신호
+
+- `useState`/`useReducer`/`useEffect`
+- 브라우저 API (`window`, `localStorage`, `IntersectionObserver`)
+- 이벤트 핸들러 (`onClick`, `onChange`)
+- 커스텀 훅 사용
+
+### 패턴
+
+- **Client 컴포넌트 안에 Server 컴포넌트를 자식으로 주입**한다 (`children` prop). RSC → Client 역방향 import 금지.
+- **환경 오염 방지**: 서버 전용 코드는 `'server-only'` 패키지로 클라이언트 import 차단.
+
+---
+
+## R2. Effect 회피 (you-might-not-need-an-effect)
+
+근거: `sources/react/no-effect-patterns.md`
+
+| 잘못된 Effect | 대체 |
+|---------------|------|
+| props/state 기반 파생 값 계산 | 렌더 중 계산. 비싸면 `useMemo` (Compiler 시 자동) |
+| 이벤트 핸들러 로직을 Effect로 옮김 | 이벤트 핸들러 안에서 처리 |
+| state 변경 시 다른 state 갱신 (체인) | 한 핸들러 안에서 둘 다 갱신 |
+| 상위 변경 알림 (`useEffect(() => onChange(value), [value])`) | 변경 발생 핸들러 안에서 `onChange` 호출 |
+| props 변경 시 state 초기화 | `key` prop 으로 컴포넌트 리마운트 |
+| 데이터 페칭 | React Query/SWR 또는 Suspense + `use()` |
+
+**남는 Effect 용도**: 외부 시스템 구독 (WebSocket, IntersectionObserver, 브라우저 API).
+
+---
+
+## R3. React 19 신 API
+
+### R3.1 `use()` — Promise/Context 읽기
+
+근거: `sources/react/use-hook.md`
+
+- 조건부 호출 가능 (Hook 규칙 예외)
+- Suspense 경계와 함께 사용
+- Server Component 의 `async`/`await` 가 안되는 Client 컴포넌트에서 데이터 읽기 용도
+
+### R3.2 `<form action>` + `useActionState` + `useFormStatus`
+
+근거: `sources/react/use-action-state.md`, `sources/react/use-form-status.md`
+
+```tsx
+'use client';
+import { useActionState } from 'react';
+import { useFormStatus } from 'react-dom';
+
+function SubmitButton() {
+  const { pending } = useFormStatus();
+  return <button disabled={pending}>{pending ? '제출 중...' : '제출'}</button>;
+}
+
+export function Form({ action }: { action: (state, fd) => Promise<State> }) {
+  const [state, formAction] = useActionState(action, { error: null });
+  return (
+    <form action={formAction}>
+      <input name="email" />
+      {state.error && <p role="alert">{state.error}</p>}
+      <SubmitButton />
+    </form>
+  );
+}
+```
+
+- 폼 라이브러리 도입 전 우선 검토. 단순 폼은 의존성 0로 가능.
+
+### R3.3 `useOptimistic` — 낙관적 UI
+
+근거: `sources/react/use-optimistic.md`
+
+- 서버 응답 전 즉시 UI 반영, 실패 시 자동 롤백
+- 메시지 전송, 좋아요 토글 같은 인터랙션 INP 개선에 결정적
+
+---
+
+## R4. React Compiler
+
+근거: `sources/react/react-compiler.md`
+
+- **`useMemo`/`useCallback`/`memo` 를 수동으로 쓰지 마라**. Compiler가 자동 메모이즈한다.
+- 도입 시 ESLint plugin (`eslint-plugin-react-compiler`) 으로 Rules of React 위반 검출.
+- Compiler가 메모이즈 못 하는 코드 → "왜 메모 못 했는지" 진단하고 수정. 수동 useMemo 회피.
+- **예외**: Compiler 미적용 프로젝트는 기존대로 명시적 메모이제이션 유지.
+
+---
+
+## R5. Suspense + Streaming
+
+근거: `sources/react/suspense.md`
+
+- Suspense 경계를 **데이터 단위가 아니라 사용자 인식 단위**로 그어라. "이 부분 따로 보여도 되나?" 기준.
+- 중첩 Suspense → 순차 스트리밍. 상위가 늦으면 하위 모두 대기.
+- `startTransition` 으로 후속 인터랙션에서 fallback 깜빡임 방지.
+
+---
+
+## R6. Next.js 16 캐싱 4계층
+
+근거: `sources/perf/06-nextjs-caching.md`
+
+| 계층 | 위치 | 무효화 |
+|------|------|--------|
+| **Request Memoization** | 단일 렌더 중 fetch 중복 제거 | 자동 (렌더 종료) |
+| **Data Cache** | 서버, 영구 | `revalidateTag` / `revalidatePath` / time |
+| **Full Route Cache** | 빌드 또는 ISR | `revalidatePath` |
+| **Router Cache** | 클라이언트, 세션 | 네비게이션 / `router.refresh()` |
+
+- `fetch(url, { next: { tags: ['posts'], revalidate: 60 } })` 표준
+- `unstable_cache` / `use cache` (Next 16) — 외부 데이터 함수 캐싱
+- **변경 액션 후 반드시 `revalidateTag('posts')` 호출** (캐시 일관성)
+
+---
+
+## R7. PPR (Partial Prerendering)
+
+근거: `sources/perf/08-ppr.md`
+
+- 정적 shell + Suspense 경계로 동적 부분 스트리밍
+- Next.js 16의 `cacheComponents` 플래그 (PPR + use cache + dynamicIO 통합)
+- 정적 캐시 가능한 부분이 큰 페이지 (상품 상세, 게시글)에서 TTFB·LCP 결정적 개선
+
+---
+
+## R8. 이미지 (next/image)
+
+근거: `sources/perf/09-nextjs-image.md`
+
+- LCP 후보 이미지에 `priority` (`fetchpriority="high"` + preload)
+- `fill` + 컨테이너 `position: relative` 또는 `width`/`height` 명시 (CLS 방지)
+- `sizes` 로 반응형 이미지 정확히 명세 — 미명세 시 1배 이미지가 모바일에 다운로드됨
+- `placeholder="blur"` 는 LCP 미세 개선 + UX 향상
+
+---
+
+## R9. React 안티패턴 카탈로그
+
+| 안티패턴 | 픽스 |
+|----------|------|
+| `useEffect` 안에서 `setState` 후 데이터 변환 | 렌더 중 파생 값 계산 |
+| `useState` + `useEffect` 로 fetch | Suspense + `use()` 또는 React Query |
+| Compiler 환경에서 수동 `useMemo` 추가 | 제거. Compiler 못 메모하면 코드 수정 |
+| Client 컴포넌트가 Server 컴포넌트 import | `children` prop 으로 주입 |
+| Server Component 안에 `useState` | `'use client'` 추가 또는 분리 |
+| `'use client'` 파일에 대형 의존성 import | Server 분리 또는 dynamic import |
+| Form 상태를 `useState` 로 수동 관리 | `<form action>` + `useActionState` |
+| `Image` 없이 `<img>` | `next/image` (또는 명시적 `width/height`) |
+| `next/dynamic` 남발 | RSC가 더 적합한지 먼저 검토 |
+| Effect 안에서 `router.push` | 이벤트 핸들러로 이동 |

package/assets/dev-guide/fe/principles/vue.md

@@ -0,0 +1,196 @@
+---
+title: Vue 3 + Nuxt 3 원칙
+version: 2026-05-18
+sources:
+  - sources/vue/
+---
+
+# Vue 3 + Nuxt 3 원칙
+
+> [공통 원칙](./common.md)을 먼저 따르고, 아래는 Vue/Nuxt 특화.
+
+## V0. 의사결정 우선순위
+
+1. **Composition API + `<script setup>` 우선** (Options API 신규 코드에서 지양)
+2. **반응성 손실 절대 회피** — props 비구조화, reactive 객체 비구조화는 금지
+3. **상태는 컴포넌트 → composable → Pinia** 순으로 승격 (필요할 때만)
+4. **Nuxt: SSR 경계 의식** — `useFetch`/`useAsyncData` 로 hydration 일관성 보장
+
+---
+
+## V1. 스타일 가이드 4단계
+
+근거: `sources/vue/style-guide-priority-a.md` ~ `priority-d.md`
+
+### V1.1 Priority A (Essential — 위반 시 [HIGH])
+
+- **다중 단어 컴포넌트 이름**. `Todo` 금지 → `TodoItem` (HTML 표준 충돌 회피)
+- **`v-for` 에 `key` 필수**. `<li v-for="item in list" :key="item.id">`
+- **`v-if` + `v-for` 같이 쓰지 마라**. 컴퓨티드로 필터링 후 `v-for`
+- **컴포넌트 데이터는 함수 반환** (Options API의 경우)
+- **prop 정의는 타입까지 명세** (`defineProps<{...}>()` 또는 객체 형식)
+- **컴포넌트 스타일은 scoped**. 전역 클래스명 충돌 회피
+
+### V1.2 Priority B (Strongly Recommended)
+
+- **단일 파일 컴포넌트 (SFC)** 우선
+- **컴포넌트 파일명: PascalCase** (`TodoItem.vue`)
+- **베이스 컴포넌트는 명확한 prefix** (`BaseButton`, `AppLogo`)
+- **싱글톤 컴포넌트는 `The` prefix** (`TheHeader`, `TheSidebar`)
+- **자식 컴포넌트는 부모 이름으로 시작** (`TodoListItem` — 같은 디렉토리 내 응집)
+- **이벤트 이름은 kebab-case** (`@form-submit`)
+
+### V1.3 Priority C (Recommended)
+
+- **컴포넌트/인스턴스 옵션 순서** 일관성
+- **속성 순서**: `is` → `v-for` → `v-if` → `v-bind` → `v-on` → `key`/`ref` 등
+- **단순 컴퓨티드 분해**. 한 컴퓨티드에 모든 로직 X → 작은 컴퓨티드 조합
+
+### V1.4 Priority D (Use with Caution)
+
+- **`scoped` 안에서 element 셀렉터 지양** — 클래스 셀렉터 사용
+- **암묵적 부모-자식 통신 지양** — props/emits 명시
+- **비-Flux 글로벌 상태 관리 지양** — Pinia 사용
+
+---
+
+## V2. Composition API + `<script setup>`
+
+근거: `sources/vue/composition-api.md`
+
+### V2.1 기본 골격
+
+```vue
+<script setup lang="ts">
+import { ref, computed, watch } from 'vue';
+
+const props = defineProps<{ id: string }>();
+const emit = defineEmits<{ change: [value: string] }>();
+
+const count = ref(0);
+const double = computed(() => count.value * 2);
+
+watch(() => props.id, (newId) => {
+  // 외부 시스템 동기화
+});
+</script>
+```
+
+### V2.2 핵심 규칙
+
+- **`<script setup>` 이 신규 코드 기본**. Options API는 레거시/마이그레이션 한정.
+- **`defineProps`/`defineEmits` 는 매크로** — import 불필요, 컴파일 시점 처리
+- **`defineModel()`** (Vue 3.4+) 로 양방향 바인딩 단순화
+- **로직 재사용은 composable** (`useXxx`) — Vue 의 커스텀 훅 패턴
+
+### V2.3 ref vs reactive
+
+- **기본은 `ref`**. 원시값 + 객체 모두 처리, `.value` 일관성
+- **`reactive` 는 객체 한정** + 비구조화 시 반응성 손실 위험
+- **composable 반환은 `ref`/`computed`** 로 통일 (외부에서 비구조화 안전)
+
+---
+
+## V3. 반응성 함정 (반드시 회피)
+
+근거: `sources/vue/reactivity-pitfalls.md`
+
+### V3.1 props 비구조화 (Vue 3.5+ 는 자동 처리)
+
+```ts
+// ❌ 반응성 손실 (3.4 이하)
+const { id } = defineProps<{ id: string }>();
+
+// ✅ 3.4 이하
+const props = defineProps<{ id: string }>();
+const id = computed(() => props.id);
+
+// ✅ 3.5+ 자동 변환 (Reactive Props Destructure)
+const { id } = defineProps<{ id: string }>();
+// 단 watch source 에서는 getter로: watch(() => id, ...)
+```
+
+### V3.2 reactive 비구조화 금지
+
+```ts
+const state = reactive({ count: 0 });
+
+// ❌ 반응성 끊김
+const { count } = state;
+
+// ✅
+const { count } = toRefs(state); // 각 필드 ref 화
+```
+
+### V3.3 ref unwrapping 함정
+
+- **template 안: 자동 unwrap** (`.value` 불필요)
+- **template 안 배열/Map 인덱싱: unwrap 안 됨** → `computed` 로 풀어서 노출
+- **JS 코드: 명시적 `.value`** 필수
+
+---
+
+## V4. 상태 관리 (Pinia)
+
+근거: `sources/vue/pinia-state-management.md`
+
+### V4.1 언제 store로 승격?
+
+- 컴포넌트 → composable: 같은 로직 2+ 컴포넌트에서 사용
+- composable → Pinia store: 인스턴스 공유 필요 (싱글톤) 또는 DevTools/SSR/플러그인 필요
+
+### V4.2 Setup Store 권장 (Composition API 일관성)
+
+```ts
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0);
+  const double = computed(() => count.value * 2);
+  function increment() { count.value++; }
+  return { count, double, increment };
+});
+```
+
+- `state`/`getters`/`actions` Options Store보다 setup store가 SSR/TS 친화적
+
+---
+
+## V5. Nuxt 3 데이터 페칭
+
+근거: `sources/vue/nuxt-data-fetching.md`
+
+### V5.1 페칭 함수 선택 매트릭스
+
+| 함수 | SSR | 클라이언트 hydration | 사용 시점 |
+|------|-----|---------------------|-----------|
+| `useFetch(url)` | ✅ | 자동 dedup | 페이지/컴포넌트 데이터 |
+| `useAsyncData(key, fn)` | ✅ | 자동 dedup | 임의 async 로직 |
+| `useLazyFetch` | ❌ | 마운트 후 | 비차단 데이터 |
+| `$fetch` | ✅(서버) | 수동 | 이벤트 핸들러 안 (form submit 등) |
+
+### V5.2 SSR hydration 일관성
+
+- 페이지 로직: `useFetch`/`useAsyncData` 만 사용. `onMounted` + 페치 금지 (SSR/CSR 불일치 → CLS).
+- 이벤트 트리거 페치: `$fetch` (mutation 응답 받기)
+- **key 명시적으로** — `useAsyncData('order-' + id, ...)` 같이 unique key 필수
+
+### V5.3 server/ 디렉토리 (Nitro)
+
+- BFF 패턴: `server/api/orders.get.ts` 같은 server route
+- 클라이언트는 `useFetch('/api/orders')` 로 호출 → 자동 타입 추론
+
+---
+
+## V6. Vue 안티패턴 카탈로그
+
+| 안티패턴 | 픽스 |
+|----------|------|
+| `v-if` + `v-for` 같이 사용 | computed로 필터링 |
+| `v-for` 에 `key` 누락 또는 index key | 안정적 id |
+| `reactive` 비구조화 | `toRefs` 또는 `ref` 사용 |
+| props 비구조화 (3.4 이하) | `computed(() => props.x)` |
+| Options API와 Composition API 혼용 | Composition으로 통일 |
+| `onMounted` 안에서 페치 (Nuxt) | `useFetch`/`useAsyncData` |
+| `defineProps()` runtime 형식 (TS 프로젝트) | `defineProps<{...}>()` 타입 형식 |
+| `<style>` (scoped 없이) 컴포넌트 스타일 | `<style scoped>` 또는 CSS Module |
+| 전역 watch 남발 | computed 우선 → 외부 시스템 동기화만 watch |
+| Pinia state 직접 변경 (외부에서) | action으로 변경 |

package/assets/dev-guide/fe/skills/react/fe-build/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: fe-build-react
+description: React/Next.js 요구사항을 받아 합의된 사내 원칙대로 구현. 명세→체크리스트→테스트 매핑을 강제하고, Server Components·React Compiler·Action 우선 패턴을 적용한다.
+---
+
+# fe-build (React)
+
+> **호출 시점**: "요구사항 명세 줄게, 이대로 구현해줘" 같은 신규 기능/페이지/컴포넌트 구현 요청.
+> **선행 로딩**: `principles/common.md` + `principles/react.md` 필수.
+
+## 0. 절대 금지
+
+1. 명세 읽기 전에 코드 쓰지 마라.
+2. 명세에 없는 UX 결정 추가하지 마라 (명세 100% 충족 후에만).
+3. 명세에서 "옵셔널"이라고 한 항목 → 안 골라도 통과 테스트 *반드시* 작성.
+4. `useEffect` 안에서 데이터 변환/체인 setState 금지 (`principles/react.md` R2).
+5. Client Component 안에서 Server Component import 금지.
+
+## 1. 워크플로우 (이 순서를 깨지 마라)
+
+### Step 1 — 명세 → 체크리스트 변환
+
+명세 문서(또는 사용자 메시지) 받자마자, **다른 어떤 작업도 하기 전에**:
+
+```markdown
+## 체크리스트
+- [ ] R-01: <명세 요구사항 한 줄>
+- [ ] R-02: ...
+```
+
+각 항목은 **명세 원문 직접 인용**으로 작성. 해석/추론 금지.
+이 체크리스트를 사용자에게 보여주고, 빠진 게 있는지 *확인 후* 다음 단계.
+
+### Step 2 — 체크리스트 → 테스트 라인 매핑표
+
+```markdown
+## 매핑표
+| 요구사항 | 컴포넌트/함수 | 테스트 파일:케이스 |
+|----------|---------------|---------------------|
+| R-01 | OrderForm | OrderForm.test.tsx:"제출 시 ..." |
+| R-02 | useCart | useCart.test.ts:"select 옵션 미선택 시 통과해야 한다" |
+```
+
+**옵셔널 항목은 반드시 "안 골라도 통과" 케이스로 매핑**. 표시(UI 분기)와 검증(로직 분기)이 같은 진실을 보는지 점검 — 이 불일치가 가장 흔한 명세 위반.
+
+### Step 3 — 아키텍처 결정
+
+Server Component 기본. Client Component 가 필요한 신호 (R1) 가 있는 부분만 `'use client'`:
+
+- `useState`/`useEffect` 필요
+- 브라우저 API
+- 이벤트 핸들러
+
+**결정 기록 한 줄** (코드 주석 X, 사용자 메시지로):
+"OrderForm은 Client (제출 핸들러). 상품 목록은 Server (정적)."
+
+### Step 4 — TDD (Red → Green → Refactor)
+
+매핑표의 각 행마다:
+1. 테스트 먼저 작성 (실패 확인)
+2. 최소 구현으로 통과
+3. 리팩터: [`common.md`](../../principles/common.md) 4원칙 적용
+
+### Step 5 — 셀프 리뷰
+
+구현 완료 후 [`fe-review/SKILL.md`](../fe-review/SKILL.md) 의 체크리스트로 자가 점검. 통과 못 한 항목 있으면 Step 4 로 회귀.
+
+### Step 6 — 매핑표 갱신 후 완료 선언
+
+매핑표 모든 행 ✅ + 모든 테스트 green. 그제서야 "완료" 선언.
+
+## 2. 구현 디폴트
+
+### 2.1 데이터 페칭
+
+```tsx
+// Server Component — 기본
+export default async function Page({ params }) {
+  const data = await fetch(`/api/items/${params.id}`, {
+    next: { tags: [`item-${params.id}`], revalidate: 60 }
+  }).then(r => r.json());
+  return <ItemView data={data} />;
+}
+
+// Client Component — 인터랙션 후 mutation
+'use client';
+import { useActionState } from 'react';
+async function submitAction(state, formData) {
+  'use server';
+  await db.update(...);
+  revalidateTag(`item-${id}`); // 캐시 무효화 필수
+  return { ok: true };
+}
+```
+
+### 2.2 폼
+
+- 단순 폼 → `<form action>` + `useActionState` + `useFormStatus`
+- 복잡한 검증 → React Hook Form + zod (조건: 5+ 필드 또는 cross-field 검증)
+- **검증 규칙은 `optional` 케이스 빠뜨리지 마라** (`z.string().optional()` 분기 명시)
+
+### 2.3 상태
+
+- 로컬: `useState`
+- 페이지 단위 파생: `useSearchParams` (URL 단일 진실)
+- 글로벌: Zustand 또는 Jotai (Redux 신규 도입 지양)
+- 서버 상태: React Query (Pages Router) 또는 RSC fetch + revalidate (App Router)
+
+### 2.4 스타일
+
+- Tailwind 또는 CSS Module + 디자인 토큰 (사내 디자인 시스템 우선)
+- `next/image` 강제 (`<img>` 직접 사용 시 [HIGH] 리뷰 대상)
+
+### 2.5 접근성 디폴트
+
+- 폼: `<label htmlFor>` 또는 `aria-label`
+- 버튼 vs 링크: 동작 = `<button>`, 이동 = `<Link>`
+- 모달: `<dialog>` 또는 focus trap 라이브러리 + `aria-modal`
+- 인터랙티브 영역 최소 24×24 CSS px (WCAG 2.5.8)
+
+## 3. 출력 형식
+
+작업 완료 시 사용자에게:
+
+```
+## 완료 보고
+- 체크리스트: 5/5 ✅
+- 매핑표: 모든 행 테스트 green
+- 변경 파일: <목록>
+- 셀프 리뷰: principles/react.md R1-R9 통과
+- 의사결정: <Server/Client 분리 기준 1-2줄>
+```
+
+## 4. 관련 문서
+
+- 원칙: [`principles/common.md`](../../principles/common.md), [`principles/react.md`](../../principles/react.md)
+- 리뷰: [`skills/react/fe-review/SKILL.md`](../fe-review/SKILL.md)
+- 성능: [`skills/react/fe-perf/SKILL.md`](../fe-perf/SKILL.md)
+- 코퍼스 원본: `sources/react/`, `sources/perf/`, `sources/toss-ff/`

package/assets/dev-guide/fe/skills/react/fe-perf/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: fe-perf-react
+description: React/Next.js 앱의 메모리 누수·CPU 병목·INP/LCP 회귀를 진단. Chrome DevTools Performance/Memory + React Profiler 절차 가이드. 흔한 누수 패턴 4종 + 픽스 코드.
+---
+
+# fe-perf (React)
+
+> **호출 시점**: "느려졌어", "메모리 누는 것 같아", "INP가 나빠졌어", Lighthouse 점수 회귀, OOM 등.
+> **선행 로딩**: `principles/common.md` B + `sources/a11y-dx/chrome-devtools-*.md`.
+
+## 0. 분류 — 어떤 증상인가?
+
+진단 시작 전 사용자에게 1개 질문 (이미 명시했으면 스킵):
+
+1. **메모리** — 시간이 지날수록 RSS/heap 증가, 탭이 GB 단위, OOM
+2. **CPU/렌더** — 인터랙션 굳음, INP 나쁨, 스크롤 끊김, Long Task
+3. **로드 성능** — LCP 나쁨, TTFB 나쁨, 번들 크기
+
+분류에 따라 §1/§2/§3 으로 분기.
+
+---
+
+## 1. 메모리 누수 진단
+
+근거: `sources/a11y-dx/chrome-devtools-memory.md`
+
+### 1.1 측정 절차
+
+1. Chrome DevTools → Memory 패널
+2. **Heap snapshot 3회법** (가장 신뢰):
+   - 초기 페이지 → snapshot 1
+   - 의심 동작 N회 반복 (모달 열고 닫기 등) → snapshot 2
+   - GC 수동 트리거 (휴지통 아이콘) → snapshot 3
+   - snapshot 3에서 snapshot 1 대비 *증가한* Constructor 찾기
+3. Constructor 클릭 → Retainers 트리에서 살아있는 이유 추적
+4. `Detached` prefix 객체 발견 시 → DOM 누수
+
+### 1.2 흔한 누수 패턴 4종 + 픽스
+
+| 패턴 | 증상 | 픽스 |
+|------|------|------|
+| **이벤트 리스너 미해제** | `window.addEventListener` 후 cleanup 없음 | `useEffect(() => { ... ; return () => removeEventListener(...) }, [])` |
+| **타이머 미정리** | `setInterval`/`setTimeout` cleanup 없음 | cleanup에서 `clearInterval/Timeout` |
+| **구독 미해제** | WebSocket/Observable/IntersectionObserver | cleanup에서 `unsubscribe`/`.disconnect()` |
+| **클로저 캡처** | 콜백이 큰 state 캡처 + 외부 보관 | 콜백 안에서 `useRef` 로 최신값 참조, 또는 캡처 최소화 |
+
+### 1.3 React 특화 누수
+
+- **RSC fetch 캐시 무한 누적** — `unstable_cache` key 안에 동적 무한 값 (timestamp 등) 사용 금지
+- **`useEffect` 의존성에 객체/배열 매번 새로 생성** → 무한 리렌더 → 메모리 압박. Compiler 도입 또는 ref 안정화.
+- **Context value 새 객체 매번 생성** → 모든 consumer 리렌더. `useMemo` 또는 Compiler.
+- **Zustand 등 store에 거대한 캐시 무제한 적재** → LRU 또는 max-size 명시
+
+### 1.4 진단 결과 형식
+
+```
+## 메모리 누수 진단
+- 증상: 모달 N회 열고 닫으면 heap +XMB
+- 원인: <Detached HTMLDivElement>, retainer: AppHeader.onResize (이벤트 리스너 미해제)
+- 픽스: src/components/AppHeader.tsx:34
+  return () => window.removeEventListener('resize', onResize)
+- 검증: snapshot 3회법 재실행 → 누적 0 확인
+```
+
+---
+
+## 2. CPU/렌더 병목 (INP 회귀)
+
+근거: `sources/a11y-dx/chrome-devtools-performance.md`, `sources/a11y-dx/react-devtools-profiler.md`, `sources/perf/02-inp.md`
+
+### 2.1 INP 진단 절차
+
+1. **`web-vitals/attribution` 로 INP 하위 구성 요소 식별**
+   ```ts
+   import { onINP } from 'web-vitals/attribution';
+   onINP((m) => console.log(m.attribution));
+   // 결과: { eventEntry, longAnimationFrameEntries, interactionTarget, inputDelay, processingDuration, presentationDelay }
+   ```
+   - **Input Delay** 큼 → 직전 Long Task 찾기 (Performance 탭)
+   - **Processing Duration** 큼 → 이벤트 핸들러 무거움
+   - **Presentation Delay** 큼 → 렌더/스타일 무거움
+
+2. **Chrome DevTools → Performance → 인터랙션 녹화**
+   - Long Task 색상 (빨강) 식별
+   - Flame Chart 가장 큰 박스 → 함수 이름
+   - **Forced Layout/Style Recalc** 노란 박스 → `offsetTop` 등 read-after-write 패턴
+
+3. **React Profiler → Why did this render?**
+   - 불필요한 리렌더 식별. 부모 리렌더 vs prop 변경 vs state 변경.
+
+### 2.2 INP 픽스 패턴
+
+| 원인 | 픽스 |
+|------|------|
+| 핸들러 안 동기 무거운 계산 | `startTransition(() => setState(heavyCalc()))` 또는 `useDeferredValue` |
+| 200ms+ Long Task | `scheduler.yield()` (지원 시) 또는 작업 chunk 분할 |
+| 매 입력마다 외부 통신 | debounce (입력) / throttle (스크롤·리사이즈) |
+| Context 거대 value 변경 | Context 분리 (Read/Write 분리) |
+| useEffect 안 setState 체인 | 한 핸들러에서 모두 처리 |
+| 큰 리스트 전체 렌더 | 가상화 (`react-window`, `@tanstack/react-virtual`) |
+
+### 2.3 React Compiler 환경
+
+- 수동 `useMemo`/`useCallback` 추가는 *오히려 컴파일러 최적화 방해 가능*
+- Compiler가 메모이즈 못 하는 코드 → ESLint plugin 경고 따라 코드 수정 (불순 함수 등)
+
+### 2.4 진단 결과 형식
+
+```
+## INP 진단
+- 측정: INP p75 = 480ms (Poor)
+- 하위: inputDelay=120ms, processingDuration=300ms, presentationDelay=60ms
+- 원인: src/pages/list/index.tsx:88 onSearch 핸들러 안 동기 필터링 (n=10k)
+- 픽스: startTransition + useDeferredValue
+  ```ts
+  const deferredQ = useDeferredValue(query);
+  const filtered = useMemo(() => items.filter(matches(deferredQ)), [items, deferredQ]);
+  ```
+- 검증: INP p75 재측정 → ≤200ms 확인
+```
+
+---
+
+## 3. 로드 성능 (LCP/TTFB/번들)
+
+근거: `sources/perf/03-lcp-cls.md`, `sources/perf/10-optimize-lcp.md`
+
+### 3.1 LCP 진단
+
+1. Lighthouse → LCP element 식별 (스크린샷 + 셀렉터)
+2. PageSpeed Insights → 실사용자 (Field) 데이터로 p75 확인
+3. Performance 패널 → 4 하위 구성 요소 시간 분해:
+   - **TTFB** (서버 응답)
+   - **Resource Load Delay** (LCP 자원 발견)
+   - **Resource Load Time** (다운로드)
+   - **Render Delay** (렌더)
+
+### 3.2 LCP 픽스 매트릭스
+
+| 큰 구성 요소 | 픽스 |
+|--------------|------|
+| TTFB | RSC + 캐시 (revalidate, ISR), Edge 배포, DB 인덱스 |
+| Resource Load Delay | `<link rel="preload">`, `next/image priority`, `fetchpriority="high"` |
+| Resource Load Time | next/image (WebP/AVIF 자동), CDN, sizes 명시 |
+| Render Delay | 클라이언트 hydration 무거움 → RSC 비중 증가, dynamic import |
+
+### 3.3 번들 분석
+
+- `next build` 출력의 First Load JS 확인
+- `@next/bundle-analyzer` 로 시각화 → 큰 의존성 → dynamic import 또는 RSC 분리
+- `'use client'` 파일 안 markdown/syntax-highlight 등 큰 라이브러리 → Server 분리
+
+### 3.4 결과 형식
+
+```
+## LCP 진단
+- 측정: LCP p75 = 3.8s (Needs Improvement)
+- LCP element: src/pages/index.tsx <img src="/hero.jpg">
+- 분해: TTFB 1.2s + LoadDelay 0.8s + LoadTime 1.1s + RenderDelay 0.7s
+- 픽스 (우선순위):
+  1. next/image + priority (Load Delay 제거): src/pages/index.tsx:24
+  2. revalidate=300 → TTFB 1.2s → 200ms (캐시 hit)
+  3. RSC로 메인 페이지 변환 (Render Delay 0.7s → 0.1s)
+- 검증: 배포 후 24h Field Data 재확인
+```
+
+---
+
+## 4. 출력 (사용자에게 무조건 포함할 항목)
+
+- **측정 수치 (before)** — "느낌"이 아니라 숫자
+- **원인 (파일:라인 + retainer/콜스택)**
+- **픽스 코드** — 카피-페이스트 가능
+- **검증 방법** — 픽스 후 무엇을 측정해서 어떻게 비교할지
+
+## 5. 관련 문서
+
+- [`principles/common.md`](../../principles/common.md), [`principles/react.md`](../../principles/react.md)
+- 코퍼스: `sources/a11y-dx/chrome-devtools-{performance,memory}.md`, `sources/a11y-dx/react-devtools-profiler.md`, `sources/perf/`