# HMDesign 패키지 AI 지침 유지보수

이 문서는 HMDesign 저장소 유지보수자용이며 패키지에 포함되지 않습니다. 패키지에 포함되는 AI 지침은 소비 프로젝트의 AI 코딩 도구가 읽는 **실행 규칙**이므로, 코드와 다른 내용이 남지 않게 아래 절차로 함께 갱신합니다.

## 1. 구조

| 위치 | 역할 | 패키지 포함 |
|---|---|---|
| `docs/ai/AI_GUIDE.md` | 공통 진입점 원본(사용 유형 Web / SW 일반·뷰어 / OrgChart / 혼합 선택, 없는 컴포넌트 처리 3단계, 1~7단계, 패키지·SW 모드 분리, 예시 A~D, 소비 프로젝트 설정) | 사본으로 포함 |
| `docs/ai/AGENTS_SNIPPET.md` | 소비 프로젝트 루트 `AGENTS.md`에 붙일 연결 문구 원본 | 사본으로 포함 |
| `docs/ai/MAINTAINING.md` | 이 문서 | 미포함 |
| `packages/ui/ai/` | Web: `AI_USAGE`, `COMPONENT_CATALOG`, `DESIGN_RULES`, `COMPOSITION_PATTERNS` | 포함(`files`) |
| `packages/sw/ai/` | SW: 위 4종(`AI_USAGE.md` §0 = SW 일반/뷰어 모드 선택) + 뷰어 모드 전용 `VIEWER.md` + 일반 모드 하단 막대 `FOOTER.md`(공유 사본 포함 Markdown 8개) + `examples/` 10개(A~G·I 일반 모드 — G 로고 클릭 메뉴, I Footer / H 뷰어 모드 / J 테마 설정)와 예제 보조 파일(`SWSearchControl.tsx`, `sample-data.ts`, `example-layout.css`, `sw-search-control.css`) | 포함 |
| `packages/org-chart/ai/` | OrgChart(Core + React 어댑터 API): 위 4종 | 포함 |
| `packages/org-chart-react/ai/` | `AI_USAGE`(Core `ai/` 안내) | 포함 |
| `scripts/ai-docs.mjs` | 동기화(`--sync`)·검사(`--check`) | — |

`@hm-design/center-graphic`에는 AI 지침이 없습니다(공통 가이드에 "README만"으로 안내). 추가하려면 같은 4종 구조로 만들고 `scripts/ai-docs.mjs`의 `packages`에 등록합니다.

저장소 루트 `AGENTS.md`·`CLAUDE.md`는 **이 저장소를 개발하는 AI**용 규칙이고, `packages/*/ai/`는 **패키지를 설치해 쓰는 소비 프로젝트의 AI**용 규칙입니다. 내용이 겹쳐도 서로를 대신하지 않습니다. 패키지 `ai/` 문서는 패키지 밖(`../../docs/…`)을 링크하지 않습니다(설치 후 존재하지 않음).

## 2. 컴포넌트를 추가·수정할 때

같은 변경(같은 Commit)에서 처리합니다.

1. **공개 Export가 바뀌면** 해당 패키지 `ai/COMPONENT_CATALOG.md`에 이름·용도·HM Props(기본값)를 추가·수정·삭제합니다. 내부 전용 이름은 "공개하지 않은 것" 절에만 적습니다.
2. **Props·Variant 기본값·허용 조합이 바뀌면** 카탈로그 표와 `COMPOSITION_PATTERNS.md`의 예시 코드를 함께 고칩니다.
3. **토큰·CSS 값이 바뀌면** `DESIGN_RULES.md`의 표를 실제 CSS 선언과 맞춥니다(값은 CSS에서 복사, 추측 금지).
4. **새 화면 유형·조합 규칙이 생기면** `COMPOSITION_PATTERNS.md` §0 표에 행을 추가합니다. SW 뷰어 모드 컴포넌트(`SWViewer*`)를 바꾸면 `VIEWER.md`와 카탈로그의 뷰어 절을 함께 고치고, 일반/뷰어 모드 구분이 바뀌면 `packages/sw/ai/AI_USAGE.md` §0과 공통 `AI_GUIDE.md` 1단계·5단계를 같이 맞춥니다.
5. 공통 규칙(유형·SW 모드 선택·혼합·보고 형식)이 바뀌면 `docs/ai/AI_GUIDE.md`만 고치고 `npm run sync:ai-docs`로 사본을 갱신합니다. 패키지 사본을 직접 고치지 않습니다.
6. `npm run check:ai-docs`를 실행해 PASS를 확인합니다.
7. 버전을 올리면 카탈로그 첫 줄의 기준 버전을 같이 바꿉니다.

## 3. `npm run check:ai-docs`가 검사하는 것

1. `docs/ai`의 공유 파일과 각 패키지 사본이 같은지(줄바꿈 CRLF/LF 차이는 무시 — `core.autocrlf=true`에서 `packages/sw`만 `.gitattributes`로 LF checkout)
2. 각 패키지 `package.json`의 `files`에 `ai`가 있는지
3. 공개 진입점(`src/index.ts` 등, `export *` 재귀 포함)의 **모든 Export 이름이 카탈로그에 나오는지**
4. 카탈로그에 Export처럼 보이지만(기존 Export 이름으로 시작) 실제로는 없는 이름이 없는지 — 예: `DialogFancyPanel`. "공개하지 않은 것"·"없는 것"·"지원하지 않는" 절은 제외
5. `ai/` 문서의 상대 링크가 존재하고 패키지 밖(저장소 전용 문서)을 가리키지 않는지

검사하지 않는 것: Props 이름·기본값·토큰 값의 정확성, 예시 코드의 컴파일. 이 부분은 리뷰와 소비 프로젝트 검증(§4)으로 확인합니다.

## 4. 소비 프로젝트 검증 (배포 전 권장)

1. `npm run build:packages` 후 `npm pack -w <패키지> --ignore-scripts --pack-destination <임시 폴더>`
2. 임시 소비 프로젝트(React 19 + Vite + Tailwind CSS 4)에 tarball 설치
3. `node_modules/@hm-design/*/ai/AI_GUIDE.md`가 있는지, 링크가 설치 위치에서 열리는지 확인
4. `COMPOSITION_PATTERNS.md`의 예시를 옮겨 `tsc --noEmit`·`vite build`·브라우저 렌더링 확인
5. 결과와 NOT VERIFIED를 기록

`npm pack`의 `prepack`은 build를 다시 실행합니다. 공유 `dist`를 쓰는 build를 동시에 돌리지 않습니다.