ProofShot – AI 코딩 에이전트가 직접 만든 UI를 시각적으로 검증하는 CLI 도구

Who Should Read

Claude Code, Cursor, Copilot 같은 AI 코딩 에이전트를 써서 프론트엔드 기능을 개발하는데, 에이전트가 만든 UI가 실제로 잘 보이는지 매번 직접 확인해야 해서 번거로운 개발자. PR 리뷰에 시각적 증거를 첨부하고 싶은 팀에도 유용하다.

Core Mechanics

• AI 코딩 에이전트는 코드를 작성하지만 그 결과물이 브라우저에서 실제로 어떻게 보이는지, 콘솔 에러가 있는지 직접 확인할 수 없다. ProofShot은 이 '피드백 루프 부재' 문제를 해결하기 위해 만들어진 오픈소스 CLI다.
• 설치는 npm으로 전역 설치 후 `proofshot install` 한 번으로 끝난다. 이 명령어가 현재 설치된 AI 코딩 도구(Claude Code, Cursor, Codex, Gemini CLI, Windsurf, GitHub Copilot 등)를 자동 감지해서 사용자 레벨에 ProofShot 스킬을 설치하므로, 모든 프로젝트에서 별도 설정 없이 작동한다.
• 워크플로우는 start → test → stop 세 단계다. `proofshot start`로 개발 서버를 실행하면서 브라우저를 열고 녹화를 시작하면, 에이전트가 `agent-browser` 명령어로 브라우저를 직접 조작하고, 마지막으로 `proofshot stop`으로 결과물을 묶어준다.
• 결과물로는 영상 녹화, 주요 시점 스크린샷, 콘솔/서버 에러 리포트가 포함된다. 로컬에서 인터랙티브 뷰어(스크럽 바, 액션 마커, 타임라인 포함)로 확인하거나, `proofshot pr` 명령어로 GitHub PR에 인라인 코멘트로 자동 업로드할 수 있다.
• 특정 클라우드나 벤더에 의존하지 않는 구조다. 내부적으로 Vercel Labs의 agent-browser를 사용하지만, 오픈소스이고 로컬에서 Headless Chromium으로 실행된다. 일부 커뮤니티에서는 Vercel 의존성을 우려하는 목소리도 있었다.
• Playwright 같은 기존 테스트 도구와의 차이점이 중요하다. Playwright는 DOM 구조적 속성(엘리먼트 존재 여부, 가시성 등)을 검증하지만, ProofShot은 '실제로 화면이 의도한 대로 보이는가'를 사람이 판단할 수 있도록 시각 증거를 수집하는 데 초점을 맞춘다. 두 도구는 서로 다른 종류의 버그를 잡는다.
• 모바일 앱(iOS 시뮬레이터, Android 에뮬레이터) 지원에 대한 요구도 있었고, 데스크탑 앱처럼 DOM 접근이 불가능한 환경(예: 드로잉 앱)에서도 시각적 검증이 필요하다는 의견이 나왔다. 현재는 웹 브라우저 기반으로 동작한다.

Evidence

• Playwright와의 차이에 대한 토론이 활발했다. 한 댓글러는 'Playwright는 구조적 속성(DOM 엘리먼트 존재 여부 등)을 빠르고 확정적으로 검사하는 반면, 멀티모달 LLM으로 스크린샷을 디자인 목업과 비교하는 방식은 완전히 다른 종류의 에러(색상 틀림, 레이아웃 밀림, 간격 문제, 컴포넌트 겹침 등)를 잡는다'고 설명했다. DOM이 구조적으로 완벽해도 화면이 의도와 전혀 다를 수 있다는 점을 강조했다.
• 실제 사용 경험으로, 한 개발자는 Claude Code에 Playwright나 간단한 브라우저 접근 권한을 주면 에이전트가 직접 브라우저를 조작하면서 WebGL GLSL 셰이더 디버깅까지 할 수 있었다고 공유했다. 이미 유사한 워크플로우를 자체 구축해서 쓰고 있다는 사람들이 여럿 있었다.
• PR 리뷰 맥락에서의 활용 가능성도 언급됐다. 한 개발자는 회사에서 Claude Code를 GitLab 이슈/MR에 연동해서 작업 결과 스크린샷을 자동으로 남기고 있는데, ProofShot을 써서 열린 PR마다 에이전트가 체크아웃 후 탐색하고 결과 번들을 코멘트로 달게 하면 리뷰어에게 매우 유용할 것이라고 했다. '자동 코드 리뷰는 지치지만, 맥락 있는 시각적 코멘트는 다르다'는 관점이었다.
• 로컬 대안을 원하는 목소리도 있었다. playwright-cli를 같은 목적으로 쓰고 있다는 사람이, 영상 녹화 기능은 없지만 Vercel 같은 외부 의존성 없이 로컬에서 완전히 동작한다는 점을 장점으로 꼽았다. ProofShot도 로컬 솔루션을 대안으로 제공해달라는 요청을 남겼다.
• DOM이 없는 환경에서의 시각적 테스트 필요성을 강조한 흥미로운 댓글이 있었다. 드로잉 앱을 예시로 들면서, '사용자가 원을 그렸을 때 실제로 원이 화면에 보이는지' 확인하려면 도메인 모델이나 렌더러 호출 여부로는 부족하다(색상이 투명, 레이어 숨김, 트랜스폼 오류, 버퍼 스왑 실패 등 50가지가 잘못될 수 있음)고 설명했다. 이런 환경에서 ProofShot 같은 시각적 검증이 극히 가치 있다고 했다.

How to Apply

• Claude Code나 Cursor로 프론트엔드 기능을 개발하는 경우, `npm install -g proofshot && proofshot install` 로 설치한 뒤 CLAUDE.md(또는 에이전트 설정 파일)에 ProofShot 워크플로우를 추가하면, 에이전트가 기능 구현 후 자동으로 브라우저에서 동작을 확인하고 영상·스크린샷·에러 리포트를 생성한다. 개발자가 일일이 브라우저를 열어 확인하는 수고를 줄일 수 있다.
• 팀 PR 리뷰 프로세스를 개선하고 싶다면, CI/CD 파이프라인이나 에이전트 워크플로우에서 `proofshot pr` 명령어를 실행해 결과 번들을 GitHub PR 인라인 코멘트로 자동 첨부하도록 설정할 수 있다. 이렇게 하면 리뷰어가 코드만 보는 게 아니라 실제 UI 동작 영상과 에러 로그를 함께 보면서 리뷰할 수 있다.
• Playwright로 구조적 테스트(DOM 엘리먼트 존재, 텍스트 매칭 등)는 이미 하고 있지만 레이아웃 깨짐, 색상 오류, 컴포넌트 겹침 같은 시각적 버그를 놓치는 경우라면, ProofShot을 병행해서 사람이 영상·스크린샷으로 시각적 검수를 하는 레이어를 추가하는 방식이 적합하다. 두 도구는 잡는 버그 종류가 달라서 상호 보완된다.

Code Example

# 설치
npm install -g proofshot
proofshot install

# 1. 개발 서버 시작 + 브라우저 열기 + 녹화 시작
proofshot start --run "npm run dev" --port 3000 --description "Login form verification"

# 2. 에이전트가 브라우저 조작 (agent-browser 명령어)
agent-browser snapshot -i                        # 인터랙티브 요소 확인
agent-browser open http://localhost:3000/login   # 페이지 이동
agent-browser click "[data-testid=submit]"       # 클릭
agent-browser snapshot                           # 스크린샷 캡처

# 3. 녹화 종료 + 결과물 번들링
proofshot stop

# PR에 결과 업로드 (GitHub PR 인라인 코멘트로 자동 첨부)
proofshot pr

Terminology

Related Resources

• ProofShot GitHub 저장소 (원본)
• Vercel Labs agent-browser
• Microsoft playwright-cli
• Simon Willison의 유사 도구 (showboat, rodney)