@makitt.io/mds-mcp-server 0.1.0

package/dist/data/playbook/ai-fill.md

@@ -0,0 +1,175 @@
+# MDS Playbook — AI Fill (ai-drawer 통합)
+
+AI 가 form 자동 채우기 (autofill) 의 약속.
+
+> **단일 통로 강제**: `useSkillAutofill` + `FormFillApprovalBanner` + `skill-registry`.
+> 도메인별 hook / Banner / Prompt 작성 **금지**.
+
+---
+
+## 1. AI Fill 의 의도
+
+| 시나리오 | AI 의 역할 |
+|---|---|
+| 사용자가 ai-drawer 에 자연어 입력 ("새 상품 만들어줘, 캐시미어 니트") | AI 가 schema 따라 form value 생성 → eventBus 발행 |
+| 페이지에 이미 form 열림 (예: `/products/new`) | `useSkillAutofill(agentType)` 수신 → banner 표시 → 사용자 approve/reject |
+| 페이지 외부 (다른 page) | `useSkillAutofillNavigation` 가 prompt → 사용자 navigation → sessionStorage 통해 데이터 전달 |
+
+---
+
+## 2. 단일 통로 — 4 layer 강제
+
+| Layer | 컴포넌트 / 위치 | 책임 |
+|---|---|---|
+| **1. ai-drawer 패키지** | `packages/ai-drawer/` | AI 결과를 eventBus.emit 으로 발행 (도메인 무관) |
+| **2. skill-registry** | `apps/web/src/shared/lib/skill-registry/` | agentType → { eventName, storageKey, schema, mutator } single source 등록 |
+| **3. useSkillAutofill** | `apps/web/src/shared/lib/skill-registry/useSkillAutofill.ts` | generic hook — 모든 form page 가 1 줄 호출 |
+| **4. FormFillApprovalBanner** | `apps/web/src/shared/ui/FormFillApprovalBanner/` | 사용자에게 approve/reject UI |
+
+→ **도메인별 hook / Banner / Prompt 작성 금지**. ESLint rule 자동 강제 (Step 1).
+
+---
+
+## 3. 새 form 의 AI fill 통합 — 30 줄 등록
+
+### Step 1 — skill 등록
+
+```ts
+// apps/web/src/shared/lib/skill-registry/skills.ts
+import { ProductAutofillSchema } from '@/shared/lib/validations';
+
+registerSkill({
+  agentType: 'product',
+  storageKey: 'ai:product:pendingAutofill',
+  eventName: AI_EVENTS.PRODUCT_AUTOFILL,
+  schema: ProductAutofillSchema,
+  mutator: (data, store) => {
+    store.setName(data.productName);
+    store.setDescription(data.description ?? '');
+    store.setTags(data.features ?? []);
+    if (data.price) store.setFeaturedPrice(data.price);
+  },
+});
+```
+
+### Step 2 — form page 에서 hook 사용
+
+```tsx
+import { useSkillAutofill } from '@/shared/lib/skill-registry/useSkillAutofill';
+import { FormFillApprovalBanner } from '@/shared/ui/FormFillApprovalBanner';
+
+function ProductFormPage() {
+  const { hasPendingFill, pendingData, applyFill, rejectFill } = useSkillAutofill<ProductAutofillData>('product');
+
+  return (
+    <>
+      {hasPendingFill && (
+        <FormFillApprovalBanner
+          data={pendingData}
+          onApply={applyFill}
+          onReject={rejectFill}
+        />
+      )}
+      <ProductForm />
+    </>
+  );
+}
+```
+
+---
+
+## 4. 결정 표 (lookup)
+
+| 케이스 | 답 |
+|---|---|
+| "새 도메인 AI fill 통합" | `registerSkill({ agentType, eventName, storageKey, schema, mutator })` 30줄 |
+| "form 안에서 AI 결과 수신" | `useSkillAutofill(agentType)` |
+| "AI 가 채운 후 사용자 확인" | `<FormFillApprovalBanner data={pendingData} onApply onReject>` |
+| "다른 page 에서 AI 가 채움 → form page 이동 prompt" | `useSkillAutofillNavigation` (TBD generic 화 — 현재 도메인별 useProductAutofillNavigation 6 hook) |
+| "사용자가 reject 후 데이터 보존" | sessionStorage 그대로, 사용자 다른 page 가서 다시 trigger |
+| "AI 가 schema 안 맞는 데이터 발행" | `useSkillAutofill` 의 schema validation (Zod) 자동 — invalid 시 toast.error |
+
+---
+
+## 5. 안티 패턴
+
+- ❌ **도메인별 fill hook 작성** (`useProductFormFill` 등) — `useSkillAutofill` 만 사용. ESLint rule 자동 강제
+- ❌ **도메인별 FormFillBanner** (`ProductFormFillBanner` 등) — shared `FormFillApprovalBanner` 만
+- ❌ **eventBus name hardcode** — skill registry 가 자동 발행
+- ❌ **schema 검증 없는 mutator** — skill 등록 시 schema 필수 + Zod 자동 validation
+- ❌ **AI 결과 직접 store 변경** — banner 의 approve 거치는 게 표준 (사용자 의식 보장)
+- ❌ **다른 도메인 의 skill 직접 trigger** — agentType 으로 격리
+- ❌ **mutator 안 navigate** — mutator = 순수 함수 (data → store mutation). navigation 은 별도
+
+---
+
+## 6. AI 친화 — Catalog + MCP
+
+| Layer | 효과 |
+|---|---|
+| **skill-registry 자체가 catalog** | AI 가 어떤 form 에 어떤 schema fill 가능 자동 lookup |
+| **MCP server (Step 6 예정)** | AI 가 `mds.skills.list()` 또는 `mds.skills.fillable(routePath)` query 자동 |
+| **schema export** | Zod schema → JSON Schema 변환 → AI 가 정확한 데이터 생성 |
+
+---
+
+## 7. 마이그레이션 — 6 도메인 의 hand-rolled → generic
+
+현재 apps/web 에 6 도메인 hand-rolled (Step 8 마이그레이션 대상):
+- `useProductFormFill` (199줄)
+- `useSkuFormFill` (182줄)
+- `useSellableUnitFormFill` (162줄)
+- `useCollectionFormFill`
+- `useFilterFormFill`
+- `useBrandProfileFormFill`
+
+각 ~30줄 의 `registerSkill` 호출로 마이그레이션. + 도메인별 Banner / Prompt → shared.
+
+총 마이그레이션 ~1.5h Claude time (Step 8 web 마이그레이션 의 일부).
+
+---
+
+## 8. Cross-cutting
+
+| Axis | 적용 |
+|---|---|
+| **Responsive** | FormFillApprovalBanner 의 mobile = vertical layout (action 버튼 stacked) |
+| **A11y** | banner 의 `role="status"` + 사용자 approve/reject button focusable |
+| **i18n** | "AI 가 form 을 채웠어요" + approve/reject 라벨 모두 `t()` |
+| **AI Integration** | 본 layer 자체. 모든 form 의 AI fill 통일 |
+| **Telemetry** | approve/reject ratio 추적 (AI 정확도 측정) |
+| **Portability** | 외부 admin 프로젝트도 skill-registry import 만으로 동일 (Step 10) |
+
+---
+
+## 9. TBD
+
+1. **AutofillNavigationPrompt 의 generic 화** — 현재 도메인별 prompt 5 component. generic + agentType prop 로 통합
+2. **Approve/Reject 후 navigation** — apply 후 자동 form submit vs 사용자 confirm
+3. **Schema → JSON Schema** — AI 가 catalog query 시 사용. converter 추가
+4. **Multi-step skill** — 단순 form fill 외 multi-page wizard (TBD)
+5. **AI 가 자체 검증** — Zod validation 외 의미 검증 (예: SKU 가 unique 한지)
+6. **Skill 별 권한** (admin vs merchant) — fill 권한 분리
+
+---
+
+## Related Playbooks
+
+- [form.md](./form.md) — Form 의 AI fill 사용 시점 (Step 4.1)
+- [feedback.md](./feedback.md) — FormFillApprovalBanner 는 banner-style (Step 4.2)
+
+---
+
+## Future — Step 6 MCP server
+
+AI 가 mds 의 사용 약속 + props spec + 안티패턴 자동 query 가능 — `mds-mcp-server` (Step 6).
+
+```ts
+// AI 가 query 가능
+const fillable = await mds.skills.list();  // ['product', 'sku', 'sellable-unit', ...]
+const schema = await mds.skills.get('product').schema;  // Zod schema → JSON Schema
+const pattern = await mds.playbook.search('form anti-patterns');
+const violation = await mds.lint.check(code);  // ESLint + audit 자동
+```
+
+→ AI fabrication 0 의 최종 layer. skill-registry + Playbook + Catalog 자동 lookup.

package/dist/data/playbook/anti-patterns.md

@@ -0,0 +1,188 @@
+# MDS Playbook — Anti-Patterns 종합
+
+9 영역의 모든 안티 패턴 모음 — **이거 보고 commit 막힘 / 코드리뷰 reject** 기준.
+
+> 각 항목 = `금지 패턴` + `이유` + `대안`. ESLint rule 으로 자동 강제하는 항목 표시.
+
+---
+
+## 1. Component 작성 (Step 1 ESLint 자동 강제 ✓)
+
+| 안티 패턴 | 이유 | 대안 | ESLint |
+|---|---|---|---|
+| `export const X = (props) => ...` (forwardRef 없음) | ref 전달 불가 — 일관성 깨짐 | `forwardRef<...>(function X(...))` | `mds/forward-ref-required` ✓ |
+| Props interface 에 `BaseComponentProps` 미extend | className/style/data-testid 누락 | `extends BaseComponentProps` | `mds/base-component-props-extend` ✓ |
+| Root element 에 `data-mds-component` 미명시 | Catalog lookup + Playwright + debug 불가 | `<div data-mds-component="X">` | `mds/data-mds-component-required` ✓ |
+| `cn(className, styles.x)` 순서 (className 앞) | consumer override 불가 | `cn(styles.x, className)` (마지막) | `mds/classname-merge-last` ✓ |
+| Root element 에 `{...rest}` 누락 | HTML attribute passthrough X (aria/data/event) | `<div {...rest}>` | `mds/spread-rest-props` ✓ |
+| 컴포넌트 default export | named import 일관성 깨짐 | `export const X` | `mds/no-default-export-components` ✓ |
+| `import styled from 'styled-components'` | runtime CSS-in-JS — bundle 부담 + token 시스템 우회 | SCSS module 만 | `mds/no-runtime-css-in-js` ✓ |
+| 같은 layer cross-import (primitives/A → primitives/B) | layer 격리 깨짐 | 공통 코드는 foundations/hooks/utils | `mds/no-cross-layer-import` ✓ |
+| file/folder 명명 (PascalCase / useCamelCase / *.types / *.store / *.module.scss) | 명명 표준 깨짐 | CLAUDE.md #6 | `mds/file-naming-conventions` ✓ |
+| inline hex / px / rem / em literal | token 시스템 우회 | `var(--token)` | `mds/no-hardcoded-visual-values` ✓ |
+
+→ **10 rule 자동 강제**. commit 시 차단.
+
+---
+
+## 2. Form (form.md)
+
+| 안티 패턴 | 이유 | 대안 |
+|---|---|---|
+| `useState<string>('')` 으로 form value 관리 | 검증 / 의도 / RHF integration 없음 | RHF `useForm()` + Zod schema |
+| raw `<input>` / `<textarea>` 직접 | Field compound 의 a11y wire 누락 | `<Field>` + `<TextField>` |
+| Field compound 외부 input | label / error / hint 의 aria 안 wire | `<Field.Root>` 안 input |
+| Modal 안 Modal 안 Form | 3단 mental stack | drawer 분리 또는 페이지 이동 |
+| inline error + toast.error 동시 | 중복 — 사용자 혼란 | 한 곳만 |
+| 가로 정렬 input 두 개가 의미 무관 | mental scan 깨짐 | vertical |
+| Notification 으로 "저장됨" | 영속 의도 아님 | Toast |
+| Toast 로 "라이선스 만료" | 사용자 놓침 | Notification (영속) |
+| 도메인별 fill hook 작성 (useXxxFormFill) | 6 도메인 ~900줄 hand-rolled | `useSkillAutofill(agentType)` 30줄 |
+| Inline 편집 의 blur 자동 저장 | 실수 위험 | Enter / 체크 명시 저장 |
+
+---
+
+## 3. Feedback (feedback.md)
+
+| 안티 패턴 | 이유 | 대안 |
+|---|---|---|
+| Toast 로 "정말 삭제?" | dismissible — 응답 못 받음 | `Modal.confirm` (Dialog) |
+| Notification 으로 "저장됨" | 영속 의도 아님 | Toast |
+| Banner + Toast 동일 메시지 동시 | 중복 | 한 곳 |
+| Toast 5+ 동시 stacking | 사용자 의식 한계 | stacking 제한 |
+| Dialog 안 multiple input | Dialog 의 의도 깨짐 | `Modal.prompt` 또는 form Modal |
+| Banner 2줄+ 긴 텍스트 | 시각 부담 | collapse 또는 Modal |
+| 영속 Notification 의 dismiss 없음 | a11y 위반 | 명시 닫기 |
+
+---
+
+## 4. Overlay (overlay.md)
+
+| 안티 패턴 | 이유 | 대안 |
+|---|---|---|
+| Modal 안 Modal | 3단 stack | drawer 분리 |
+| Drawer 안 Drawer | 동일 | nested drawer 외 금지 |
+| Modal ↔ Drawer 혼합 (Modal 안 Drawer 등) | focus / layer 충돌 | 한 종류 만 |
+| Popover 안 Popover | auto-position 충돌 | nested popover 금지 |
+| Dialog 안 form (input multiple) | Dialog 의도 깨짐 | `Modal.prompt` |
+| Popover 안 큰 form | Popover 의도 (작은 inline) 아님 | Modal |
+| isDirty close 시 force confirm 없음 | 사용자 변경 사항 손실 | `<Modal isDirty={isDirty}>` |
+| Drawer 의 width 변경 (사용자 resize) | layout 깨짐 | caller fix |
+| Sheet 의 height 가 viewport 90%+ | full-screen modal 이 차라리 명확 | Sheet 의 의도 모호 |
+
+---
+
+## 5. DataGrid + Table (data-grid.md)
+
+| 안티 패턴 | 이유 | 대안 |
+|---|---|---|
+| DataGrid 안 form (모든 row 의 input) | 큰 form 은 별도 페이지 | page-form 분리 |
+| Table 으로 DataGrid 흉내 (filter/pagination caller 구현) | 중복 + 일관성 X | DataGrid |
+| column 50+ | 사용자 scan 불가 | hidden + caller 선택 |
+| loading 시 ErrorState / EmptyState 표시 | async-states.md §2 위반 | loading 만 |
+| row 클릭 + checkbox 동시 작동 | 의도 충돌 | selection 모드 시 row click 막힘 |
+| pagination size 50+ | render 부담 + a11y | 최대 20-30 |
+| selection 이 page 이동 후 사라짐 | cross-page 의도 깨짐 | DataGrid 의 selectedIds Set 유지 |
+| column header 가 너무 길거나 wrap | fixed height 깨짐 | ellipsis |
+
+---
+
+## 6. Page Layout (page-layout.md)
+
+| 안티 패턴 | 이유 | 대안 |
+|---|---|---|
+| 페이지마다 다른 layout | 사용자 mental model 깨짐 | AppShell + PageHeader 표준 |
+| DataGrid 페이지 에 max-width | content 답답 (1920px 모니터) | full-bleed |
+| form 페이지에 max-width 없음 | 가로 input 한 줄 어색 | 640~800px |
+| PageHeader 의 actions 가 row-level | DataGrid column action 의 의도 | PageHeader 는 page-level |
+| Sidebar 안 sub-Item 3 단계+ | mental load | 2 단계 max |
+| section gap / padding hardcoded | token 시스템 우회 | `var(--section-gap)` / `var(--space-*)` |
+| mobile 에서 Sidebar 그대로 left sticky | UX 깨짐 | drawer 변환 |
+
+---
+
+## 7. Array Input (array-input.md)
+
+| 안티 패턴 | 이유 | 대안 |
+|---|---|---|
+| 무한 깊은 nested (drawer 안 drawer 안 drawer) | mental stack 한계 | 2 단 max |
+| inline edit + drawer 편집 동시 | 의도 충돌 | 한쪽만 |
+| add 버튼이 row 사이 | mental scan 깨짐 | row 끝 |
+| remove 의 confirm 없음 (이미 저장 entity) | 실수 위험 | `Modal.confirm` |
+| 0 row 의 empty state 없음 | placeholder 부족 | `<EmptyState size="sm">` |
+| dnd 만 (keyboard reorder 없음) | a11y 위반 | dnd-kit keyboard sensor |
+| submit 시 빈 row valid | 데이터 quality 깨짐 | Zod `.min(1)` |
+
+---
+
+## 8. Async States (async-states.md)
+
+| 안티 패턴 | 이유 | 대안 |
+|---|---|---|
+| Spinner 우선 사용 | 의도 모호 / placeholder X | Skeleton |
+| Loading 의 깜빡임 (< 200ms) | UX 불안정 | min display time 200ms |
+| Action button loading + 별도 progress bar | 중복 | button loading 만 |
+| Background 의 modal loading | 사용자 인터럽트 | silent 또는 corner toast |
+| Empty 의 "다시 시도" 만 | empty != error | EmptyState 의 의도 따라 |
+| Error 시 toast 만 (page-level) | content 자리 missing | ErrorState content area |
+| Skeleton 의 layout mismatch | 깜빡임 효과 | 실 content shape |
+
+---
+
+## 9. AI Fill (ai-fill.md)
+
+| 안티 패턴 | 이유 | 대안 |
+|---|---|---|
+| 도메인별 fill hook (`useXxxFormFill`) | 6 도메인 ~900줄 hand-rolled | `useSkillAutofill(agentType)` |
+| 도메인별 FormFillBanner | 6 component 중복 | shared `FormFillApprovalBanner` |
+| eventBus name hardcode | 도메인별 name typo 위험 | skill-registry 자동 발행 |
+| schema 검증 없는 mutator | invalid 데이터 store 진입 | Zod schema 필수 |
+| AI 결과 직접 store 변경 (banner skip) | 사용자 의식 없음 | banner approve 거치기 |
+| 다른 도메인 skill trigger | agent 격리 깨짐 | agentType 격리 |
+| mutator 안 navigate | 순수성 깨짐 | navigation 별도 |
+
+---
+
+## 10. Cross-cutting 안티 패턴
+
+| 안티 패턴 | 이유 | 대안 |
+|---|---|---|
+| **i18n raw string** ("저장" 직접) | locale 변경 시 깨짐 | `t('common.save')` |
+| **a11y aria-label / role 없음** | screen reader 누락 | Radix 기반 + 명시 aria |
+| **token 외 hardcoded color / spacing** | theme 안 자동 변환 | `var(--token)` 만 |
+| **mobile breakpoint hardcoded** (`@media (max-width: 768px)`) | breakpoint 변경 시 mismatch | `var(--breakpoint-md)` (CSS @media 안 직접 사용 못 함 — SCSS @media + Tailwind) |
+| **새 컴포넌트 추가 시 stories / test 누락** | audit 차단 + 사용 예 없음 | `pnpm mds:new` (Step 9 generator) |
+| **CI 통과 안 한 채 commit** | drift 가능 | pre-commit + CI 강제 (작동 중) |
+
+---
+
+## 11. 강제 layer 종합
+
+| Layer | 자동 강제 |
+|---|---|
+| **ESLint 10 rule (Step 1)** | §1 의 10 항목 + cross-layer + hardcoded |
+| **audit-components (Step 2)** | file-structure / forwardRef / data-mds / use-client / BaseComponentProps / cn |
+| **baseline lock (max-warnings 551)** | 새 ESLint warning 1개도 차단 |
+| **verify:tokens** | hardcoded color / spacing |
+| **verify:stories** | 정의 안 된 CSS var() |
+| **a11y axe-playwright (Step 2.C)** | WCAG 2.1 AA 위반 |
+| **visual regression** | snapshot diff 강제 confirm |
+| **prefers-reduced-motion** | 운동 민감증 자동 |
+| **style-dictionary** | theme 별 자동 token 적용 |
+| **pre-commit + CI** | drift 차단 |
+
+→ **새 컴포넌트 / 변경 시 위 10 layer 모두 자동 통과 필수**. 우회 시도해도 차단.
+
+---
+
+## Related Playbooks
+
+각 영역의 detail:
+- [form.md](./form.md) (Step 4.1)
+- [feedback.md](./feedback.md) (Step 4.2)
+- [data-grid.md](./data-grid.md) (Step 4.3)
+- [overlay.md](./overlay.md) (Step 4.4)
+- [page-layout.md](./page-layout.md) (Step 4.5)
+- [array-input.md](./array-input.md) (Step 4.6)
+- [async-states.md](./async-states.md) (Step 4.7)
+- [ai-fill.md](./ai-fill.md) (Step 4.8)

package/dist/data/playbook/array-input.md

@@ -0,0 +1,249 @@
+# MDS Playbook — Array Input + Nested Entity
+
+배열형 input (반복 필드) + 메인 form 안 sub-entity 편집 의 약속.
+
+> RHF `useFieldArray` 표준 + drawer 편집 패턴.
+
+---
+
+## 1. 4 패턴 분리
+
+| 패턴 | 사용 시점 | 컴포넌트 |
+|---|---|---|
+| **짧은 동질 배열** (태그 / 카테고리) | item = 단순 string, ≤ 20 개 | `<ChipToggle>` (compounds) |
+| **가변 row sub-form** | item 이 small form (예: variant 가격) | `useFieldArray` + `<Stack>` row + add/remove |
+| **nested entity 다수** (정책 / 결제 옵션) | item 이 큰 form, 별 entity | `useFieldArray` row 요약 + click → **Drawer 편집** |
+| **reorder 가능** | drag handle 으로 순서 변경 | `<Tree>` (compounds) 또는 `useFieldArray` + dnd-kit |
+
+---
+
+## 2. 사용 시점 결정표
+
+| 케이스 | 답 |
+|---|---|
+| "상품 태그 (text chip 다수)" | `<ChipToggle>` (다중 토글) |
+| "주문 항목 (상품 + 수량 + 가격 3 필드 row)" | `useFieldArray` + Stack row + IconButton remove |
+| "변형 (variant: 색 / size / 가격 / 재고 4 필드, 각 row 가 큼)" | `useFieldArray` + 행 요약 + click → Drawer 의 sub-form |
+| "정책 (각 정책이 큰 entity)" | nested drawer-form (overlay.md §7) |
+| "image 다수 + reorder" | `<Tree>` (compounds) 또는 dnd-kit + useFieldArray |
+| "FAQ list (질문/답 row, 다수)" | useFieldArray + Stack + Drawer 의 큰 답변 input |
+
+---
+
+## 3. 짧은 동질 배열 — ChipToggle
+
+```tsx
+<Field.Root>
+  <Field.Label>태그</Field.Label>
+  <Controller
+    name="tags"
+    control={control}
+    render={({ field }) => (
+      <ChipToggle.Group value={field.value} onValueChange={field.onChange} multiple>
+        <ChipToggle.Item value="new">신상</ChipToggle.Item>
+        <ChipToggle.Item value="sale">세일</ChipToggle.Item>
+        <ChipToggle.Item value="featured">추천</ChipToggle.Item>
+      </ChipToggle.Group>
+    )}
+  />
+</Field.Root>
+```
+
+- 다중 선택 = `multiple` prop
+- 단일 선택 = 그 prop 없음 (default)
+- caller 가 새 chip 추가 불가 (predefined list 만) — 새 추가 = `Combobox` 또는 별도 input
+
+---
+
+## 4. 가변 row sub-form — useFieldArray + Stack
+
+```tsx
+import { useFieldArray } from 'react-hook-form';
+
+function VariantPriceForm() {
+  const { fields, append, remove } = useFieldArray({
+    control,
+    name: 'variants',
+  });
+  return (
+    <Field.Root>
+      <Field.Label>변형 가격</Field.Label>
+      <Stack gap="2">
+        {fields.map((field, idx) => (
+          <Stack key={field.id} direction="row" gap="2" align="center">
+            <Field.Root>
+              <Field.Label visuallyHidden>이름</Field.Label>
+              <TextField {...register(`variants.${idx}.name`)} placeholder="이름" />
+            </Field.Root>
+            <Field.Root>
+              <Field.Label visuallyHidden>가격</Field.Label>
+              <NumberInput {...register(`variants.${idx}.price`)} step={100} suffix="원" />
+            </Field.Root>
+            <IconButton
+              aria-label={`${field.name} 삭제`}
+              onClick={() => remove(idx)}
+              variant="ghost"
+            >
+              <TrashIcon />
+            </IconButton>
+          </Stack>
+        ))}
+      </Stack>
+      <Button
+        variant="ghost"
+        leadingIcon={<PlusIcon />}
+        onClick={() => append({ name: '', price: 0 })}
+      >
+        변형 추가
+      </Button>
+    </Field.Root>
+  );
+}
+```
+
+### Add / Remove UI 표준
+
+| 위치 | 컴포넌트 | 라벨 |
+|---|---|---|
+| Add 버튼 | row 마지막 아래 (또는 위) | `Button variant="ghost" leadingIcon=<PlusIcon>{...}추가` |
+| Remove 버튼 | row 끝 우측 | `IconButton variant="ghost"` + aria-label |
+| 위험 (이미 저장된 entity 삭제) | `Modal.confirm` 확인 후 remove | — |
+
+---
+
+## 5. nested entity 다수 — drawer 편집
+
+큰 sub-entity (variant / 정책 / 결제 옵션) — 행 요약 + click → Drawer 의 full form.
+
+```tsx
+function PolicyList() {
+  const { fields, append, remove, update } = useFieldArray({ control, name: 'policies' });
+  const [editIdx, setEditIdx] = useState<number | null>(null);
+
+  return (
+    <>
+      <Stack gap="2">
+        {fields.map((field, idx) => (
+          <Card.Root
+            key={field.id}
+            onClick={() => setEditIdx(idx)}
+            data-mds-component="PolicyRow"
+          >
+            <Card.Body>
+              <PersonCell name={field.name} sub={field.description} />
+            </Card.Body>
+          </Card.Root>
+        ))}
+      </Stack>
+      <Button variant="ghost" leadingIcon={<PlusIcon />} onClick={() => setEditIdx(fields.length)}>
+        정책 추가
+      </Button>
+      <Drawer.Root open={editIdx !== null} onOpenChange={(o) => !o && setEditIdx(null)}>
+        <Drawer.Content side="right">
+          <PolicyForm
+            initialValue={editIdx !== null && editIdx < fields.length ? fields[editIdx] : undefined}
+            onSubmit={(data) => {
+              if (editIdx !== null && editIdx < fields.length) update(editIdx, data);
+              else append(data);
+              setEditIdx(null);
+            }}
+            onDelete={editIdx !== null && editIdx < fields.length
+              ? () => { remove(editIdx); setEditIdx(null); }
+              : undefined}
+          />
+        </Drawer.Content>
+      </Drawer.Root>
+    </>
+  );
+}
+```
+
+- 메인 form 의 isDirty 유지 — Drawer 닫으면 변경 사항 commit
+- Drawer 안 sub-form 의 isDirty close 시 confirm (overlay.md §11 TBD)
+
+---
+
+## 6. Reorder
+
+mds 의 자체 dnd 없음. 옵션:
+- **Tree (compounds)** — Radix 기반 nested reorder
+- **useFieldArray + dnd-kit** — drag handle 의 manual integration
+
+```tsx
+import { DndContext, closestCenter } from '@dnd-kit/core';
+import { SortableContext, useSortable, verticalListSortingStrategy } from '@dnd-kit/sortable';
+
+function SortableArray() {
+  const { fields, move } = useFieldArray({ control, name: 'items' });
+  return (
+    <DndContext
+      collisionDetection={closestCenter}
+      onDragEnd={(e) => {
+        const oldIndex = fields.findIndex((f) => f.id === e.active.id);
+        const newIndex = fields.findIndex((f) => f.id === e.over?.id);
+        if (oldIndex !== -1 && newIndex !== -1) move(oldIndex, newIndex);
+      }}
+    >
+      <SortableContext items={fields.map((f) => f.id)} strategy={verticalListSortingStrategy}>
+        {fields.map((field, idx) => (
+          <SortableRow key={field.id} id={field.id} {...field} />
+        ))}
+      </SortableContext>
+    </DndContext>
+  );
+}
+```
+
+---
+
+## 7. Mobile 변형
+
+| Pattern | Mobile |
+|---|---|
+| ChipToggle | wrap full-width, scroll horizontal if many |
+| useFieldArray + Stack (row) | `direction="column"` (vertical) + add / remove 그대로 |
+| nested entity (Drawer) | Drawer → bottom Sheet (overlay.md §8) |
+| Reorder (dnd-kit) | touch-friendly drag handle |
+
+---
+
+## 8. 안티 패턴
+
+- ❌ **무한 깊은 nested** (drawer 안 drawer 안 drawer) — 2 단 max (메인 form + sub-entity drawer)
+- ❌ **inline edit + drawer 편집 동시** — 한쪽만
+- ❌ **add 버튼이 row 사이** — row 끝에만 (mental scan 깨짐)
+- ❌ **remove 의 confirm 없음** (이미 저장된 entity) — `Modal.confirm`
+- ❌ **0 row 의 empty state 없음** — `<EmptyState size="sm">` 또는 placeholder
+- ❌ **row 의 a11y 없는 reorder** (drag only) — keyboard 도 가능 (dnd-kit 자체 keyboard sensor)
+- ❌ **submit 시 useFieldArray 의 빈 row 도 valid** — Zod schema 의 .min(1) 검증
+
+---
+
+## 9. Cross-cutting
+
+| Axis | 적용 |
+|---|---|
+| **Responsive** | row → column (mobile) |
+| **A11y** | each row 의 aria-label / remove button aria-label / dnd-kit keyboard support |
+| **i18n** | "추가" / "삭제" / "변형" 등 모두 `t()` |
+| **Catalog** | useFieldArray 의 standard pattern 자동 catalog |
+| **Validation** | Zod `array().min(N).max(N)` |
+
+---
+
+## 10. TBD
+
+1. **dnd-kit mds 통합** — `<SortableArray>` 같은 mds wrapper 컴포넌트 추가
+2. **drawer 안 isDirty confirm** — 메인 form 의 isDirty 와 drawer 의 isDirty 의 통합
+3. **add 위치** — row 끝 vs row 사이 (행간 + 버튼) 둘 다 허용 vs 표준화
+4. **empty state 표준** — useFieldArray 의 0 row 시 표시 패턴
+5. **Bulk add** — CSV / paste 로 다 row 한 번에 (변형 가격 list 같은)
+
+---
+
+## Related Playbooks
+
+- [form.md](./form.md) — useFieldArray 의 form 안 통합 (Step 4.1)
+- [overlay.md](./overlay.md) — nested drawer 합성 규칙 (Step 4.4)
+- [async-states.md](./async-states.md) — 0 row 의 empty state (Step 4.7)
+- [data-grid.md](./data-grid.md) — DataGrid 의 row 자체가 다른 entity 의 array (Step 4.3)