텍스트는 느리다: AI 에이전트를 위해 페이지를 요청하라

Andrej Karpathy는 X에서 다음과 같은 간단한 점을 제기했습니다: AI가 더 많은 작업을 수행함에 따라 우리의 역할은 감독과 이해로 이동하며, 일반 텍스트는 무엇이든 이해하는 가장 느린 방법인 경우가 많습니다. 그는 출력 형식의 사다리(ladder of output formats)를 제시합니다: 통제된 언어 텍스트 (controlled-language text), 다이어그램, 인터랙티브 HTML 페이지, 그리고 설명 비디오입니다. 또한 코드는 이제 크고 일회성으로 사용할 소프트웨어를 구축하기에 충분히 저렴해졌다고 말합니다.

이 아이디어는 동의하기 쉽지만 잊기 쉽습니다. 이 가이드가 그것을 실용적으로 만듭니다. 아래에는 오늘 Claude Code, Cursor 또는 Claude에서 설정할 수 있는 다섯 가지 실제 사례가 있으며, 각각 복사할 수 있는 프롬프트가 제공됩니다. 그 외에도 나중에 사용할 수 있는 다섯 가지 아이디어가 더 있습니다.

모든 예시의 기반이 되는 규칙

모든 사례는 동일한 루프를 따릅니다:

1. 이미 가지고 있는 텍스트 (강좌, diff, 로그, 스크립트)를 가져옵니다.
2. 모델에게 데이터가 임베딩된 하나의 독립적인 HTML 파일을 요청합니다.
3. 브라우저에서 열고 읽습니다. 버리거나 보관합니다.

파일이 자체적으로 완결되도록 유지해야 합니다. 빌드 단계도, 서버도, 외부 데이터도 안 됩니다. 이 하나의 규칙이 모든 도구에서 동일하게 작동하게 만듭니다.

사용 사례 1: 강좌 블로그를 인터랙티브 스토리텔링 학습 자료로 변환

Image
Course Blog into Interactive lesson using AI

문제점: 강좌 콘텐츠는 보통 긴 텍스트입니다. 학생들은 그것을 훑어보고 잊어버립니다.

해결책: 각 학습 자료를 다이어그램, 작은 상호작용 요소, 그리고 간단한 확인 질문이 포함된 스크롤 기반 스토리로 만듭니다.

프롬프트:

lesson-03.md을 읽어라. lesson-03.html 파일을 하나의 파일로 만들어라. 스크롤 스토리 형식으로 구성해라: 화면당 하나의 아이디어, 주요 개념에 대한 SVG 다이어그램, 상호작용 요소 하나 (슬라이더, 토글 또는 클릭을 통한 전환), 그리고 마지막에 퀴즈 질문 세 개를 포함시켜라. 텍스트는 간단한 기술 영어로 작성해라: 짧은 문장, 능동태 사용. 어두운 테마를 적용하라.

실행 위치(Where to run it): Claude Code 또는 Cursor를 사용하고 lessons 폴더에 대해 반복 루프를 돌리세요. 매번 동일한 레이아웃을 요청하여 과정이 일관되게 보이도록 하세요. 배포하기 전에 각 레슨의 사실 관계는 직접 확인하세요. 잘 다듬어진 페이지가 잘못된 주장을 옳아 보이게 만들 수 있습니다.

사용 사례 2: 커밋 또는 diff로부터 풀 리퀘스트 미리보기

Image Git 차이를 시각적 PR 미리보기로

문제: diff는 무엇이 변경되었는지 보여줄 뿐, 그것이 무엇을 의미하는지는 보여주지 않습니다. 검토자는 위험한 변화를 찾기 위해 수백 줄의 코드를 읽어야 합니다.

해결책: 각 풀 리퀘스트에 대한 시각적 미리보기를 생성합니다.

프롬프트 (Cursor 또는 Claude Code, 레포 내부에서):

git diff main...HEAD를 실행하세요. pr-preview.html이라는 파일 하나로 만드세요. 다음 내용을 포함해야 합니다: 5줄의 평이한 영어 요약, 변경된 파일과 함수 및 이들이 어떻게 연결되는지 보여주는 다이어그램, 가장 중요한 세 가지 변화에 대한 전후(before and after) 스니펫, 그리고 위험 요소와 테스트할 사항 목록.

실제 diff 옆에 파일을 열어두세요. 이것을 코드를 읽는 대체재가 아니라 지도처럼 사용하세요. 팀 환경의 경우, 이 파일을 CI 아티팩트로 추가하여 모든 PR에 링크를 갖도록 하세요. 모델이 버그를 놓칠 수 있으므로,

오늘의 다섯 에이전트 로그(logs/*.json)를 가져와서, 데이터를 포함하는 daily-report.html 파일을 만드세요. 다음 내용을 보여줘야 합니다: 무엇이 완료되었는지, 무엇이 실패했는지, 그리고 인간의 결정이 필요한지 보여주는 상단 카드; 에이전트별 타임라인; 에이전트로 필터링하기; 클릭 시 열리는 '이유(why)' 패널. 비기술적인 독자를 위해 평범하고 차분한 언어를 사용하세요.

실행 위치: 스케줄된 스크립트가 로그를 수집하고, Claude를 호출하며, 파일을 작성하고 이메일로 보내거나 호스팅합니다. 데이터가 포함되어 있기 때문에, 이메일 첨부 파일에서 열어도 페이지가 작동합니다. 아동과 관련된 것이라면, 부모님이 필요한 정보만 보여주고 기본적으로 개인적인 세부 정보는 포함하지 마세요.

사용 사례 4: YouTube 동영상을 강의 및 설명 자료로 변환

ImageYouTube 동영상을 인터랙티브 예제로

문제점: 최고의 교육 자료는 긴 동영상에 갇혀 있습니다.

해결책: 스크립트를 아카이브한 다음, 이를 페이지로 만드세요. TubeLog은 각 동영상의 스크립트를 마크다운(Markdown) 파일로 저장하며, 이는 이상적인 입력 자료입니다.

프롬프트:

videos/<channel>/<video-id>.md 파일을 읽어주세요. 다음 내용을 포함하는 HTML 설명 자료를 만드세요: 5가지 핵심 아이디어를 카드 형태로, 주요 프로세스의 다이어그램, 용어집, 그리고 원본 동영상으로 돌아가는 링크. 스크립트 내용 내에 머물러 주세요. 화자가 말하지 않은 사실은 추가하지 마세요.

마지막 문장이 중요합니다. 만약 동영상을 원한다면, 장면 계획(scene plan)과 Manim 또는 Remotion 코드를 한 장면씩 요청하세요. 렌더링하기 전에 항상 스크립트를 읽으세요.

사용 사례 5: 코드베이스 온보딩 투어

Image아키텍처 맵이 포함된 코드베이스 온보딩 투어

문제점: 새로운 개발자가 300개의 파일이 있는 리포지토리를 열었지만 어디서부터 시작해야 할지 전혀 모른다.

해결책: 프로젝트의 인터랙티브한 지도(map).

프롬프트:

이 리포지토리를 탐색하여 온보딩 페이지를 만들어 주세요. onboarding.html이라는 단일 파일로 작성해 주세요. 각 상자가 클릭 가능하고, 해당 모듈이 무엇을 하는지, 핵심 파일은 무엇인지, 테스트는 어떻게 실행하는지를 보여주는 패널이 열리는 아키텍처 다이어그램을 추가해 주세요. 진입점부터 데이터베이스까지 '요청 하나 따라가기(follow one request)' 워크스루를 추가해 주세요. 첫 주 학습 순서도 추가해 주세요.

실행할 곳: Claude Code가 가장 좋습니다. 전체 리포지토리를 읽을 수 있기 때문입니다. 아키텍처가 변경될 때마다 파일을 재생성하세요. 모델이 단순히 훑어본 파일에 대해 설명하는 경우가 있으므로, 몇몇 상자를 클릭하여 코드와 비교해 보세요.

시도해 볼 만한 다섯 가지 추가 아이디어

1. API 문서 탐색기(API docs explorer): OpenAPI 파일을 사용자가 요청을 편집하고 샘플 응답을 확인할 수 있는 페이지로 변환합니다.
2. 사고 분석 보고서(Incident postmortem): 로그와 채팅 내용을 원인 다이어그램이 포함된 타임라인으로 만듭니다.
3. 회의록을 액션 페이지로: 결정 사항, 담당자, 마감일을 체크리스트 형태로 정리합니다.
4. 계약 또는 정책 설명서(Contract or policy explainer): 위험 조항을 강조한 일반 언어 버전으로 작성합니다.
5. 연구 논문 설명서(Research paper explainer): 방법론을 용어집이 포함된 인터랙티브 다이어그램으로 만듭니다.

구현 도구(Implementation Tools)

• Claude Code: 리포지토리, 로그 및 여러 파일을 한 번에 처리하는 데 가장 좋습니다. 폴더와 대상 파일명을 지정해 주세요.
• Cursor: 이미 에디터 안에 있을 때 가장 좋습니다. 에이전트 모드를 사용하고 HTML 파일을 브라우저 패널이나 실제 브라우저에서 엽니다.
• Claude (채팅): 일회성 페이지에 가장 좋습니다. 텍스트를 업로드하고 HTML 아티팩트를 요청한 다음, 게시하거나 다운로드합니다.

요약(Summary)

텍스트는 기본값일 뿐, 최선의 선택은 아닙니다.