shkim4
7621934f69
- 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).
7.4 KiB
7.4 KiB
패키지 AI 지침 구축 검증 기록 (2026-10-19)
범위: 공통 진입점(docs/ai/AI_GUIDE.md → 각 패키지 ai/AI_GUIDE.md), Web(packages/ui/ai/)·OrgChart(packages/org-chart/ai/, packages/org-chart-react/ai/) 신규 문서, SW 기존 ai/ 연결, 패키지 files에 ai 추가, scripts/ai-docs.mjs. 런타임 코드·CSS·Storybook·공개 API 변경 없음.
실행한 검증
| 항목 | 결과 |
|---|---|
npm run check:ai-docs (사본 일치, files, 카탈로그 ↔ 공개 Export 양방향, ai/ 링크) |
PASS |
검사기 음성 테스트(Export 누락, 가짜 이름 DialogFancyPanel, 사본 불일치, 패키지 밖 링크를 임시 주입) |
4건 모두 FAIL로 검출 후 원복, 재검사 PASS |
npm run build:packages |
PASS |
npm pack --ignore-scripts 4종(ui 0.1.0, sw 0.2.0, org-chart 0.1.0, org-chart-react 0.1.0) |
모든 tarball에 package/ai/AI_GUIDE.md·AGENTS_SNIPPET.md와 패키지별 문서 포함 |
| 독립 소비 프로젝트(React 19.3.0, Vite 8.3.0, Tailwind CSS 4.3.3, TypeScript 7.0.2)에 tarball 설치 | node_modules/@hm-design/*/ai/ 4곳 존재, 설치 위치 기준 상대 링크 42개 모두 해석, AI_GUIDE.md 4사본 동일 |
AI_GUIDE.md §9의 스니펫 연결 명령(cat … >> AGENTS.md) |
동작 |
문서만 근거로 구현: Web+OrgChart 페이지(LNB ONLY, PageHeader, 신규 StatCard = Card + 토큰, FilterBar + DataTable, AlertDialog, OrgChart Full Page + /hm-dialog), Chart Only 미리보기, SW 뷰어(SWHeader + SWToolGroup + SWPopup, 별도 entry) |
tsc --noEmit(strict, skipLibCheck false) PASS, vite build PASS |
| 브라우저(1440px) | HM 외형 렌더링(글꼴 Noto Sans KR, Card·Button 토큰 값), 조회 1건 → 초기화 3건, 삭제 확인창 열림·Escape 닫힘·Trigger Focus 복귀, 조직도 직원 카드 → Web Dialog 표시·Escape 닫힘, 회사 Select → selectedCompanyIds 반영, 콘솔 오류 0, 가로 넘침 없음 |
| 브라우저(390px) | LNB Desktop 숨김·LNB Mobile Header 표시, 문서 가로 넘침 없음 |
| Chart Only(1280px) | 흰 캔버스 + 노드 + 연결선만, 외부 제목·버튼·요약 없음, 중앙 Fit |
| SW 뷰어 | Popup 열림·내부 Focus·Escape 닫힘·Trigger 복귀, --hm-sw-header-*가 body에는 없고 .hm-sw-theme 범위에만 존재 |
검증 프로젝트는 세션 임시 폴더에서 수행했고 저장소에 추가하지 않았다.
NOT VERIFIED
- 다른 AI 코딩 도구(Codex·Cursor 등)가 소비 프로젝트의
AGENTS.md만 보고 스스로ai/문서를 찾아가는지. 이번 시나리오는 이 문서를 작성한 같은 AI가 수행했으므로 독립 Cold-start 검증이 아니다. - Web CSS와 SW를 한 문서에서 함께 쓰는 경우의 시각 결과(문서에 NOT VERIFIED로 명시, 별도 entry 권장).
- 768px 화면, 실제 터치·스크린리더, Registry publish 후 설치.
- 문서의 Props 기본값·토큰 값 전부를 기계적으로 대조하지는 않았다(검사기는 Export 이름·링크·사본만 검사). 이번 작성은 소스를 직접 확인했다.
추가 검증 — SW 일반 / 뷰어 모드 구분 (2026-10-19)
범위: feature/sw-viewer-header(68fbcf6)를 merge(be7a04a)한 뒤, 사용 유형을 Web / SW(일반·뷰어) / OrgChart / 혼합으로 나누고 SW 모드 선택·혼합 금지·없는 컴포넌트 처리 3단계를 공통 가이드와 각 패키지 ai/ 문서에 반영. 런타임 코드·CSS·Storybook·공개 API 변경 없음. 위 기록의 "SW 뷰어(SWHeader + SWToolGroup + SWPopup)"는 당시 명칭이며, 현재 기준으로는 일반 모드 Header + 도구 막대 구성이다(뷰어 모드 = SWViewer*).
| 항목 | 결과 |
|---|---|
npm run sync:ai-docs → npm run check:ai-docs (뷰어 Export 33개 포함 카탈로그 ↔ 공개 Export) |
PASS |
npm run build -w packages/sw 후 npm pack --ignore-scripts 4종을 임시 소비 폴더 node_modules/@hm-design/*에 풀어 확인 |
sw tarball에 ai/VIEWER.md·examples/ExampleH-ViewerMode.tsx 포함, dist/index.d.ts가 sw-viewer를 export * |
뷰어 문서(VIEWER.md, 카탈로그 §8, DESIGN_RULES §11, PATTERNS 7, AI_USAGE §0)의 Props·토큰 이름 ↔ sw-viewer 소스·sw-viewer.css |
일치(남은 차이는 예제 변수명과 "없는 Props" 목록뿐) |
설치 위치 기준 시나리오 정적 검사 124건: 공통(사본 동일·상대 링크), Web(설정 → ui/ai, 다른 영역 이관, 3단계), SW 미지정("HMDesign SW로 화면을 만들어 주세요" → 유형 확정 + 모드 질문만, 애매하면 추측 금지), SW 일반(설정 → 묻지 않음, SWViewer* 금지, 예제 B·F 명칭), SW 뷰어(설정·요청 근거 → VIEWER.md, SWHeader/SWPopup 재스타일 금지, 주요 8개 컴포넌트가 카탈로그와 설치 .d.ts에 존재), OrgChart(Chart Only / Full Page 질문 1회, 승인 디자인 유지), 혼합(SW 영역 모드, 보고 형식) |
124 PASS / 0 FAIL |
Cold-start 검증(be7a04a 기준) 지적 사항 반영
| 지적 | 현재 작업본 |
|---|---|
check:ai-docs FAIL — sw 사본 AI_GUIDE.md·AGENTS_SNIPPET.md 불일치 |
원인은 내용이 아니라 줄바꿈: core.autocrlf=true에서 docs/ai·ui·org-chart는 CRLF, packages/sw(.gitattributes eol=lf)는 LF로 checkout. scripts/ai-docs.mjs 사본 비교를 줄바꿈 무시로 변경. 작업본 스냅샷을 git archive(CRLF checkout 재현)로 풀어 검사 PASS, 실제 내용 차이를 넣으면 FAIL 검출 |
check:ai-docs FAIL — SW 카탈로그에 SWViewer* 33개 누락 |
카탈로그 §8에 33개 모두 등재, 검사 PASS |
| 카탈로그 "표에 없는 이름은 공개 API 아님"과 VIEWER.md 충돌 | §8 등재로 해소, 머리말 "무엇을 쓸까"에 일반/뷰어 분기 |
"도면 뷰어" 요청 시 예시 B(SWHeader+SWPopup)와 VIEWER.md가 다른 답 |
공통 1단계 4번·예시 B0/B1/B2, SW AI_USAGE.md §0(판단 순서·질문 문구·혼합 금지), 예제 B·F는 일반 모드로 명시 |
SWPopup anchorRef 사용 시 열릴 때 Focus 미이동 |
이번 AI 지침 작업 범위 밖 — 별도 수정 대상. 코드 수정하지 않음 |
추가 검증 — 코드 예제 (변경분만, 기존 PASS 재사용)
| 항목 | 결과 |
|---|---|
임시 소비 프로젝트(설치 tarball, React 19.3.0, TypeScript 7.0.2, Vite 8.3.0)에서 COMPOSITION_PATTERNS.md 7 코드 조각과 VIEWER.md §5 코드 조각을 본문 그대로 감싸고 자유 변수만 선언, 예제 H 포함 |
tsc --noEmit(strict, skipLibCheck false) PASS, vite build PASS |
| 브라우저 1440px — PATTERNS 7 | 샘플 메뉴 열림·선택 → 파일명 표시, 도면 공간 탭 전환(space=layout), 설정 패널 열림 시 패널 안 Focus·Escape 닫힘·토글로 Focus 복귀, 정보 modal Focus·확인 닫힘, 가로 넘침 없음, 글꼴 Noto Sans KR, 콘솔 오류 0 |
| 브라우저 1440px — VIEWER.md §5 | 파일명 표시, 전체 보기 명령, 설정 패널 Focus, Switch 토글·Label 연결 |
| 800px 폭 | 항목이 More(⋯)로 이동(반응형 동작 확인, 세부 경계값 미측정) |
NOT VERIFIED
- 독립 AI가 Cold-start로 이 문서를 읽고 실제로 모드를 묻거나 고르는지(행동 검증). 위 검사는 문서에 필요한 판단 문구가 읽는 경로에 있는지만 확인한다.
- 확정 Commit 기준 독립 Cold-start 재검증(별도 1회 예정).
- SW 일반/뷰어 모드 전환을 소비 프로젝트에서 실제로 구성한 화면, SW 화면 + 조직도 조합.