visual-qa-fix

스타0

포크0

업데이트2026년 3월 13일 17:05

Phase 3 — 스크린샷 기반 VQA 검수 + SSIM 비교 + 수정 (최대 3라운드)

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

출처

vp-k

vp-k/godot-craft

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Phase 3: Visual QA & Fix

개요

게임 실행 스크린샷을 캡처하고, VQA(Visual Question Answering)로 시각적 품질을 검수합니다. reference.png 대비 SSIM(구조적 유사도)도 측정합니다. 최대 3라운드 반복.

VQA 루프

반복 (최대 3회) {
    1. 스크린샷 캡처 (여러 장면)
    2. VQA 실행 (Gemini Flash)
    3. SSIM 비교 (reference.png vs 스크린샷)
    4. 리포트 분석 → 수정 계획
    5. 수정 실행
    6. compile-check
}

Step 1: 스크린샷 캡처

여러 게임 상태의 스크린샷을 캡처합니다:

# 메인 화면
bash ${CLAUDE_PLUGIN_ROOT}/tools/capture.sh screenshot --scene main --wait 2

# 게임플레이 (시간 경과)
bash ${CLAUDE_PLUGIN_ROOT}/tools/capture.sh screenshot --scene main --wait 5

# 특정 상태 (게임 오버, 메뉴 등)
bash ${CLAUDE_PLUGIN_ROOT}/tools/capture.sh screenshot --scene main --wait 10

Step 2: VQA 실행

python3 ${CLAUDE_PLUGIN_ROOT}/tools/visual_qa.py \
  --screenshots "screenshot_*.png" \
  --reference "reference.png" \
  --questions "게임이 시각적으로 올바르게 보이는가?,UI 요소가 올바른 위치에 있는가?,스프라이트가 정상적으로 렌더링되는가?"

VQA 결과: JSON 리포트

{
  "verdict": "fail|pass|acceptable",
  "issues": [
    {"severity": "high|medium|low", "description": "...", "suggestion": "..."}
  ],
  "score": 0.75
}

Step 3: SSIM 비교

python3 ${CLAUDE_PLUGIN_ROOT}/tools/screenshot_diff.py \
  --reference "reference.png" \
  --screenshot "screenshot_main.png"

SSIM ≥ 0.7 → acceptable, SSIM ≥ 0.85 → good

Step 4: 리포트 분석

VQA 리포트의 issues를 분석하여 수정 계획 수립:

high severity: 반드시 수정
medium severity: 가능하면 수정
low severity: 시간 허용 시 수정

Step 5: 수정 실행

godot-task 스킬 패턴으로 수정합니다.

Step 6: 라운드 기록

# progress에 VQA 라운드 기록 (jq로 직접)
# vqa.rounds에 {round, verdict, score, issues, fixes} 추가
# vqa.currentRound 증가

Step 7: VQA 게이트

bash ${CLAUDE_PLUGIN_ROOT}/scripts/godot-gate.sh vqa-gate

완료 조건

최소 1라운드 VQA 실행
verdict가 pass 또는 acceptable
vqa-gate 통과

이 저장소의 다른 Skills

같은 저장소

concept-planning

vp-k/godot-craft

Phase 0 — 게임 콘셉트 확장, 비주얼 타겟 생성, PLAN/STRUCTURE/ASSETS.md 작성, 사용자 승인

2026-03-290

godot-review

vp-k/godot-craft

완성된 Godot 게임을 UX 디자이너, 게임 디자이너, 기술 리뷰어(Godot 전문) 3관점으로 병렬 평가한다.

2026-03-290

godot-task

vp-k/godot-craft

단일 태스크 실행기 — GDScript 코드 작성, 씬 수정, 사운드 연결, Godot 4 함정 회피

2026-03-290

godot-testing

vp-k/godot-craft

Godot 게임 인터랙티브 테스트 — 입력 주입, 상태 검증, 스크린샷 캡처를 자동화하는 테스트 스킬

2026-03-290

scaffold-assets

vp-k/godot-craft

Phase 1 — 프로젝트 스캐폴딩 + 스크립트 스텁 + 씬 생성 + 에셋 생성 (이미지/사운드/음악)

2026-03-140

implementation

vp-k/godot-craft

Phase 2 — PLAN.md 태스크를 순서대로 구현. godot-task 스킬로 각 태스크 실행, compile-check + 스크린샷

2026-03-130

name	visual-qa-fix
description	Phase 3 — 스크린샷 기반 VQA 검수 + SSIM 비교 + 수정 (최대 3라운드)

Phase 3: Visual QA & Fix

개요

VQA 루프

반복 (최대 3회) {
    1. 스크린샷 캡처 (여러 장면)
    2. VQA 실행 (Gemini Flash)
    3. SSIM 비교 (reference.png vs 스크린샷)
    4. 리포트 분석 → 수정 계획
    5. 수정 실행
    6. compile-check
}

Step 1: 스크린샷 캡처

여러 게임 상태의 스크린샷을 캡처합니다:

# 메인 화면
bash ${CLAUDE_PLUGIN_ROOT}/tools/capture.sh screenshot --scene main --wait 2

# 게임플레이 (시간 경과)
bash ${CLAUDE_PLUGIN_ROOT}/tools/capture.sh screenshot --scene main --wait 5

# 특정 상태 (게임 오버, 메뉴 등)
bash ${CLAUDE_PLUGIN_ROOT}/tools/capture.sh screenshot --scene main --wait 10

Step 2: VQA 실행

python3 ${CLAUDE_PLUGIN_ROOT}/tools/visual_qa.py \
  --screenshots "screenshot_*.png" \
  --reference "reference.png" \
  --questions "게임이 시각적으로 올바르게 보이는가?,UI 요소가 올바른 위치에 있는가?,스프라이트가 정상적으로 렌더링되는가?"

VQA 결과: JSON 리포트

{
  "verdict": "fail|pass|acceptable",
  "issues": [
    {"severity": "high|medium|low", "description": "...", "suggestion": "..."}
  ],
  "score": 0.75
}

Step 3: SSIM 비교

python3 ${CLAUDE_PLUGIN_ROOT}/tools/screenshot_diff.py \
  --reference "reference.png" \
  --screenshot "screenshot_main.png"

SSIM ≥ 0.7 → acceptable, SSIM ≥ 0.85 → good

Step 4: 리포트 분석

VQA 리포트의 issues를 분석하여 수정 계획 수립:

high severity: 반드시 수정
medium severity: 가능하면 수정
low severity: 시간 허용 시 수정

Step 5: 수정 실행

godot-task 스킬 패턴으로 수정합니다.

Step 6: 라운드 기록

# progress에 VQA 라운드 기록 (jq로 직접)
# vqa.rounds에 {round, verdict, score, issues, fixes} 추가
# vqa.currentRound 증가

Step 7: VQA 게이트

bash ${CLAUDE_PLUGIN_ROOT}/scripts/godot-gate.sh vqa-gate

완료 조건

최소 1라운드 VQA 실행
verdict가 pass 또는 acceptable
vqa-gate 통과