HMDesign/AGENTS.md

# HMDesign AI 화면 구현 — 필수 규칙

이 파일을 먼저 읽고 필요한 항목만 탐색한다. 전체 문서·전체 소스·전체 Storybook을 반복해서 읽지 않는다.

1. 범위 `STORYBOOK_ONLY | PRODUCTION_UI | BOTH`와 Runtime을 확인한다. 신규 AI 업무 화면은 실제 HM React 컴포넌트를 사용한다. 명시적 다른 Runtime adapter는 [상세 계약](docs/guidelines/runtime-portability.md)을 따른다.
2. [기존 Component / Pattern 인덱스](docs/guidelines/component-pattern-reference.md)에서 후보를 찾는다. Import는 `@hm-design/ui` 공개 API가 기본이다. 선택한 문서·대표 All Story·필요한 Props만 확인한다. verification Story는 운영 기준이 아니다.
3. 기존 Component → Variant/Prop → Composition 순으로 재사용한다. 기본 HTML·임의 CSS로 HM 컴포넌트를 모방하거나 `data-slot`만 붙여 재사용했다고 보고하지 않는다. Import만으로 재사용을 인정하지 않는다. 실제 렌더링에 사용해야 한다.
4. 기존 Theme/Semantic Token을 사용한다. React CSS entry는 앱 `index.css → hm-theme.css` 및 필요 시 공개 status CSS를 연결한다. [Runtime Theme](docs/guidelines/runtime-theme.md), [Tailwind/Asset 계약](docs/guidelines/runtime-portability.md)은 관련 변경 때만 읽는다.
5. 페이지 Navigation은 GNB/LNB/DASHBOARD 중 하나다. 공식 LNB ONLY는 허용한다. 신규 GNB ONLY·DASHBOARD ONLY의 Sidebar는 금지한다. GNB는 GNBMobileMenu도 구성한다. Dashboard는 전용 48px Header와 최소 폭 960px·내부 스크롤을 유지한다. 미지정 시 [선택 근거](docs/guidelines/navigation-single-mode.md#선택-근거)를 기록한다.
6. Storybook은 참조 전용이다. 신규 업무 화면을 Story로 등록하거나 대표 Story를 교체하지 않는다. 독립 미리보기 HTML은 실제 React bootstrap을 실행해야 한다. 별도 HTML 모방 화면·이미지를 실제 React 결과로 제출하지 않는다.
7. 완료 후 Guard를 1회 실행한다: `node scripts/ai-generation-guard.mjs --target <앱> --scope FULL_SCREEN|PARTIAL`. Navigation 재사용 시 `--mode GNB_ONLY|LNB_ONLY|DASHBOARD_ONLY`, PARTIAL은 `--files <수정 파일,...>`을 전달한다. 최종 제출 경로 확인은 같은 실행에 `--result <실제 React HTML 또는 bootstrap>`을 추가한다.
8. FAIL만 수정하고 수정 범위만 PARTIAL 재검사한다. 정상 검사는 반복하지 않는다. Guard PASS는 정적 계약만 뜻한다. 화면별 빌드와 실제 React 브라우저 렌더링(utility 적용·레이아웃·핵심 동작)을 최소 1회 확인한다. 미확인은 `NOT VERIFIED`로 보고한다. [Guard 범위](docs/guidelines/ai-generation-guard.md).
9. Component·Pattern·Theme·대표 Story 디자인/동작·공개 API를 요청 없이 변경하지 않는다. 결과는 실제 사용 요소·Navigation·검증·미검증만 간결하게 보고한다.

필요할 때만 [보존된 상세 지침](docs/guidelines/ai-implementation-details.md)을 읽는다. 신규 화면에는 위 필수 규칙이 우선한다.