에이전트가 만든 결과물을 직접 시연할 수 있도록 — Showboat와 Rodney 소개

• 코드가 실제로 동작한다는 것을 증명하기
• Showboat: 에이전트가 작업 결과를 문서로 시연한다
• Rodney: Showboat와 함께 쓰도록 설계된 CLI 브라우저 자동화 도구
• 테스트 주도 개발이 도움이 되지만, 수동 테스트는 여전히 필요하다
• 이 도구 두 가지, 모두 휴대폰으로 만들었다

코드가 실제로 동작한다는 것을 증명하기

얼마 전, 소프트웨어 엔지니어의 본업은 코드를 작성하는 것이 아니라 실제로 동작하는 코드를 납품하는 것이라는 글을 썼다. 그 핵심에는 자신이 책임지는 코드가 의도대로 동작한다는 사실을 스스로, 그리고 다른 사람들에게 증명하는 과정이 있다.

코딩 에이전트를 소프트웨어 개발 프로세스의 중심에 두게 되면서, 이 문제는 더욱 중요해지는 동시에 더 까다로워졌다.

에이전트와 함께 더 많은 코드를 쏟아낼수록, 수동 QA에 쏟는 시간을 줄여주는 도구의 가치는 더 높아진다.

StrongDM의 소프트웨어 팩토리 모델에서 특히 흥미로웠던 점은, "코드를 사람이 리뷰해서는 안 된다"는 정책을 유지하면서도 소프트웨어를 탄탄하게 테스트하고 실질적인 가치를 만들어내는 방식이다. 그 해법 중 하나는 다양한 "시나리오"를 실행하며 소프트웨어를 검증하는 QA 에이전트 군집을 운용하는 것인데, 비용이 상당히 든다. 발상 자체는 매력적이지만, 굳이 그렇게 하지 않아도 된다면 QA 로봇에 수천 달러를 쓰고 싶지는 않다.

에이전트가 자신이 한 작업을 명확하게 보여줄 수 있는 도구가 필요하다. 동시에, 에이전트가 실제로 하지 않은 일을 한 것처럼 속일 수 있는 여지는 최대한 줄여야 한다.

Showboat: 에이전트가 작업 결과를 문서로 시연한다

Showboat는 에이전트가 작업 결과를 나에게 시연할 수 있도록 만든 도구다.

Go 바이너리로 제공되는 CLI 도구로, 설치 편의를 위해 Python으로 래핑한 버전도 있다. 에이전트가 새로 개발한 코드의 기능을 설명하는 마크다운 문서를 단계별로 구성하는 데 쓰인다.

사람이 직접 실행하도록 설계된 도구는 아니지만, 굳이 실행한다면 이렇게 하면 된다:

showboat init demo.md 'How to use curl and jq'
showboat note demo.md "Here's how to use curl and jq together."
showboat exec demo.md bash 'curl -s https://api.github.com/repos/simonw/rodney | jq .description'
showboat note demo.md 'And the curl logo, to demonstrate the image command:'
showboat image demo.md 'curl -o curl-logo.png https://curl.se/logo/curl-logo.png && echo curl-logo.png'

VS Code에서 열어 마크다운 미리보기를 켜면 결과가 이렇게 보인다:

Gist에서 demo.md 파일을 확인할 수 있다.

showboat init, showboat note, showboat exec, showboat image 명령어를 순서대로 실행하면 마크다운 문서가 섹션 단위로 완성된다. 각 exec 명령어의 출력은 해당 명령어 바로 다음에 자동으로 문서에 삽입된다.

image 명령어는 조금 특별하다. 명령어 출력에서 이미지 파일 경로를 찾아 해당 이미지를 현재 폴더에 복사한 뒤, 문서에 이미지 참조를 추가한다.

기능은 이게 전부다. 뭔가 잘못됐을 때 가장 최근에 추가된 섹션을 제거하는 pop 명령어, 문서를 재실행해서 변경 사항이 없는지 확인하는 verify 명령어(이 부분의 설계가 완전히 마음에 들진 않는다), 그리고 문서를 만드는 데 사용된 CLI 명령어들을 역으로 추출하는 extract 명령어가 있다.

코드는 172줄의 Go로 작성됐다. 꽤 단순하다.

go-to-wheel 도구로 패키징했기 때문에, 별도 설치 없이 바로 실행할 수 있다:

uvx showboat --help

--help 명령어는 특히 중요하다. 코딩 에이전트가 이 도구를 사용하는 데 필요한 모든 정보를 한 번에 제공하도록 설계됐다. 전체 도움말 텍스트는 여기서 확인할 수 있다.

Claude Code를 열고 이렇게 입력하면 된다:

Run "uvx showboat --help" and then use showboat to create a demo.md document describing the feature you just built

그게 전부다. --help 텍스트는 일종의 스킬(Skill)처럼 작동한다. 에이전트가 도움말 텍스트를 읽고 Showboat의 모든 기능을 활용해, 시연이 필요한 내용을 담은 문서를 직접 만들어낸다.

유용한 활용 팁이 있다. Claude에 Showboat 문서 작성을 맡긴 뒤 VS Code에서 해당 파일을 열어두면, 에이전트가 시연을 진행하는 동안 미리보기 창이 실시간으로 업데이트된다. 마치 동료가 화면 공유를 켜고 자신의 최근 작업을 직접 설명해주는 것 같은 느낌이다.

마지막으로 몇 가지 예시를 소개한다. 다른 프로젝트에서 기능을 개발할 때 Claude에게 Showboat를 이용해 작성하게 한 시연 문서들이다:

• shot-scraper: A Comprehensive Demo는 내 shot-scraper 브라우저 자동화 도구의 전체 기능을 훑어보는 문서로, 주로 showboat image 명령어를 다양하게 실행해보기 위해 만들었다.
• sqlite-history-json CLI demo는 새로 만든 sqlite-history-json Python 라이브러리에 추가한 CLI 기능을 시연한다.

  • row-state-sql CLI Demo는 같은 프로젝트에 새로 추가한 row-state-sql 명령어를 보여준다.

  • Change grouping with Notes는 동일한 트랜잭션 내 변경 묶음에 메모를 첨부할 수 있는 기능을 시연한다.

• krunsh: Pipe Shell Commands to an Ephemeral libkrun MicroVM은 특히 복잡한 사례로, Claude Code 웹 버전을 이용해 Claude의 gVisor 샌드박스 안에서 QEMU로 에뮬레이션한 Linux 환경 위에 libkrun 마이크로VM을 실행하는 데 성공했다.

Showboat를 충분히 써보면서 그 유용성을 직접 확인했다.

(에이전트가 속임수를 쓰는 장면도 목격했다! 시연 파일이 마크다운이다 보니, 에이전트가 Showboat를 거치지 않고 파일을 직접 편집하는 경우가 있었다. 이렇게 되면 실제로 실행된 결과가 아닌 내용이 문서에 기록될 수 있다. 관련 이슈에서 이 문제를 다루고 있다.)

Rodney: Showboat와 함께 쓰도록 설계된 CLI 브라우저 자동화 도구

내가 작업하는 프로젝트 상당수는 웹 인터페이스를 포함한다. 에이전트가 완전히 새로운 페이지를 만들어내는 경우도 많은데, 그 결과물도 시연 문서에 담기를 원했다.

Showboat의 이미지 기능은 처음부터 에이전트가 시연 과정에서 스크린샷을 캡처할 수 있도록 설계됐으며, 초기에는 내가 만든 shot-scraper나 Playwright를 활용했다.

Showboat의 형식은 CLI 유틸리티와 잘 맞는다. 여러 단계로 이어지는 브라우저 세션을 CLI에서 관리할 수 있는 도구를 찾아봤지만 마땅한 것이 없어서, 직접 만들어보기로 했다.

Claude Opus 4.6이 Chrome DevTools 프로토콜을 다루는 Go 라이브러리인 Rod를 소개해줬다. 훌륭한 라이브러리다. Chrome 자동화로 할 수 있는 거의 모든 기능을 포괄하는 래퍼를 제공하며, 몇 MB 크기의 단일 라이브러리로 컴파일된다.

Rod에 없는 것은 CLI뿐이었다.

처음에는 비동기 리포트 프로토타입으로 첫 버전을 만들었는데, 독립 프로젝트로 분리할 만한 가치가 있다는 확신이 생겼다.

이름은 기반이 된 Rod 라이브러리에 대한 오마주이자 Only Fools and Horses에 대한 헌사로 Rodney라고 지었다. PyPI에서 패키지명도 비어 있었다.

uvx rodney로 바로 실행하거나, 다음과 같이 설치할 수 있다:

uv tool install rodney

(Go 바이너리는 릴리스 페이지에서 받을 수 있다.)

간단한 사용 예시는 다음과 같다:

rodney start # starts Chrome in the background
rodney open https://datasette.io/
rodney js 'Array.from(document.links).map(el => el.href).slice(0, 5)'
rodney click 'a[href="https://simonwillison.net/for"]'
rodney js location.href
rodney js document.title
rodney screenshot datasette-for-page.png
rodney stop

터미널에서 실행하면 이렇게 보인다:

Showboat와 마찬가지로, 이 도구도 사람이 직접 사용하도록 만든 것이 아니다. 코딩 에이전트가 rodney --help를 실행해 도구 사용에 필요한 모든 정보를 한 번에 파악하는 것이 목표다. 도움말 출력 내용은 GitHub 저장소에서 확인할 수 있다.

Showboat로 만든 Rodney 시연 문서 세 가지를 소개한다:

• Rodney의 기본 기능 세트: 페이지 스크린샷 촬영과 JavaScript 실행 등 초기 기능을 담고 있다.
• Rodney의 새로운 접근성 테스트 기능: 해당 기능 개발 과정에서 만든 문서로, 어떤 것들이 가능한지 보여준다.
• 이 기능들을 활용한 기본 접근성 감사. "showboat와 rodney를 사용해서 https://latest.datasette.io/fixtures의 접근성 감사를 수행해줘"라는 프롬프트에 Claude Opus 4.6이 얼마나 잘 반응하는지 인상적이었다. 대화 내용은 여기서 확인할 수 있다.

테스트 주도 개발이 도움이 되지만, 수동 테스트는 여전히 필요하다

오랫동안 테스트 우선, 최대 커버리지를 추구하는 소프트웨어 개발 방식에 회의적이었다(나는 테스트 포함 개발 방식을 선호한다). 그런데 최근에는 에이전트가 문제 해결에 꼭 필요한 코드만 작성하도록 유도하는 수단으로서 테스트 우선 방식의 효용을 새롭게 보게 됐다.

Python 코딩 에이전트 세션을 시작할 때 나는 보통 이렇게 한다:

Run the existing tests with "uv run pytest". Build using red/green TDD.

에이전트에게 테스트 실행 방법을 알려주면, 이 프로젝트에 테스트가 존재하며 중요하다는 신호도 함께 전달된다. 에이전트는 자신의 테스트를 작성하기 전에 기존 테스트를 먼저 읽기 때문에, 잘 정리된 테스트 스위트와 좋은 패턴이 있으면 에이전트도 그 흐름에 맞춰 좋은 테스트를 작성할 가능성이 높아진다.

최신 프런티어 모델들은 모두 "red/green TDD"의 의미를 이해한다. 테스트를 먼저 작성하고, 실행해서 실패를 확인한 뒤, 테스트를 통과시키는 코드를 작성하는 흐름이다. 이걸 그대로 쓸 수 있는 편리한 단축 표현이다.

이 방식을 쓰면 코드 품질이 크게 향상되고, 최소한의 프롬프트로 에이전트가 올바른 결과물을 만들어낼 가능성도 높아진다.

하지만 테스트를 다뤄본 사람이라면 알겠지만, 자동화 테스트가 통과한다고 해서 소프트웨어가 실제로 제대로 동작한다는 보장은 없다. Showboat와 Rodney를 만든 이유도 여기에 있다. 직접 눈으로 동작을 확인하기 전까지는 어떤 기능도 믿지 않는다.

Showboat를 만들기 전에는 에이전트 세션에 "수동" 테스트 단계를 직접 추가하곤 했다. 예를 들면 이런 식이다:

Once the tests pass, start a development server and exercise the new feature using curl

이 도구 두 가지, 모두 휴대폰으로 만들었다

Showboat와 Rodney는 모두 iPhone 앱을 통한 Claude Code 웹 버전에서 시작됐다. 이후 기능 개발 대부분도 같은 방식으로 이뤄졌다.

요즘 내가 휴대폰으로 이렇게 많은 코딩 작업을 처리한다는 사실이 아직도 놀랍지만, 요즘 GitHub에 올리는 코드의 대부분은 그 iPhone 앱으로 구동한 코딩 에이전트가 작성한 것이라고 해도 과언이 아니다.

이 두 도구는 처음부터 Claude Code 웹 버전 같은 비동기 코딩 에이전트 환경을 염두에 두고 설계했다. 지금까지는 기대 이상으로 잘 작동하고 있다.

이 글은 제 블로그의 장문 아티클만 모아 보여드리고 있습니다. 모든 포스트를 받아보시려면 /atom/everything/을 구독하시거나, 다른 구독 옵션을 확인해보세요.