HMDesign/AGENTS.md

HMDesign AI 화면 구현 — 필수 규칙

기준 우선순위: 2026-10-10 추가 수정 요청의 확정 사항 → 충돌하지 않는 D-01/D-02 → 현재 HM Component/Pattern/Theme → 현재 Storybook/구현 → 과거 문서. 현재 추가 수정 기준. 미확정 값은 임의 확정하지 않으며 과거 검증 기록은 보존합니다.

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

AI 조직도 독립 페이지 생성 — 공통 정책

• 자연어 또는 JSON·CSV·Excel에서 새 독립 조직도 페이지를 생성하는 작업은 먼저 AI 조직도 자동 생성 정책을 읽고 적용한다. 회사·조직 유형·Depth·인원수를 특정 사례의 기본값으로 고정하지 않는다.
• 기본 화면에는 요청한 조직도와 기존 탐색 기능만 표시한다. AI 채팅·생성 입력·JSON·테스트·별도 통계·개발 안내와 Navigation은 요청 없이 추가하지 않는다. 이 범위에서는 아래 일반 업무 화면의 Navigation 의무 대신 해당 정책의 최소 화면 규칙을 따른다. 공개 API·Theme·React·접근성·검증 규칙은 계속 적용한다.
• 기존 Full Composition·Expanded OrgChart·P9.5·P-AI1에는 소급 적용하지 않는다. 일반 업무 화면과 명시적인 기존 화면 수정에는 기존 규칙 및 해당 요청 범위를 유지한다.

1. 범위 STORYBOOK_ONLY | PRODUCTION_UI | BOTH, Runtime, 요구사항·필수 동작·완료 조건을 확인한다. 신규 AI 업무 화면은 실제 HM React 컴포넌트를 사용한다. 명시적 다른 Runtime adapter는 상세 계약을 따른다.
2. 기능별 선택·완료 계약 → Component / Pattern 인덱스 → 선택한 문서·대표 All Story·필요한 Props 순으로 읽는다. Import는 @hm-design/ui 공개 API가 기본이다. 의존성은 package.json의 exports/types와 실제 파일 목록을 확인하며 내부 src/dist 경로를 추측하지 않는다. verification Story는 운영 기준이 아니다.
3. 요구 기능에 맞는 기존 Pattern을 먼저 확인한 뒤 기존 Component → Variant/Prop → Composition 순으로 재사용한다. 목록 검색은 FilterBar를 Table 유무와 관계없이 검토한다. 미사용 시 요구사항과 맞지 않는 API·구조 제약을 기록하며 강제하지 않는다. 기본 HTML·임의 CSS·data-slot으로 HM을 모방하지 않는다. 재사용은 import가 아닌 실제 렌더링으로 확인한다.
4. 기존 Theme/Semantic Token의 실제 선언을 확인한다. 변수 이름을 추측하거나 없는 Token을 fallback 색으로 감추지 않는다. React CSS entry는 index.css → hm-theme.css 및 필요 시 공개 status CSS를 연결한다. Runtime Theme, Tailwind/Asset 계약은 관련 변경 때만 읽는다.
5. 페이지 Navigation은 GNB/LNB/DASHBOARD 중 하나다. 공식 LNB ONLY는 허용한다. 신규 GNB ONLY·DASHBOARD ONLY의 Sidebar는 금지한다. GNB는 GNBMobileMenu도 구성한다. Dashboard는 전용 48px Header와 최소 폭 960px·내부 스크롤을 유지한다. 미지정 시 선택 근거를 기록한다.
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 staticStatus는 정적 계약, 원본 status는 미검증을 포함한다. 실제 React 빌드·브라우저 결과는 별도 증거 연결로 기록한다. 원본 미검증을 덮어쓰지 않는다. CSS 검사는 styleEvidence/결합 styleVerification의 STATIC·RUNTIME·DESIGN_INTENT·FINAL을 함께 보고한다. HM Component의 HEX/RGB/HSL·Spacing/Radius 하드코드 override는 STYLE-001 FAIL이며 일반 콘텐츠 CSS는 일괄 금지하지 않는다. 동적 Token의 유한 후보는 모두 선언을 확인하고 외부 입력·Props·미해석 className/style은 위치별 Runtime 근거 없이는 NOT VERIFIED다. 문서 recipe나 computed PASS는 디자인 의도 승인이 아니다. 검사 범위와 증거 형식을 따른다.
9. Field Label은 공개 Label과 실제 control ID/접근성 이름을 연결한다. 레이아웃·콘텐츠용 HTML은 허용하며 HM이 지원하지 않는 native control/label은 이유를 기록한다. 무조건적인 native HTML 금지는 적용하지 않는다.
10. 요구사항에 없는 CSV·다운로드·외부 API·추가 메뉴·Navigation은 구현하지 않고 제안으로만 보고한다. Story의 예제 기능은 필수 요구사항이 아니다. Component·Pattern·Theme·대표 Story·공개 API를 요청 없이 변경하지 않는다.
11. 390/768/1280/1440px에서 overflow·줄바꿈·Navigation을 확인한다(Dashboard는 960px 내부 스크롤). 숨김 absolute 알림의 위치 기준과 문서/내부 scrollHeight·clientHeight, ID의 한 줄 식별 가능성도 확인한다. Label/접근성 이름, 키보드·focus 복귀, disabled/readOnly, 핵심 상호작용을 확인한다. 결과는 실제 사용 요소·Pattern 선택/미사용 이유·Navigation·검증·미검증으로 보고하며 확인하지 않은 항목은 NOT VERIFIED다.

필요할 때만 보존된 상세 지침을 읽는다. 신규 화면에는 위 필수 규칙이 우선한다.

공식 작업 경로와 Git 정책 — 2026-10-11 사용자 확정

• HMDesign 실제 수정은 D:\디자인시스템\HMDesign-Gitea-Transfer에서 진행한다. 시작 전 절대경로·main 브랜치·공식 origin https://gitea.hmac.kr/b25027/HMDesign.git·최신 원격 HEAD·Working Tree·기존 미커밋 변경을 확인한다.
• 퍼블리셔 요청에 필요한 부분만 수정하고 기존 Component·Pattern·Theme·Storybook을 보존한다. 변경 영향과 관련 MD/Storybook 정합성을 검증하고 유효한 기존 정상 검증은 불필요하게 반복하지 않는다.
• 필수 검증을 통과하면 관련 파일만 Stage하고 Staged Diff를 검토한 뒤 Commit·공식 Gitea main 일반 Push를 수행한다. 작업별 사용자의 명시적 Commit/Push 보류 지시가 있으면 그 지시를 우선한다.
• Commit/Push 직전에 원격 main을 다시 확인한다. 시작 기준 이후 원격이 변경됐거나 중요한 충돌이 있으면 자동으로 덮어쓰지 않고 중단한다. 완료 후 Local/Remote SHA와 Working Tree를 확인한다.
• GitHub 이전 원본 폴더·remote에는 수정/Push하지 않는다. Force Push·Reset·Clean·기존 이력 삭제·백업 브랜치 변경·무관한 파일 Stage를 금지한다.