웹 페이지를 Claude Code 스킬로 역설계하기

저는 폴란드 탐사 보도 매체인 Frontstory에서, 하나의 큰 삽화 지도 위로 스크롤하며 이야기를 전하는 긴 기사를 봤습니다. 짧은 카드 하나를 읽으면 지도가 한 도시에 이동하고, 몇 개의 카드를 더 지나면 전체 지역을 보여주기 위해 뒤로 물러나거나 다른 곳으로 확대됩니다. 이 형식을 보통 '스크롤링 스토리텔링(scrollytelling)'이라고 부릅니다: 텍스트가 스크롤되고, 그 뒤의 이미지가 단락마다 바뀝니다.

저는 AI 시스템이 어떻게 작동하는지 설명할 때도 이런 페이지들이 필요해서, Claude Code에게 이 페이지를 분해하고 스스로 만드는 방법을 배우게 해달라고 요청했습니다. 이 글은 Claude Code가 무엇을 했고 제가 어디에 개입해야 했는지 그 과정을 담았습니다. 대부분의 예시는 가상의 데이터를 사용했으며, AI의 도움을 받아 초안 작성 및 수정이 이루어졌습니다.

프롬프트

폴란드어에서 번역된 전체 요청은 다음과 같았습니다:

https://frontstory.pl/sabotaze의 구조를 분석해 주세요. 스크롤하면 콘텐츠가 나타나고, 보기 좋게 애니메이션이 적용되어 있습니다. 이런 페이지를 HTML로 만들 수 있는 스킬을 저희 시스템에 추가해 주시겠어요? 형식을 철저히 분석한 후, 갤러리를 위한 세 가지 예시를 만들어 주세요.

이 스킬은 Vstorm에서 콘텐츠 기획, 리서치, 초안 작성 및 검토에 사용하는 내부 시스템인 Content OS용이었습니다. 그곳의 스킬이란 어디서든 Claude Code 스킬과 같은 개념입니다: 에이전트에게 특정 종류의 작업을 수행하는 방법을 알려주는 SKILL.md 파일과 해당 작업에 필요한 모든 스크립트 및 참고 자료가 들어있는 폴더를 말합니다. Content OS는 내부 시스템이라 이 글에서 설치할 것은 없습니다. 접근 방식(approach) 자체가 가치가 있는 부분입니다.

에이전트가 읽은 것

Claude Code는 해당 페이지를 다운로드하고 HTML을 읽었습니다. 또한 헤드리스 브라우저(headless browser)로 페이지를 열고, 독자가 보는 것을 보기 위해 데스크톱 및 휴대폰 너비에서 스크린샷을 찍어 임시 폴더에 보관했습니다. 이 과정에서 페이지의 텍스트, 이미지 또는 코드는 저희 저장소에 들어가지 않았습니다.

해당 페이지는 프레임워크가 없는 단일 수작업 HTML 파일이었습니다:

무대. 화면에 고정된 하나의 SVG 그림: 지도 자체를 이미지로 하고, 그 위에 약 15개의 일러스트레이션이 배치되어 있습니다.
카메라 타겟. SVG 내의 14개 보이지 않는 사각형으로, 각 사각형은 촬영샷이 보여야 할 무언가를 둘러싸고 있습니다.
단계. 36개의 텍스트 카드. 각각 카메라 타겟과 해당 카드가 화면에 표시되는 동안 보여줄 일러스트레이션을 명시합니다.
카메라. 카드가 활성화되면, 스크립트가 그 목표 사각형을 측정하고 SVG의 viewBox를 그쪽으로 애니메이션화합니다. viewBox를 변경하는 것이 그림이 줌인하고 패닝하는 것처럼 보이게 만듭니다.
트리거. 사용자가 스크롤함에 따라 어떤 카드가 활성화될지 IntersectionObserver가 결정합니다.

또한 리듬을 파악했는데, 이것이 실제 교훈이었습니다. 전체 지도의 설정 샷(establishing shot)으로 시작하여 한 장소로 줌인하고, 텍스트가 계속되는 동안 여러 카드들이 그 장소에 머무르다가, 다시 빠져나오고 다음 장소로 이동하는 식입니다. 대부분의 카드는 텍스트만 변경합니다. 카메라는 아마 세 번째 카드마다 움직이는 것 같습니다.

구축한 것들

몇 분 동안 읽은 후, 에이전트는 곧바로 코드로 넘어갔습니다. 순서대로: 카메라를 이동시키고 레이어를 보여주는 작은 런타임, 스타일시트, 빌드 스크립트, 페이지를 촬영하는 리코더, 그리고 세 가지 예제, 마지막으로 스킬입니다. 스킬 옆에는 원래 페이지에 대한 분해(teardown) 파일을 참조 파일로 저장했습니다. 이 파일에는 위에서 언급한 파트 목록과 리듬이 포함되어 있습니다.

그 파일은 전체 스킬에서 가장 유용한 것 중 하나가 되었습니다. 평범한 용어로 형식을 설명하며, 이후의 모든 페이지는 그것을 기반으로 시작합니다. 어떤 코드도 작성하기 전에 그 분해(teardown)를 자체적인 결과물로 요청하는 것은, 에이전트가 이해한 형식 위에서 구축하기 전에 그 형식을 이해했는지 확인할 수 있는 저렴한 방법입니다.

단일 아티클과 여러 페이지에 다른 역할을 부여하는 도구 덕분에, 분해(teardown) 파일에는 우리의 버전이 어디서 다른지 목록으로 나열되어 있습니다.

모든 카드 높이 지원. 카드는 상단이 화면의 한 줄을 넘어서면 활성화됩니다. 이때 카드의 길이가 아무리 길어도 마찬가지입니다. 좁은 휴대폰 화면에서 긴 카드가 문제였던 사례가 바로 이것입니다.
한 번에 하나의 카메라만 사용 가능. 새로운 카메라 움직임은 실행 중인 움직임을 취소하고, 그 위치부터 다시 시작합니다.
원격 연결 불가. 무대는 벡터 기반이며, 폰트는 내장되고, 빌드는 다른 서버에서 로드된 모든 것을 거부합니다. 완성된 페이지는 오프라인에서도 작동하는 단일 HTML 파일입니다.
오타가 크게 실패를 알림. 카드는 이전 카드에서 제외한 내용을 상속받고, 빌드는 자신이 모르는 속성이나 아무것도 가리키지 않는 ID를 가진 것을 거부합니다.
움직임 감소 기능. 시스템에 움직임을 적게 요청하는 독자를 위해 카메라가 미끄러지는 대신 잘립니다(cuts).
스크롤 기반 애니메이션. 카드는 독자가 현재 어느 지점에 있는지, 0부터 1까지의 비율을 게시할 수 있습니다. 따라서 스크롤함에 따라 무대 위의 무언가가 커지거나 채워질 수 있습니다.

이 모든 것은 원본에 대한 비판이 아닙니다. 이는 같은 아이디어가 아직 아무도 본 적 없는 주제를 다루는 에이전트가 작성한 페이지에서 살아남아야 할 때 변화하는 부분입니다.

스킬 작동 방식

이 스킬은 무언가를 그리기 전에 스토리부터 설계하도록 에이전트에게 지시합니다. 먼저 비트 시트를 만듭니다: 단계별로 한 행을 사용하며, 카드가 말할 문장, 무대가 보여줄 내용, 카메라 위치를 포함합니다. 다음으로 하나의 무대를 만들고, SVG 내에서 한 번에 그리며, 모든 샷이 프레임할 영역 주변에는 눈에 보이지 않는 cam-* 사각형을 배치하고, 각 단계가 드러낼 모든 요소에는 .layer 그룹을 사용합니다. 그리고 카드를 만듭니다.

카드는 몇 가지 데이터 속성을 가진 일반 HTML입니다. 에이전트 요청 예시에서 가져온 이 코드는 앱으로 확대되어 그림의 세 부분을 보여줍니다:

<section class="step" data-camera="#cam-app" data-show="#b-request, #p-ask, #b-wrap">
  <h2>모델이 필요한 것을 앱이 추가합니다</h2>
  <p>모델은 텍스트만 볼 수 있습니다. 앱은 당신의 메시지와 함께...

빌드 스크립트(build script)가 해당 story.html을 완성된 페이지로 변환합니다. 무언가를 작성하기 전에, 이 스크립트는 카드에 이름이 지정된 모든 카메라와 레이어가 드로잉 내에 존재하는지 확인하고, 페이지에 제목과 언어 및 대체 텍스트(alt text)가 있는지, 그리고 네트워크에서 로드되는 것이 없는지를 확인합니다. 그런 다음 헤드리스 브라우저(headless browser)에서 페이지를 열고, 모든 단계로 스크롤하며, 정적 검사로는 알 수 없는 활성화되지 않은 단계가 있으면 실패 처리합니다. --film 옵션으로는 독서 속도로 페이지를 비디오로 기록하여, 인터랙티브한 페이지가 아닌 비디오 형태의 채널에도 활용할 수 있습니다.

이러한 검사들이 중요한 이유는, 에이전트(agent)가 사각형이 #cam-tool이라고 호출되었을 때 #cam-tools를 가리키는 카드를 쉽게 작성할 수 있기 때문입니다. 이 검사가 없으면 해당 카드는 아무것도 하지 않을 것이고, 독자가 발견하기 전까지 아무도 알아차리지 못할 것입니다.

저의 첫 번째 리뷰와 사과

첫 번째 버전은 프롬프트(prompt)를 받은 후 약 30분 만에 돌아왔습니다. 예시들을 열어 대략 다음과 같이 작성했습니다. '텍스트만 움직이고 배경은 움직이지 않지만, 핵심은 배경도 바뀔 수 있다는 것입니다. 에이전트 요청 맵(Agent request map)은 좋지만, 나머지는 약합니다.'

그리고 같은 메시지에서: '젠장, 미안하다. 내가 그걸 잘못 표현했어. 예시들은 사실 정말 좋다. 더 많이 만들고 스타일을 다양하게 변주해서 선택의 폭을 넓혀줘. 5개에서 10개 정도 더 부탁해.'

에이전트는 이 두 부분 모두를 진지하게 받아들였습니다. 다음 라운드에서는 스테이지가 변화할 수 있는 세 가지 방법을 추가했습니다:

장면(Scenes). 카드가 분위기(mood)를 지정하면, 스타일시트(stylesheet)가 전체 스테이지의 색상을 변경합니다. 한 예시에서는 독서하는 동안 도시가 황혼에서 밤을 거쳐 아침으로 바뀝니다.
깊이(Depth). 스테이지의 일부는 서로 다른 깊이에 위치할 수 있어, 모든 카메라 움직임이 패럴랙스(parallax) 효과를 갖게 됩니다.
재배치(Rearranging). 페이지 스크립트가 스테이지 자체 요소들을 이동시킬 수 있습니다. 또 다른 예시에서는 400개의 점들, 각 점은 가상의 지원 티켓 하나에 해당하며, 주제별로 쌓여서 바 차트(bar chart) 형태로 배열됩니다.

이제 이 스킬은 명확하게 말합니다. 텍스트만 움직이는 페이지는 사진이 있는 아티클입니다.

다양한 스타일의 9가지 예시

19:49에 처음 프롬프트를 던진 순간부터 9가지 예시가 포함된 병합 풀 리퀘스트(merged pull request)까지 약 두 시간이 걸렸습니다. 여기에는 코덱스(Codex)가 풀 리퀘스트를 검토한 두 번의 라운드가 포함됩니다. 코덱스는 단일 파일 페이지에서는 손실될 수 있는 파일을 참조하는 경우나, 이전 빌드에서 남겨진 오래된 비디오 파일 등 여러 가지 문제점을 발견했고, Claude Code가 이를 수정했습니다. 저는 두 번째 라운드 후에 병합을 완료했습니다. 세 번째 라운드는 병합 후 여덟 가지 추가적인 발견 사항과 함께 돌아왔으며, 이는 아직 해결되지 않은 상태입니다.

각 예시는 서로 다른 시각적 스타일과 스테이지를 움직이는 방식을 사용합니다:

AI 에이전트를 통해 전달되는 요청, 카메라가 하나의 다이어그램을 가로지르며 이동하는 방식
황혼에서 낮으로 변하는 도시를 배경으로 전개되는 온콜(on call) 밤
점들이 스스로 정렬되는 지원 티켓 주간
텍스트 청크(text chunks)가 점으로 바뀌는 RAG 시스템에서의 검색
실제 논문을 인용하며 하나의 긴 신문 스타일 페이지에 담긴 70년간의 AI 역사
사용자가 스크롤할 때 터미널에 출력되는 에이전트와 MCP 서버 간의 대화
생생하고 다채로운 장면에서 회귀(regression)를 포착하는 평가(eval)
페이지 자체가 계산하며 움직이는, 리트라이(retries)에 백오프(backoff)가 필요한 이유에 대한 차트
스크롤함에 따라 채워지고 압축되는 컨텍스트 윈도우(context window)

이 모든 예시는 패널의 갤러리에 배치되어 있으며, 각각은 모바일 너비 토글과 함께 샌드박스 프레임에서 라이브 페이지로 열립니다.

다양한 스타일을 요청했기 때문에 선택할 것이 더 많았습니다. 돌이켜보면 이것은 다른 것을 보여줍니다. 하나의 예시는 에이전트가 본 것을 재현할 수 있다는 것만 증명하는 반면, 다양한 스타일의 아홉 개는 이 기술이 원래 주제와 분리될 수 있음을 보여줍니다.

직접 해보기

이것은 Claude Code를 사용한 저녁 시간이었지만, 저는 같은 단계가 다른 형식과 다른 코딩 에이전트에도 적용될 것이라고 예상합니다:

에이전트에게 실제 대상을 지목하세요. 스크린샷에서 추측하는 것만이 아니라, 페이지를 다운로드하여 데스크톱 및 휴대폰 너비로 브라우저에서 열어달라고 요청하세요.
자체 파일 형태로 분해 분석(teardown)을 요청하세요. 부분들, 연결 방식, 리듬이 무엇인지 나열한 짧은 참고 자료입니다. 이것을 읽으세요. 만약 이해할 수 없다면, 그것을 기반으로 구축된 스킬 역시 불안정할 것입니다.
재사용 가능한 도구가 다르게 해야 할 것이 무엇인지 목록화하도록 하세요. 하나의 페이지와 생성기는 서로 다른 역할을 합니다.
그리고 스킬입니다. 방법론이 담긴 SKILL.md 파일, 시작할 수 있는 템플릿, 그리고 에이전트의 실수가 크게 실패(fail loudly)하는지 확인하는 스크립트를 만드세요.
다양한 스타일로 여러 예시를 요청하세요. 이는 기술이 새로운 주제에서도 살아남는지 테스트합니다.
솔직하게 검토하세요. 첫 번째 버전이 만들어졌을 때의 저의 반응이 그날 저녁 가장 큰 변화를 가져왔고, 사과도 포함되었습니다.

그리고 콘텐츠가 아닌 기술 자체를 빌리세요. 스킬 자체가 그렇게 말하고 있습니다. 다른 출판물의 구조를 재사용하는 페이지는 그 텍스트, 그림 또는 브랜딩 중 어느 것도 사용하지 않습니다.

이것이 보여주지 않는 것들

이 스킬은 새로워요. 저희 출판 기록에는 아직 이 스킬로 만들어진 것이 없기 때문에, 실제 독자나 지저분한 데이터가 있는 주제를 만나본 적이 없습니다. 대부분의 예시는 가상의 숫자를 사용한 교육 자료입니다. 8개의 검토 결과는 여전히 기다리고 있습니다. 그리고 2시간 동안 작업할 수 있었던 것은 Content OS에 이미 빌드 파이프라인, 갤러리, 그리고 새로운 스킬이 연결될 수 있는 다른 형식에 대한 확인 절차가 갖춰져 있었기 때문입니다.

그럼에도 불구하고, 이는 포맷을 학습하는 좋은 방법입니다. 단순히 페이지를 감상하는 대신, 에이전트에게 그것을 제대로 읽고, 도구를 만들게 한 다음, 어떻게 작동하는지에 대한 설명을 남기도록 요청할 수 있습니다.

최근에 보고 코딩 에이전트가 분해해 보았으면 하는 포맷은 무엇인가요?

원조는 Anastasiia Morozova의 인터랙티브 시각화와 Alisa Szorochowa의 일러스트레이션으로 제작된 Frontstory, "Paczka z bombą"입니다.