Private

Public Access

0 Fork 0

Files

T

shkim4 7621934f69 docs(ai): split SW usage into general / viewer mode in packaged AI guides

- Usage types are now Web / SW (general mode, viewer mode) / OrgChart / mixed.
  Shared AI_GUIDE step 1 asks for the SW mode only when the request or the
  project setting (HMDesign 사용 유형: SW 일반 | SW 뷰어) leaves it open;
  examples B0/B1/B2 cover "HMDesign SW로 화면을 만들어 주세요", general and viewer.
- Missing-component handling in three steps (reuse in the chosen type/mode ->
  build with that mode's tokens -> HMDesign-consistent style, reported as
  "AI 구성 값 — 디자인 확인 필요"), plus SW general/viewer separation rules.
- sw/ai: AI_USAGE §0 mode selection, catalog §8 lists all 33 SWViewer* exports,
  DESIGN_RULES §11 viewer tokens, PATTERNS 7 viewer composition; examples B/F
  marked as general mode. ui/ai and org-chart/ai aligned with the new types.
- AGENTS_SNIPPET, AGENTS.md and MAINTAINING updated; copies synced.
- scripts/ai-docs.mjs: shared-copy check ignores CRLF/LF (core.autocrlf=true
  checks out packages/sw as LF and the rest as CRLF).
- Verification record updated (code samples typechecked, built and rendered).

2026-10-19 17:34:15 +09:00

4.8 KiB

Raw Blame History

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` + `examples/`(A~F 일반 모드, H 뷰어 모드)	포함
`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)에서 처리합니다.

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

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

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

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

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

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

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

4.8 KiB Raw Blame History