Project Capture - AI 에이전트용 화면 캡처 자동화 스킬 정리

Project Capture - AI 에이전트용 화면 캡처 자동화 스킬

Project Capture - AI 에이전트용 화면 캡처 자동화 스킬 정리

AI 코딩 에이전트에게 "내 프로젝트 화면 전부 캡처해서 보여줘"라고 부탁해 본 적 있을 것이다. 라우트 목록을 사람이 일일이 적어주고, 로그인 처리 방법은 매번 다르게 시도하고, 캡처 범위와 뷰포트 크기를 결정해서 명령을 만들어야 한다. 매번 같은 반복 작업이 이어지는 셈이다.

이런 번거로움을 해결하기 위해 Kuneosu가 만든 오픈소스 도구가 Project Capture다. Codex 스킬 형태로 배포되지만, npm 패키지로도 설치할 수 있어서 Claude Code, Gemini CLI 같은 다른 AI 코딩 도구, 혹은 일반 터미널에서도 그대로 활용할 수 있다. 이번 글에서는 이 도구가 무엇을 하고 어떻게 쓰는지를 정리해 본다.

Project Capture란?

Project Capture는 AI 코딩 에이전트가 프로젝트를 먼저 분석한 뒤, 어떤 화면을 캡처할지 사용자에게 확인하고 Playwright로 스크린샷과 리포트를 생성하는 도구다. 단순한 자동 크롤러가 아니라 "프로젝트 분석 → 캡처 범위 확인 → 로그인 처리 → 화면 캡처 → 리포트 생성"의 흐름을 안정적으로 진행하도록 돕는 스킬에 가깝다.

완전 자동 크롤러가 아니라는 점을 강조한다. 동적 라우트, 인증이 필요한 화면, 역할별 화면, 기능 플래그로 가려진 UI 등은 사용자가 명시적으로 확인하거나 샘플 URL을 제공해야 한다. 이 점은 한계라기보다 설계 의도에 가깝다. 모든 가능한 상태를 자동 캡처한다는 환상을 주지 않겠다는립장이다.

주요 기능

• 프로젝트 구조 분석 및 라우트 후보 탐색 — Next.js, Remix, React Router, 일반 SPA 라우트 패턴을 지원한다.

• 캡처 범위 선택 — 전체 라우트, 핵심 도메인, 특정 도메인, 수동 지정 중 선택할 수 있다.

• 로그인 필요 여부 감지 — 수동 로그인, 환경변수 기반 로그인, 로그인 없는 캡처 중에서 선택 가능하다.

• 동적 라우트 처리 — 샘플 URL을 기반으로 처리한다.

• Playwright 화면 캡처 — 전체 스크롤 캡처(fullpage)와 특정 viewport 캡처 중 선택할 수 있다.

• 리포트 생성 — capture-report.md와 capture-results.json을 자동으로 생성한다.

설치 방법

가장 간단한 방법은 npx를 이용하는 것이다. 현재 프로젝트에 스킬을 설치하려면 아래 명령어를 실행한다.

npx project-capture init

이 명령은 스킬을 다음 두 디렉터리에 복사한다.

• .codex/skills/project-capture/

• .claude/skills/project-capture/

또한 기존에 있는 AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules 파일에 짧은 project-capture 안내를 추가한다. 해당 파일이 하나도 없으면 AGENTS.md를 새로 만든다.

특정 에이전트 디렉터리에만 설치하고 싶다면 --agent 옵션을 사용한다.

npx project-capture init --agent codexnpx project-capture init --agent claude

Codex에 전역 설치도 가능하다.

npx project-capture init --global-codex

사용 워크플로우

Codex 안에서 사용하는 전형적인 흐름은 다음과 같다.

1. Codex에게 "project-capture 사용해 줘" 또는 /capture라고 요청한다.

2. Codex가 프로젝트를 살펴보고 라우트 후보를 파악한다.

3. Codex가 캡처 범위를 묻는다.

4. 보호된 라우트가 감지되면 로그인 처리 방식을 묻는다.

5. 풀페이지 캡처인지 viewport 캡처인지 묻는다.

6. 선택한 화면을 캡처한다.

7. 생성된 리포트를 요약해 준다.

이 과정에서 Codex는 자동으로 사용자에게 확인을 받는다. 이 점이 핵심이다. 단순히 라우트를 다 캡처하는 게 아니라, 사용자의 의도를 반영하면서 진행한다.

캡처 범위 옵션

다섯 가지 범위 옵션이 있다.

• all — 발견된 모든 정적 라우트

• core — 홈, 로그인, 대시보드, 설정, 목록/상세/생성/수정 화면 등 핵심 제품 화면

• domain — /admin, /users, /settings 같은 특정 prefix 아래 라우트

• manual — 사용자가 직접 URL이나 경로 목록을 지정

• custom — 그 외 사용자가 정의한 조건

화면이 수십 개인 대규모 프로젝트라면 core부터 시작해서 필요한 화면을 manual로 추가해 가는 방식을 추천한다.

스크립트로 직접 사용하기

Codex 같은 에이전트 안이 아니라 일반 터미널에서도 사용할 수 있다. 라우트 탐색과 캡처가 별도 명령어로 분리되어 있어서 CI 파이프라인에도 끼워 넣기 쉽다.

라우트 탐색:

npx project-capture discover /path/to/project \--output output/playwright/project-capture-routes.json

핵심 라우트 캡처:

npx project-capture capture \--base-url http://localhost:3000 \--routes output/playwright/project-capture-routes.json \--scope core \--screenshot-mode viewport \--viewport 1440x900 \--output-dir output/playwright/project-capture

수동 로그인으로 캡처할 때는 --auth-mode manual과 --headed 옵션을 함께 쓴다.

npx project-capture capture \--base-url http://localhost:3000 \--routes output/playwright/project-capture-routes.json \--scope static \--auth-mode manual \--login-path /login \--headed \--output-dir output/playwright/project-capture

출력 구조

캡처가 끝나면 다음 구조로 결과물이 생성된다.

output/playwright/project-capture/├── screenshots/├── capture-report.md├── capture-results.json└── storage-state.json

여기서 storage-state.json에는 세션 정보가 들어 있을 수 있으므로 절대 커밋하지 말아야 한다. .gitignore에 추가하는 것을 잊지 말자.

로그인 처리 방식

보호된 라우트가 감지되면 세 가지 방식 중 하나를 선택한다.

• manual — 헤드드 브라우저를 띄워서 사용자가 직접 로그인한다. OAuth, SSO, WebAuthn, CAPTCHA, SMS OTP, 이메일 OTP 등 복잡한 인증 흐름에 적합하다.

• env — CAPTURE_USER, CAPTURE_PASSWORD 환경변수와 선택적 selector 변수를 사용한다.

• none — 공개 화면만 캡처한다.

운영 환경에서 캡처할 때는 manual 방식을 우선 권장한다. 환경변수 방식은 단순 폼 로그인에만 안전하게 쓸 수 있다.

다른 AI 에이전트와 함께 쓰기

이 저장소는 Codex 스킬로 패키징되어 있지만, 핵심 기능은 독립 스크립트로 구현되어 있다. 그래서 Claude Code, Gemini CLI, 자체 터미널 에이전트 등에서도 그대로 활용할 수 있다.

이런 에이전트에게는 다음과 같은 지시문을 주면 된다.

> 이 저장소를 프로젝트 화면 캡처 툴킷으로 사용해 줘. 먼저 scripts/discover_routes.py를 실행해서 대상 웹 프로젝트를 살펴보고, 후보 라우트를 요약한 다음, 캡처 범위를 물어보고, 보호된 라우트가 감지되면 로그인 방식을 물어봐 줘. 그다음 scripts/capture_pages.mjs를 Playwright로 실행해서 스크린샷과 리포트를 저장해 줘.

SKILL.md는 운영 가이드, references/는 정책 참고 자료, scripts/는 실행 가능한 구현으로 역할이 나뉘어 있다.

한계

모든 도구가 그렇듯 Project Capture도 만능은 아니다.

• 라우트 탐색은 최선의 정적 분석이다. 런타임에만 보이는 메뉴나 기능 플래그 화면은 발견되지 않을 수 있다.

• 동적 라우트는 샘플 값이 필요하다.

• 여러 역할이나 계정을 자동으로 순환하지 않는다.

• 시각적 회귀 테스트를 수행하지 않는다.

이런 한계들은 의도된 설계다. 자동화의 범위를 명확히 하고, 사용자가 명시적으로 확인해야 하는 지점을 분명히 한다.

정리

Project Capture는 AI 코딩 에이전트와 함께 쓰는 화면 캡처 자동화 도구다. Codex 스킬이지만 npm 패키지로도 설치할 수 있어서 다른 에이전트에서도 그대로 활용할 수 있다. 프로젝트 구조를 분석하고 라우트 후보를 찾아주며, 사용자에게 캡처 범위와 로그인 방식을 확인한 뒤 Playwright로 캡처하고 리포트를 만들어 준다. 모든 상태를 자동으로 캡처한다는 환상을 주지 않으면서, 반복 작업을 안정적으로 줄여 준다는 점이 매력적이다.

자신의 프로젝트 화면을 한 번에 정리해 보고 싶거나, AI 에이전트와 함께 UI 검증 흐름을 만들고 싶다면 한 번 써보길 권한다.

---

📚 출처

• https://news.hada.io/topic?id=30169