| name | ui-visual-review |
| description | Captures screenshots of key UI flows after E2E tests pass, runs an agent-side first-pass diff (regressions, console errors, layout shifts), then surfaces a checklist for the user's final approval. Use after E2E tests pass on a UI track (csr-*, ssr-*, full). Adapts the GoalTrack screenshot-review pattern into a repeatable workflow. |
UI Visual Review
Purpose
E2E 테스트가 PASS 했어도 시각적 회귀(layout shift, 색상/간격 변화, 빈 화면, 잘림)는 functional test가 못 잡는다. 본 skill은:
- 핵심 사용자 화면을 자동 캡처
- 이전 baseline과 diff
- 에이전트가 명백한 regression 1차 판정
- 사용자가 최종 승인 → 새 baseline 채택 또는 수정 요청
GoalTrack의 docs/screenshots/ 수동 패턴(mvp-home / v3-search / v4-wiki 등)을 자동화한 형태.
When to Invoke
| 트리거 | 행동 |
|---|
| E2E 테스트 PASS + UI Track(csr-/ssr-/full) | 본 skill 호출 권유 |
| UI 변경 PR review | visual diff 결과 review 입력으로 |
| 의도적 디자인 변경 후 baseline 갱신 | "approve all" 옵션 |
| Track이 data/tooling/executive | skip — UI 없음 |
Pre-conditions
- Playwright 또는 chrome-devtools MCP 사용 가능 (UI Track 설치 시 기본 포함)
- 앱이 로컬에서 기동 가능 (예:
pnpm dev, docker-compose up)
- 핵심 화면 URL 리스트가 정의됨 (없으면 본 skill 첫 실행 시 사용자 질의)
Process
1. 화면 리스트업 (한 번만)
docs/visual-pages.json 부재 시 사용자에게 핵심 화면을 묻는다 (5-10개 권장):
{
"base_url": "http://localhost:3000",
"pages": [
{ "id": "login", "path": "/login", "wait_for": "form" },
{ "id": "home", "path": "/", "wait_for": "main", "auth": "user1" },
{ "id": "detail", "path": "/items/sample", "auth": "user1" },
{ "id": "settings", "path": "/settings", "auth": "user1" }
],
"viewports": [
{ "name": "desktop", "width": 1440, "height": 900 },
{ "name": "mobile", "width": 375, "height": 812 }
]
}
auth 키는 docs/visual-auth.example.json(별도 시크릿)에서 매핑.
2. 캡처
각 page × viewport 조합으로 스크린샷 캡처. chrome-devtools MCP 사용 예:
for page in pages:
navigate_page({url: base_url + page.path})
wait_for({text: page.wait_for})
take_screenshot({fullPage: true})
→ 저장: docs/screenshots/<branch-or-date>/<page.id>__<viewport.name>.png
저장 경로 규칙: docs/screenshots/<phase>/<page_id>__<viewport>.png. phase는 git branch 이름 또는 YYYY-MM-DD-HHmm.
3. Diff (baseline 대비)
baseline 위치: docs/screenshots/baseline/. 첫 실행이면 현재 캡처가 baseline.
비교 방식 (간단 → 정밀 순):
- L1 (해시):
sha256 비교. 같으면 PASS, 다르면 L2.
- L2 (pixelmatch):
pixelmatch 또는 ImageMagick compare -metric AE. threshold(예: 0.5%) 이내 PASS.
- L3 (시각 검토): L2 fail 시 에이전트가 두 이미지를 LLM 입력으로 보고 차이 서술.
L1만 구현해도 50% 가치. L2는 의존성 추가.
4. 에이전트 1차 리뷰 (자동)
L2/L3 fail이거나 차이가 임계 이상이면 에이전트가 다음 휴리스틱으로 명백한 regression 판정:
| 시그널 | 분류 |
|---|
| 빈 화면 / 흰 페이지 | REGRESSION |
콘솔 에러 (chrome-devtools list_console_messages) | REGRESSION |
| 핵심 컴포넌트(navbar, main content) 누락 | REGRESSION |
| 색상/간격 미세 변화 | CHANGED (사용자 판단) |
| 의도된 카피/레이아웃 변경 | EXPECTED (커밋 메시지 매칭) |
5. 결과 보고
docs/visual-review-<phase>.md 생성:
# Visual Review — 2026-04-20
## Summary
- 8 pages × 2 viewports = 16 captures
- PASS (no diff): 12
- CHANGED (review needed): 3
- REGRESSION: 1
## REGRESSION
- `home__desktop`: 콘솔 에러 "Cannot read properties of undefined" + main 영역 빈 화면
## CHANGED
- `login__mobile`: 버튼 색상 변경 (의도 추정 — git diff에 button.primary 수정 발견)
- `settings__desktop`: spacing 변화
## PASS
- (생략)
6. 사용자 승인 게이트
사용자가 docs/visual-review-<phase>.md 보고 다음 중 결정:
- REGRESSION 있음 → 수정 후 재실행 (Revision Gate)
- CHANGED만 있음 → 항목별 approve 또는 reject. approve 시 baseline 업데이트
- PASS만 있음 → 자동 baseline 업데이트 가능
Output
docs/screenshots/<phase>/*.png — 캡처본docs/screenshots/baseline/*.png — 승인된 baselinedocs/visual-review-<phase>.md — diff 리포트
Integration with Workflow
- E2E 테스트 후: UI Track +
docs/visual-pages.json 존재 시 PASS 후 본 skill 자동 호출 권유
- Review 시: visual-review-.md 가 있으면 review 입력으로 흡수. REGRESSION 1건이라도 있으면 차단
- Revision loop 중: REGRESSION → 수정 → 재캡처 → 재diff 로 포함
Anti-Patterns
- 사용자 승인 없이 baseline 자동 갱신 — 의도하지 않은 regression이 영구화. 항상 명시적 approve 필요
- 모든 페이지 다 캡처 (50+) — 노이즈 폭증. 핵심 5-10개로 시작
- viewport 1개만 — mobile 깨짐 놓침. desktop + mobile 최소 2개
- L3(LLM 시각 비교) 매번 호출 — 비용. L1/L2에서 못 거른 것만 L3
- screenshots/ 디렉토리 git에 커밋 X — 회귀 비교 불가.
docs/screenshots/baseline/은 커밋, <phase>/는 gitignore
Examples
GoalTrack 프로젝트의 수동 패턴 (참고):
docs/screenshots/mvp-home-empty.png, mvp-home-list.png — 같은 화면 다른 상태crypto-365d-after-fix.png, crypto-365d-round2.png — 수정 round별 보존shared_portfolio.png, shared_simulation.png — 기능별 핵심 화면
본 skill은 그 패턴을 자동화 + diff + 에이전트 사전 판정 추가.
