shot-scraper video를 사용하여 에이전트가 작업 결과의 비디오 데모를 기록하게 하세요

2026년 6월 30일

shot-scraper video는 오늘 출시된 shot-scraper 1.10 릴리스에 도입된 새로운 명령어로, 웹 애플리케이션에 대해 실행할 루틴을 정의하는 storyboard.yml 파일을 수용하며 Playwright를 사용하여 해당 루틴의 비디오를 기록합니다. 저는 이전에도 코딩 에이전트(coding agents)가 자신의 작업에 대한 데모를 생성하는 것이 얼마나 중요한지에 대해 글을 쓴 적이 있습니다. 이것은 에이전트가 그 작업을 수행할 수 있도록 하는 저의 최신 시도입니다.

다음은 shot-scraper video를 사용하여 생성된 예시 비디오입니다. 이 비디오는 붙여넣은 CSV, TSV 또는 JSON 데이터로부터 Datasette에 새로운 테이블을 생성하는 기능을 추가하는, 현재 개발 중인 기능을 테스트하는 모습을 담고 있습니다:

[IMG:1]

해당 비디오는 다음 명령어를 실행하여 생성되었습니다:

shot-scraper video datasette-bulk-insert-storyboard.yml \
--auth datasette-demo-auth.json --mp4

(해당 --auth JSON 파일에는 문서에 설명된 대로 쿠키가 포함되어 있습니다.)

다음은 datasette-bulk-insert-storyboard.yml 파일입니다:

output: /tmp/datasette-bulk-insert-demo.webm
server:
- uv
...

비디오 명령어 문서에는 더 간단한 예시들이 포함되어 있지만, 이 포스트의 목적을 위해 저는 좀 더 포괄적인 예시를 사용하기로 했습니다.

해당 데모 YAML 스토리보드는 Codex Desktop에서 실행되는 GPT-5.5 xhigh에 의해 전적으로 구성되었습니다. 이 과정에서 제 ~/dev/datasette 체크아웃 브랜치 내부에서 다음과 같은 프롬프트를 사용했습니다:

Review the changes on this branch.

cd to ~/dev/shot-scraper and run the command "uv run shot-scraper video --help"

Now use that new video command to record a video demo of the new features from this branch, including running a "uv run datasette -p 6419 --root --secret 1 /tmp/demo.db" development server so you can record the video against a demo DB that you first create.

이제 제가 이 기능을 출시했으므로, 프롬프트는 대신 run uvx shot-scraper video --help라고 말할 수 있으며 동일한 결과를 달성할 것입니다.

저는 --help를 사용하는 이 패턴이 정말 마음에 듭니다.

명령어의 출력 결과가 코딩 에이전트(coding agent)가 사용할 수 있을 만큼 충분한 세부 정보를 제공한다는 점입니다. 이는 마치 도구 내부에 SKILL.md 파일을 직접 묶어 넣는 것과 비슷하게 작동합니다. 저는 showboat와 rodney에서도 동일한 패턴을 사용했습니다.

제작 과정

shot-scraper video는 실험적인 프로토타입(prototype)으로 시작되었습니다. shot-scraper는 Playwright를 기반으로 구축되었으며, 핵심적으로 필요했던 기능은 Playwright가 원하는 데모를 생성할 수 있을 만큼 충분한 제어력을 가지고 브라우저 세션의 비디오를 녹화할 수 있는 것이었습니다.

몇 년 전 처음 이 시도를 했을 때는 Playwright가 생성하는 비디오에 테스트 실패 디버깅에는 유용하지만 제품 데모에는 불필요한 추가적인 크롬(chrome) 요소들이 포함되어 있다는 것을 발견했습니다.

그들은 얼마 전 그 문제를 해결했지만, 여전히 몇 가지 사소한 장애물이 있었습니다. 특히 브라우저에 첫 번째 URL이 로드되기 전에 녹화 메커니즘이 작동하기 때문에 비디오 시작 부분에 몇 개의 흰색 프레임이 나타나는 문제가 있었습니다.

Playwright 1.59 버전에서 비디오 녹화에 대해 훨씬 더 세밀한 제어(finely grained control)를 제공하는 새로운 스크린캐스트(screencast) 메커니즘이 추가되었습니다. 이는 제가 필요로 했던 것에 거의 근접했지만, 결과물인 비디오의 너비가 800px로 고정되어 있었습니다.

해당 문제를 해결하는 PR(Pull Request)이 머지된 것을 발견했지만 아직 릴리스(release)되지는 않은 상태였습니다. 그러다 어제 playwright-python 1.61.0에 해당 기능이 배포되었고, 마침내 장애물이 제거되어 기능 구현을 완료할 수 있었습니다!

코드 자체는 모두 Codex Desktop의 GPT-5.5 xhigh가 작성했습니다. 저는 문서화(documentation) 작업도 맡겼는데, 이는 설계를 검토하는 데 매우 유용한 틀을 제공해 주었습니다. 기능에 대한 많은 반복 작업(iteration)은 해당 문서를 검토하면서 중복되거나, 일관성이 없거나, 혼란스러운 부분을 찾아내고 더 나은 설계를 요청(또는 지시)하는 과정에서 이루어졌습니다.

YAML 형식 자체도 대부분 코딩 에이전트가 정의했습니다. 설계를 더 쉽게 검토할 수 있도록 하기 위한 목적도 겸하여, Pydantic을 사용하여 형식을 정의하고 검증(validate)하도록 했습니다.

이는 코딩 에이전트 (coding agent)의 지원 없이는 거의 확실히 시도하지 않았을 기능의 아주 좋은 사례입니다. 저는 2024년 2월에 원래의 이슈 (issue)를 등록했지만, 다른 모든 프로젝트들 사이에서 이를 해결하는 데 필요한 시간을 확보하는 데 어려움을 겪었습니다.