HMDesign/docs/ai/verification-2026-10-19.md

패키지 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(⋯)로 이동(반응형 동작 확인, 세부 경계값 미측정)

최종 독립 Cold-start 검증 — PASS (7621934 기준)

독립 세션의 보고 결과를 옮겨 적은 것이다(이 문서를 작성한 세션이 다시 실행한 결과가 아님). 기준 Commit 7621934f69a0324041ea59137b764117841d44b0, 독립 세션 scratchpad의 격리 사본(git archive 7621934)·tarball 4종·소비 프로젝트에서 수행, 원본 폴더는 읽기만 했다. be7a04a→7621934 변경은 AI 문서와 scripts/ai-docs.mjs 25개 파일뿐이라 패키지 빌드·Web·OrgChart 코드 PASS는 be7a04a 결과를 재사용했다(두 tarball은 ai/*.md만 다름).

항목	판정	근거(독립 세션 보고)
AI 문서 동기화	PASS	check:ai-docs 통과(be7a04a의 FAIL 3건 해소). 4개 사본 AI_GUIDE.md는 줄끝을 LF로 맞추면 SHA-256 1a1e0f98727f206191eadcea524ef2aa81d92e30c0a5d4fdbae635d0fbb46420로 동일(원본 바이트는 ui·org-chart·org-chart-react CRLF, sw LF)
Viewer Export 33개	PASS	설치 .d.ts에서 추출해 카탈로그와 대조: 누락 0, 33개 모두 §8
SW 일반/뷰어 모드 선택	PASS	"도면 뷰어" 요청은 SW AI_USAGE.md §0.1 근거로 질문 없이 뷰어 모드. 모드 근거가 없는 요청은 모드만, 애매한 요청은 묻도록 되어 있음(문서 판단)
컴포넌트 검색	PASS	뷰어 문서 순서만으로 필요한 API를 모두 찾음, 추측 API 없음, Typecheck 오류 0
신규 UI 구현 규칙(3단계)	PASS	간격은 --hm-sw-viewer-gap 토큰, 토큰 없는 결과 행 정렬만 "AI 구성 값 — 디자인 확인 필요"로 보고, 뷰어 화면에 일반 모드 컴포넌트 혼입 없음(브라우저 확인)

실행: Typecheck·Build(4개 화면 entry) PASS. 뷰어 검색 패널 열림 Focus·검색·결과 선택·Escape 닫힘·Focus 복귀, 폭 1181 / 1179 / 901 / 899px에서 새로고침 기준 More 이동과 More에서 패널 열기 확인.

NOT VERIFIED

• 실시간 ResizeObserver 동작: 창 폭을 바꾸는 도중의 More 재배치. 검증용 내장 브라우저의 크기 조정에서 ResizeObserver가 호출되지 않아 판정 불가, 새로고침 기준 동작만 확인(독립 세션 보고).
• 질문 규칙의 실제 대화 흐름(질문 → 답변 → 구현). 독립 검증도 문서 판단으로만 확인했다.
• 독립 검증에서 쓰지 않은 뷰어 기능: 단독·우클릭 SWViewerMenu, iconOnlyBelow(Switch·Slider·modal 패널은 위 코드 예제 검증에서 확인).
• SW 일반/뷰어 모드 전환을 소비 프로젝트에서 실제로 구성한 화면, SW 화면 + 조직도 조합.
• Web·OrgChart의 기존 NOT VERIFIED(Web 1280px, Hover 세부, OrgChart 키보드 Pan)는 그대로.
• SWPopup + anchorRef 열림 Focus 결함: 별도 세션에서 수정 중(이 기록의 범위 밖).