design-qa

design-qa — 오버레이 검증 루프

codegen의 "LLM 눈대중 대조"를 실기기/시뮬레이터 런타임에서 수치로 수행하는 보완 트랙이다. JVM (layoutlib) 정량 트랙과 달리 실 렌더엔진·다크모드·디바이스 density가 그대로 반영된다 — 둘은 경쟁이 아니라 병행이다.

비교·측정 엔진(overlay·align_probe·glyph_probe·edge_probe·enumerate_regions)과 crop 의 auto/box/ anchor/정합 게이트는 플랫폼 중립이다. 플랫폼에 종속되는 건 뷰포트 정규화(0단계)와 캡처, dumpsys frame crop, "고치는 법(코드 어휘)"뿐이다. 그래서 이 문서는 루프·판정·종료 계약을 중립으로 기술하고, 플랫폼별 명령·보정 어휘는 references/<platform>.md로 분리한다(android.md, ios.md, web.md).

두 진입 — 빌드·진입·캡처는 공유

목표는 인간 개입 최소화 자율 검증이다. 빌드·화면 진입·캡처는 진입과 무관하게 design-qa가 스스로 한다. 두 진입은 앞단 입력을 어떻게 얻느냐만 다르다.

• 위임 진입 (codegen Step 7c): file_key·node_id·crop 인자 + 빌드/실행 정보가 넘어옴 → 0단계 건너뛰고 "빌드·화면 진입"부터 자율 수행.
• 직접 진입 (/design-qa <프롬프트>): 입력이 자연어뿐 → 0단계(입력 해소)로 모드·링크를 먼저 정한 뒤 합류.

0단계 — 입력 해소 (직접 진입 전용)

0a. 모드 판별. 기본값은 보정 모드(자율 루프).

• 인자 없는 /design-qa 또는 애매한 프롬프트 → 보정 모드: 검증→보정→재빌드→최종 오버레이까지 묻지 않고 자동.
• 오차 서술("틀렸/밀렸/색이/폰트/위치/간격/크기가 …")이 있으면 → 보정 모드, 그 영역 우선 조준.
• "오버레이만/겹쳐봐/확인만" 신호가 명시되면 → 검증 모드(blend-only 표시, 코드 미수정).

0b. Figma 링크 해소. ① 프롬프트의 URL → ② 없으면 세션 직전 링크 재사용 → ③ 둘 다 없을 때만 요청. 확보한 URL의 file_key·node_id를 추출하고 세션에 유지해 후속 호출이 ②로 재사용하게 한다.

빌드·화면 진입 (양 진입 공유, 자율)

• 빌드: 타겟 앱을 지금 체크아웃된 브랜치 그대로 빌드한다(보정 루프의 코드 수정도 현재 트리에 적용 후 재빌드).
• 화면 진입 + 캡처 fallback (인간 개입은 최후수단): 대상 화면 포그라운드 진입을 자동 시도한다. 자율 진입이 끝까지 막힐 때(프로젝트 의존 로그인 등)에만 안내 후 사용자 신호를 받아 캡처한다 — 성공하면 신호 없이 진행.

산출물 위치(outdir) — 기본은 Desktop. 기본 outdir는 $HOME/Desktop/design-qa/{검수화면}/(예: $HOME/Desktop/design-qa/날씨-엔드/)이고, 캡처·크롭 중간물도 같은 디렉터리에 둔다. {검수화면}은 node id가 아니라 사람이 알아보는 화면 이름(figma 프레임명 등, 공백은 -)으로 쓴다 — Desktop에 폴더가 쌓였을 때 어느 검수 결과인지 이름만으로 구분돼야 한다. 이 루프의 마지막 동작이 "사람이 이미지를 눈으로 확인"이라서 산출물은 Finder에서 바로 열리는 자리에 있어야 한다 — /tmp는 사용자가 찾아가기 어렵고 정리·재부팅으로 사라진다. 사용자가 경로를 명시하면 그 경로를 따른다.

마무리는 호출 종류로 갈린다:

• 직접/자율 호출: 수렴 후 outdir를 blend50.png 한 장만 남기고 정리 → open으로 띄우고 종료. 사람은 이미지 한 장만 본다.
• 위임 보정: full rubric 산출물 + OVERLAY-REPORT.md를 유지(위임자가 코드 오차 리스트·리포트 경로를 소비). open 불필요.