shkim4
b7227ee963
- Five checked items from the independent session's report: document sync, 33 viewer exports, SW general/viewer mode selection, component search, three-step rule for new UI - Live ResizeObserver re-layout and the real ask/answer flow stay NOT VERIFIED
82 lines
9.8 KiB
Markdown
82 lines
9.8 KiB
Markdown
# 패키지 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 결함: 별도 세션에서 수정 중(이 기록의 범위 밖).
|