HMDesign/docs/reports/ai-quality-improvement-2026-10-10.md

# HMDesign AI 화면 생성 품질 개선 — 2026-10-10

RESULT: PARTIAL. 검증한 구현·회귀 검사는 통과했다. 교차 모델 생성, 수치 디자인 점수, 전체 접근성 적합성은 NOT VERIFIED다. 이전 실험과 생성 조건이 달라 NON-COMPARABLE이며 품질 점수 상승을 주장하지 않는다.

TARGET: `D:\디자인시스템\hmdesign` / Runtime: React / Scope: BOTH(공개 Pattern·Storybook Reference 개선 + 독립 실험 화면). 초기 Working Tree는 clean이었다.

BASE_SHA: `0b2bc376aa8b6af9d2492b5620d8ae776391508d`

IMPLEMENTATION_SHA: `cb451b34363c72b50c1bb44a1f10b63b8f5e0163`

FINAL_SHA: 이 문서·집계 스크립트를 포함한 최종 HEAD는 제출 응답에 기록한다. 문서는 자신의 commit hash를 자체 포함할 수 없으므로 위 구현 기준과 분리한다.

## 원인과 개선 범위

기존 생성 화면 10개의 공통 RENDER-002는 React bootstrap 확인만으로 브라우저 실행을 증명할 수 없다는 판정이었다. Production Graph 실패라고 일괄 해석하거나 규칙을 완화해서는 해결되지 않는다. 일부 기존 소비 CSS의 의도 판단도 REUSE-003으로 남아 있었다. 낮은 추론의 보존된 02·06·07 결과에서는 미정의 HM Token 참조 17곳(고유 이름 8개)을 실제 확인했다.

| 우선순위 | 결과 | 근거와 영향 |
|---|---|---|
| P0_GUARD | PASS(검사 계약 범위) | entry별 연결 CSS·공개 Theme 정의로 TOKEN-001 감지. 계산된 참조/불완전 graph는 NOT VERIFIED. scope/profile/Production Graph 분리 유지. 그룹 근거·검사 파일·정적 상태 추가. source+contract hash가 일치하는 4개 폭·핵심 동작 증거만 별도 판정에 연결 |
| P1_PATTERN | PASS(근거 있는 개선) | FilterBar `layout` opt-in으로 목록 기본/확장형 표현. 기본 동작 호환. Form/Empty/Error/Chart는 없는 API를 신설하지 않고 공개 Component composition으로 안내 |
| P2_AI_GUIDELINES | PASS | AGENTS 핵심 계약 → 기능 선택표 → 선택한 Pattern/Component 문서 순서. Native 콘텐츠 HTML 허용, Label 연결, Navigation 한 모드, 미요청 기능 금지, 결과 보고 구분 명시 |
| P3_STORYBOOK | PASS(선택한 Reference) | FilterBar All ID 유지, 실제 조회 적용/초기화·Label/useId·Do/Don't·layout 예제. 신규 업무 Story 등록 없음. 모든 Story를 재작성하지 않음 |
| P4_ACCESSIBILITY | PARTIAL | Clear 버튼 Enter 후 focus가 BODY로 손실되는 문제를 Chrome에서 재현·수정. 외부 ref/Label focus도 packed consumer에서 검증. Dialog/Sheet/Drawer/mobile focus 복귀, Form 오류 focus, Checkbox/Switch/readOnly 검증. 전체 WCAG·스크린리더는 NOT VERIFIED |
| P5_THEME_TOKEN | PASS(정적·테마 회귀 범위) | 연결 공개 CSS 목록 1,170개 선언 이름 inventory. Runtime override key 목록과 동일하다고 보지 않음. 새 Token/색/글꼴/간격 값 추가 없음. Theme Loader/Designer/실제 keyboard 검증 통과 |

## 주요 수정 파일

| 파일 | 변경 이유·내용 | 영향 범위 |
|---|---|---|
| `scripts/ai-generation-guard.mjs`, `guard-theme-analysis.mjs` | 미정의 Token 및 정적 판정의 근거 부족 → 연결 graph 검사·그룹 근거·hash·staticStatus | 기존 원본 status/exit/issues 유지; additive JSON schemaVersion 2 |
| `scripts/guard-evidence.mjs` | Runtime 근거를 원본 Guard와 구분하여 연결 | stale source/contract, 정적 FAIL/NV, 미확인 bootstrap을 PASS로 덮어쓰지 않음; PARTIAL scope 유지 |
| `packages/ui/src/patterns/filter-bar/filter-bar.tsx`, `src/theme/filter-bar.css`, `src/theme/dashboard-layout.css`, `src/index.ts` | 목록 구조 재사용·Clear focus 손실 | `layout` optional prop/공개 Props type, 기존 ref 전달 보존; default CSS 동작 유지 |
| `src/patterns/filter-bar.stories.tsx` | draft와 applied 조건·접근성·사용 기준 명확화 | 기존 All Story 유지, 선택적 목록 layout과 사용 예제 |
| `AGENTS.md`, `docs/guidelines/ai-screen-contract.md`, 관련 Guard/Pattern 문서 | 중복·암묵적 선택 기준 감소 | 문서 우선순위·API/상태/Native/Navigation 선택과 검증 계약 |
| `examples/ai-quality/**` | 신규 React 생성 결과로 실제 계약 검증 | 10개 독립 bootstrap, Storybook/운영 메뉴와 별개; 공통 composition 사용 |
| `scripts/verify-quality-*.mjs`, `audit-quality-contracts.mjs`, `summarize-quality-evidence.mjs` | 재현 가능한 브라우저·회귀·집계 | localhost와 로컬 evidence; Playwright/Chrome 경로는 환경 변수 필요 |

## 생성 실험

| ID | 화면 | 난이도 | Navigation | 필수 내용 Pattern |
|---|---|---|---|---|
| 01 | 사용자 목록 | Easy | GNB | FilterBar/DataTable |
| 02 | 현장 업무 카드 | Medium | GNB | FilterBar |
| 03 | 승인 결재 | Hard | GNB | FilterBar/DataTable + Dialog |
| 04 | 채용 관리 | Hard | GNB | FilterBar/DataTable + Sheet |
| 05 | 업무 요청 | Medium | GNB | 별도 Form API 없음; Label/Input/Textarea/Checkbox |
| 06 | 권한 설정 | Medium | LNB | Checkbox/Switch/readOnly Input |
| 07 | 업무 Dashboard | Medium | Dashboard | DashboardLayout/Tabs/Progress |
| 08 | 통계 Dashboard | Medium | Dashboard | DashboardLayout/DataTable 분류별 집계 |
| 09 | 작업 변경 | Hard | GNB | Drawer |
| 10 | 처리 상태 | Easy | LNB | Skeleton/Alert/빈 결과 composition |

SCREEN_COUNT: 10

MODEL: GPT-6(session identity), 같은 Codex 세션의 공유 composition. 이전 실험 소스를 정답 코드로 제공하지 않았다.

REASONING_LEVEL: UNAVAILABLE / RANDOM_SEED: UNAVAILABLE. 조건은 화면별 requirements.json에 보존. 독립 모델 실행·낮은 추론 재생성은 NOT VERIFIED.

TYPECHECK: PASS(strict, skipLibCheck:false) / BUILD: PASS / RUNTIME: PASS(10화면 × 4폭 = 40렌더, 핵심 동작 그룹 24/24).

AVERAGE_DESIGN_SCORE: NOT VERIFIED. 점수 rubric/독립 평가를 실행하지 않았다. 10개 화면 대표 캡처의 시각 확인은 수행했지만 점수로 환산하지 않았다.

COMPONENT_REUSE_RATE: 소스 JSX site 기준 100%(121 HM 공개 API site / 121 HM+native widget site, native widget 0). 공유 TSX를 한 번씩 계산, 콘텐츠/레이아웃 HTML 및 local composition wrapper 제외. 이 수치는 mounted DOM 비율이나 디자인 품질 점수가 아니다. 실제 HM slot 렌더는 10화면에서 확인했다.

PATTERN_REUSE_RATE: 요구된 내용 Pattern 10/10(100%)이 4개 폭 모두 실제 렌더. Navigation은 별도 모드 검사. Pattern이 없는 기능은 분모에서 제외하고 composition 이유를 기록했다.

GUARD_PASS: 원본 0 / 정적 계약 10 / Runtime 연결 판정 10

GUARD_FAIL: 원본 0 / 연결 0

GUARD_NOT_VERIFIED: 원본 10(RENDER-002) / 연결 0. 원본 issue를 삭제하지 않았다.

ACCESSIBILITY_ISSUES: 검사한 visible control 이름 누락·중복 ID·active tab 연결 오류 0; tested focus/keyboard 통과. 전체 접근성 문제 0을 의미하지 않는다.

UNREQUESTED_FEATURES: 정의한 허용 main 액션·단일 업무 메뉴 기준 0. 기본 공개 DataTable 페이지 기능/검색 clear/Overlay close는 Component 기본 기능이다. 의미적 전체 요구사항 평가는 NOT VERIFIED.

THEME_TOKEN: 새 화면의 연결 HM Token 위반 0, 실제 Theme/font/utilities 적용 확인. 임의 Chart·CSV·다운로드·외부 API·추가 운영 메뉴 없음.

## 회귀 검증

| 항목 | 최종 결과 |
|---|---|
| TYPECHECK | root/UI/CENTER/신규화면 PASS |
| UI_BUILD | UI/CENTER package build PASS |
| PRODUCTION_BUILD | root, Dashboard export+finalizer, Recruit, Publisher PASS |
| STORYBOOK_BUILD | PASS, 기존 292 ID → 292 ID(add/delete 0) |
| COMPONENT_TEST | 9/9 PASS, 기존 8개 test AST 본문 동일 |
| GUARD_TEST | 63/63 PASS, 기존 51개 test AST 본문 동일 |
| EVIDENCE_TEST / THEME_TEST | 5/5 / 3/3 PASS |
| GUARD_FULL_SCREEN | 기존 root NOT VERIFIED(CSS 의도 13+RENDER-002); FAIL 0 |
| GUARD_PARTIAL | root NOT VERIFIED(SCOPE-001: graph 밖 tailwind.css + RENDER-002); 신규01 static PASS/raw NV |
| GUARD_STORYBOOK | FULL NOT VERIFIED(wrapper1/CSS19/native33/computed token2); FAIL 0. FilterBar PARTIAL PASS |
| GUARD_GENERATED_SCREEN | raw 10 NV / static 10 PASS / 연결 10 PASS |
| CSS_IMPORTS | 연결 73개 누락 0 |
| EXPORTS | UI/CENTER 선언 export target 16개 누락 0 |
| DOC_LINKS | 96문서·429 내부 링크 PASS |
| THEME_JSON_LOADER | PASS(service primary #6837a8 → default #123328) |
| THEME_DESIGNER | 96 checks PASS |
| RUNTIME_THEME | 자동136/58 parts PASS, 실제 keyboard138 checks PASS(R3 보존) |
| PACKAGE_CONSUMER | npm pack 설치, 독립 엄격 TS·Vite build·public CSS·Label/ref/Clear focus PASS |
| GIT_CLONE_RUNTIME | --no-hardlinks clone, 자체 npm ci/typecheck/build; 01/08 각각4폭·검색/집계 PASS |
| RESPONSIVE | 신규40렌더, 기존 app/publisher/dashboard/recruit16렌더 PASS. Dashboard Header48/frame≥960·내부 scroll 확인 |

최초 실행에서 검사 harness의 Storybook bin 경로, test server `/themes/` 경로, 숨겨진 Radix input·중복 status locator 문제가 확인됐다. harness를 수정하고 영향받은 항목만 재검사했다. 실패 로그는 삭제하지 않았다. 최신 Loader/FilterBar·Storybook 결과가 초기 로그를 대체하는 근거다. 전체 검사를 동일 조건으로 반복하지 않았다.

## 보존 확인

D-01/D-02 및 PUBLISHER_ADDITIONAL: 확정 기준 문서 unchanged, 관련 기존 Component 테스트·Publisher/운영 브라우저 검증 PASS. 전체 문서 조항의 독립 수동 재인증은 NOT VERIFIED.

COMPONENT_API: 제거/이름 변경 없음; optional FilterBar layout/Props export만 추가. 기존 consumer ref도 검증.

THEME_TOKEN: default JSON·primitive/default/generated values·Tabs·Carousel TS/CSS 및 추가 요청 기준 9개 보호 파일 SHA256 일치. 기존 approved Theme 값과 미확정 항목을 변경하지 않음.

STORYBOOK_ID: 292개 보존 / EXISTING_TESTS: Guard51·Component8 AST 본문 보존.

## 증거·재현

Git 추적 요약은 같은 폴더 `ai-quality-improvement-2026-10-10.json`에 있다. 원본 결과·실패 시도·PNG는 gitignored `_local/quality-20261010`에 보존된다. 이전 실험/퍼블리셔 폴더는 읽기만 했다. 기존 증거 삭제·ZIP 배포 없음.

대표 최신 파일: `final-evidence.json`, `guard-01..10.json`, `runtime-01..10.json`, `combined-01..10.json`, `contract-audit.json`, `reference-runtime.json` + 후속 `reference-THEME_JSON_LOADER.json`/`reference-FILTERBAR_REFERENCE_USAGE.json`, `regression-*.json`, `consumer-runtime.json`, `clone-runtime/`, `clone-typecheck.log`, `clone-build.log`.

기본 재현 명령은 [실험 README](../../examples/ai-quality/README.md)와 [이전 준비 문서](../guidelines/gitea-source-transfer-preparation-2026-10-10.md)에 있다. aggregate는 per-screen 파일을 읽으므로 마지막 subset summary로 전체 성공 수를 대체하지 않는다. source 또는 Guard/Component 계약이 바뀌면 연결 판정은 stale이 된다.

## GitHub·이전 준비

PREVIOUS_HEAD: BASE_SHA와 동일. 구현 commit: `9ae2ab3`(Guard), `332c614`(FilterBar), `6034ac4`(10화면/검증), `cb451b3`(통계 집계).

COMMIT_SHA / REMOTE_HEAD / SHA_MATCH / WORKING_TREE / PUSH_RESULT: 제출 응답에서 최종 보고 commit을 포함한 일반 push와 실제 remote SHA 확인 결과를 기록한다. force push/reset/clean/remote 변경을 하지 않는다.

SOURCE_READY: 검증한 GitHub 소스·필수 파일/의존성/명령/위험을 [월요일 이전 준비](../guidelines/gitea-source-transfer-preparation-2026-10-10.md)에 정리했다. 이번에는 이전 실행 없음.

공식 Gitea: NOT ACCESSED / NOT MODIFIED. GitHub 연결 유지.

## 잔여 문제·최종 판단

연결 graph 기반 Token 감지, Pattern 표현/포커스 수정, 선택 지침과 실제 예제, 증거 연결·회귀 도구까지 구현했다. 기존 화면의 관측한 회귀는 0이다. 원본 Guard를 PASS로 만드는 것보다 판정 근거와 범위를 명확히 했다.

모델별 재현성·낮은 추론 신규 생성은 NOT VERIFIED. 기존 낮은 추론 3개 산출물의 Token 재검사만 수행했으며 새 cross-model 실험으로 보고하지 않는다. 공유 composition이므로 10개 독립 생성의 성공률로 일반화할 수 없다.

다음 우선순위는 같은 prompt/seed/모델별 독립 생성 및 실제 점수 rubric, 그 뒤 기존 전체 Storybook의 native/CSS intent 예외 검토·스크린리더/색 대비 검증이다. 과거 보고의 contrast 미충족/일부 clear icon 문제는 approved Theme를 임의 변경하지 않고 잔여 항목으로 유지한다. Combobox/DatePicker/Carousel/실기기 drag 전체 상태 재검증은 NOT VERIFIED.

Guard 한계: import/AST/CSS 선언 확인은 실제 cascade·미디어 활성 상태·모든 inline 변수 scope·실제 렌더 횟수를 보증하지 않는다. JS로 생성되는 동적 CSS/Token 및 의미적 미요청 기능은 별도 Runtime·사람 검토가 필요하다. Runtime evidence는 제공된 assertion이며 독립 보안 attestation이 아니다.

Started At: 2026-10-10 17:31:43 KST / Estimated Duration: 120~180분. Completed At·Actual Duration·Variance는 원격 확인이 끝난 제출 응답에 정확한 시각으로 기록한다.