HMDesign/AGENTS.md

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

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

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

## 패키지 소비용 AI 지침 — 2026-10-19

- 이 파일은 HMDesign 저장소를 개발하는 AI용이다. 패키지를 설치한 **다른 프로젝트**의 AI가 읽는 지침은 각 패키지의 `ai/`(`packages/ui/ai`, `packages/sw/ai`, `packages/org-chart/ai`, `packages/org-chart-react/ai`)에 있고 공통 진입점 원본은 [docs/ai/AI_GUIDE.md](docs/ai/AI_GUIDE.md)다.
- 사용 유형은 Web / SW(**SW 일반 모드**·**SW 뷰어 모드**) / OrgChart / 혼합이다. SW 작업은 모드를 먼저 정하고(불명확하면 질문, 요청·설정으로 명확하면 묻지 않음) 선택 모드의 컴포넌트·토큰만 쓴다 — 일반 `SWHeader`·`SWPopup`, 뷰어 `SWViewerHeader`·`SWViewerMenu`·`SWViewerPanel`. 기준은 [packages/sw/ai/AI_USAGE.md](packages/sw/ai/AI_USAGE.md) §0과 공통 가이드 1·4·5단계이며 이 파일에 본문을 복사하지 않는다.
- 공개 Export·Props·토큰을 바꾸면 같은 변경에서 해당 `ai/` 문서를 갱신하고 `npm run check:ai-docs`를 실행한다. 공통 가이드는 원본만 고친 뒤 `npm run sync:ai-docs`로 사본을 갱신한다. 절차는 [docs/ai/MAINTAINING.md](docs/ai/MAINTAINING.md).

## Typography — 공통 정책

- HMDesign의 Font Weight는 400(Regular), 500(Medium), 700(Bold)의 3단계만 사용한다. Font Weight 600은 사용하지 않으며, 카드 제목은 700을 기본으로 한다.
- 신규 컴포넌트·AI 생성 코드·Storybook에 동일하게 적용한다. 폰트 패밀리·크기·행간·자간과 기존 OrgChart 카드·연결선·배치는 유지한다. 외부 CSS 커스터마이징은 기본 정책과 구분한다.

## AI 조직도 생성 — 공통 정책

- 확장형 OrgChart의 조직 계층 생성 시 팀(Team)을 셀(Cell)의 직접 자식 또는 모든 하위 계층에 배치해서는 안 된다. 팀 → 셀은 허용한다. Storybook 샘플 및 AI가 생성하는 조직 데이터는 정의된 조직 위계를 따른다. 셀을 무조건 말단으로 처리하거나 다른 조직 유형의 제약을 추가하지 않는다. 상세 기준과 제공 데이터 충돌 처리는 [AI 생성 정책](docs/org-chart/ai-page-generation-rules.md#21-확장형-조직-위계-규칙)을 따른다. 이는 데이터 생성 정책이며 제품 런타임 Validator·이동 정책·공개 API 변경을 뜻하지 않는다.
- OrgChart UI 수정 또는 AI 생성 작업은 [최종 디자인 승인 기록](docs/org-chart/design-approval.md)을 먼저 확인해 승인된 기본 디자인을 따른다. 기본값 변경·외부 테마 커스터마이징·데이터 생성의 구분과 접근성 미해결 상태는 해당 문서를 따른다.
- 자연어 또는 JSON·CSV·Excel에서 **새 조직도 컴포넌트 또는 전체 페이지를 생성하는 작업**은 먼저 [AI 조직도 자동 생성 정책](docs/org-chart/ai-page-generation-rules.md)을 읽고 적용한다. 생성 방식 미지정 시 코드 작성 전에 위 정책의 사전 선택 질문으로 Chart Only / Full Page를 확인하고 답변 후 구현한다. 이미 명시한 방식은 다시 묻지 않는다. 회사·조직 유형·Depth·인원수를 특정 사례의 기본값으로 고정하지 않는다.
- **Chart Only**는 기존 페이지에 삽입 가능한 독립 컴포넌트로 흰색 캔버스·조직도 노드·연결선, 최초 Fit to View·마우스 휠 확대/축소·Pan을 제공하며 외부 제목·통계·설명·조작 패널을 생성하지 않는다. **Full Page**는 기존 HM UI를 우선 재사용해 요청된 제목·정보·필터·컨트롤과 전체 배치·반응형을 구성한다. 두 방식 모두 기존 OrgChart Core·React Wrapper와 정확한 요청 구조·인원·데이터를 사용한다. Fixed·Auto/Expanded는 생성 방식 선택을 대신하지 않는다. Chart Only에는 아래 일반 업무 화면의 Navigation 의무 대신 해당 정책의 최소 화면 규칙을 적용하고, Full Page에는 기존 HM 화면 계약을 적용한다. 공개 API·Theme·React·접근성·검증 규칙은 계속 적용한다.
- 기존 Full Composition·Expanded OrgChart·Department Colors·Overview·P9.5·P-AI1에는 소급 적용하지 않는다. 일반 업무 화면과 명시적인 기존 화면 수정에는 기존 규칙 및 해당 요청 범위를 유지한다.

1. 범위 `STORYBOOK_ONLY | PRODUCTION_UI | BOTH`, Runtime, 요구사항·필수 동작·완료 조건을 확인한다. 신규 AI 업무 화면은 실제 HM React 컴포넌트를 사용한다. 명시적 다른 Runtime adapter는 [상세 계약](docs/guidelines/runtime-portability.md)을 따른다.
2. [기능별 선택·완료 계약](docs/guidelines/ai-screen-contract.md) → [Component / Pattern 인덱스](docs/guidelines/component-pattern-reference.md) → 선택한 문서·대표 All Story·필요한 Props 순으로 읽는다. Import는 `@hm-design/ui` 공개 API가 기본이다. 의존성은 package.json의 exports/types와 실제 파일 목록을 확인하며 내부 src/dist 경로를 추측하지 않는다. verification Story는 운영 기준이 아니다.
3. 요구 기능에 맞는 기존 Pattern을 먼저 확인한 뒤 기존 Component → Variant/Prop → Composition 순으로 재사용한다. 목록 검색은 [FilterBar](docs/patterns/filter-bar.md)를 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](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 `staticStatus`는 정적 계약, 원본 `status`는 미검증을 포함한다. 실제 React 빌드·브라우저 결과는 [별도 증거 연결](docs/guidelines/ai-generation-guard.md#runtime-증거-연결)로 기록한다. 원본 미검증을 덮어쓰지 않는다.
   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는 디자인 의도 승인이 아니다. [검사 범위와 증거 형식](docs/guidelines/ai-generation-guard.md#css-intent와-동적-token-검사-2026-10-10)을 따른다.
9. Field Label은 공개 [Label](docs/components/label.md#5-api)과 실제 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`다.

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

## 작업 위치와 Git 정책 — 2026-10-20 개정 (2026-10-11 정책 대체)

- 작업 위치는 고정 폴더가 아니라 **사용자가 지정한 브랜치의 작업 트리**다(별도 Clone·worktree 포함). 시작 전 절대경로·현재 브랜치·HEAD·공식 origin `https://gitea.hmac.kr/b25027/HMDesign.git`·최신 원격 HEAD·Working Tree·기존 미커밋 변경을 확인한다. 같은 폴더를 다른 작업자나 AI가 수정 중일 수 있으므로 수정 전 파일을 다시 읽는다.
- 기능 작업은 기능 브랜치(예: `feature/sw-package`, `feature/orgchart-package`)에서 진행하고 `main`에는 사용자가 지시한 병합(PR 등)으로만 반영한다. `main` 직접 Commit/Push와 병합은 사용자의 명시적 지시가 있을 때만 수행한다.
- 요청에 필요한 부분만 수정하고 기존 Component·Pattern·Theme·Storybook을 보존한다. 변경 영향과 관련 MD/Storybook 정합성을 검증하고 유효한 기존 정상 검증은 불필요하게 반복하지 않는다.
- Commit·Push는 사용자 승인 후 수행한다. 관련 파일만 Stage하고 Staged Diff를 검토한다. 직전에 대상 원격 브랜치를 다시 확인하고, 시작 기준 이후 원격이 변경됐거나 중요한 충돌이 있으면 자동으로 덮어쓰지 않고 중단한다. 완료 후 Local/Remote SHA와 Working Tree를 확인한다.
- `main` push는 웹 Storybook(`https://design.hmac.kr/`) 배포 Workflow를 실행한다(`.gitea/workflows/deploy-storybook.yml`). 병합 전에 운영 웹을 변경하지 않는다.
- GitHub 이전 원본 폴더·remote에는 수정/Push하지 않는다. Force Push·Reset·Clean·기존 이력 삭제·백업 브랜치 변경·무관한 파일 Stage를 금지한다.