에이전트와의 협업에서 Markdown 대신 HTML을 출력 형식으로 선호하게 된 이유와, 설계·코드 리뷰·리포트·인터랙티브 도구 제작 등 다양한 활용 사례를 설명합니다.
Markdown은 에이전트가 우리와 소통할 때 사용하는 지배적인 파일 형식이 되었습니다. 단순하고, 이식 가능하며, 어느 정도의 서식 기능이 있고, 직접 편집하기도 쉽습니다. Claude는 심지어 markdown 파일 안에서 ASCII로 다이어그램을 만드는 일도 놀랄 만큼 잘하게 되었습니다.
하지만 에이전트가 점점 더 강력해지면서, 저는 markdown이 오히려 제약이 되는 형식이라는 느낌을 받게 되었습니다. 100줄이 넘는 markdown 파일은 읽기가 어렵습니다. 더 풍부한 시각화, 색상, 다이어그램을 원하고, 그것들을 쉽게 공유할 수 있기를 바랍니다.
또한 저는 점점 이런 파일들을 직접 편집하지 않고, 명세서, 참고 파일, 브레인스토밍 결과물 등으로 사용하고 있습니다. 실제로 수정이 필요할 때도 보통 Claude에게 편집하라고 프롬프트를 주기 때문에, markdown의 가장 큰 장점 중 하나가 사라집니다.
저는 Markdown 대신 HTML을 출력 형식으로 선호하기 시작했고, Claude Code 팀의 다른 사람들도 점점 그렇게 사용하는 것을 보고 있습니다. 그 이유는 다음과 같습니다.
(예시부터 보고 싶다면, 여기에서 여러 개를 볼 수 있습니다:
, 다만 왜 그런지에 대한 설명을 더 읽으러 꼭 돌아오세요)
HTML은 markdown보다 훨씬 더 풍부한 정보를 전달할 수 있습니다. 물론 제목이나 서식 같은 단순한 문서 구조도 표현할 수 있지만, 그 외에도 다음과 같은 다양한 정보를 나타낼 수 있습니다.
테이블을 이용한 표 형식 데이터
CSS를 활용한 디자인 데이터
SVG를 활용한 일러스트레이션
script 태그를 활용한 코드 스니펫
javascript + CSS와 HTML 요소를 활용한 인터랙션
SVG와 HTML을 활용한 워크플로
절대 위치 지정과 canvas를 활용한 공간 데이터
image 태그를 활용한 이미지
저는 Claude가 읽을 수 있는 정보 집합 중 HTML로 꽤 효율적으로 표현할 수 없는 것은 거의 없다고까지 말하고 싶습니다. 즉, 모델이 여러분에게 심층적인 정보를 전달하고, 여러분이 그것을 검토하기 위한 매우 효율적인 방식이라는 뜻입니다.
이런 표현이 불가능할 때, 모델은 markdown 안에서 ASCII 다이어그램 같은 비효율적인 방법을 쓰거나, 제가 가장 좋아하는 예로는 Claude Code의 이 스크린샷처럼 유니코드 문자로 색상을 추정해 표현하기도 합니다.
markdown에서 색을 보여주려고 하는 Claude Code
Claude가 더 복잡한 작업을 할 수 있게 되면서, 더 크고 방대한 명세와 계획도 작성하게 되었습니다. 실제로는 100줄이 넘는 markdown 파일은 거의 읽지 않게 되고, 조직 내 다른 사람들에게 그것을 읽게 만드는 것은 더더욱 어렵다는 것을 느꼈습니다.
반면 HTML 문서는 훨씬 읽기 쉽습니다. Claude는 탭, 일러스트레이션, 링크 등을 활용해 탐색하기 이상적인 구조를 시각적으로 구성할 수 있습니다. 심지어 모바일 반응형으로 만들어서 기기 형태에 따라 다르게 읽을 수도 있습니다.
Markdown 파일은 대부분의 브라우저가 기본적으로 잘 렌더링하지 못하기 때문에 공유하기가 꽤 어렵습니다. 이메일이나 메시지에 첨부파일로 넣어야 하는 경우가 많습니다.
HTML은 파일만 업로드해 두면(예를 들어 S3에) 링크를 쉽게 공유할 수 있습니다. 동료들은 원하는 곳 어디서나 열어 보고 쉽게 참조할 수 있습니다.
누군가가 여러분의 명세, 보고서, 또는 PR 설명을 실제로 읽을 가능성은 HTML일 때 훨씬 더 높습니다.
HTML은 문서와 상호작용할 수 있게 해줍니다. 예를 들어 디자인을 조정할 슬라이더나 노브를 추가하게 하거나, 알고리즘의 여러 옵션을 조정하면서 어떤 일이 일어나는지 보게 할 수 있습니다. 또 이런 변경 사항을 프롬프트로 복사해서 Claude Code에 다시 붙여 넣을 수 있게 만들 수도 있습니다. 이런 양방향 상호작용의 예시는 제 playgrounds 글에서 더 볼 수 있습니다.
Data Ingestion
왜 HTML 파일을 만들 때 ClaudeAI나 Claude Design이 아니라 Claude Code를 써야 할까요? 가장 큰 이유 중 하나는 Claude Code가 흡수할 수 있는 컨텍스트의 양입니다. 예를 들어 이 글을 작성할 때 저는 Claude Code에게 제 코드 폴더를 훑어보고, 제가 생성한 모든 HTML 파일을 찾고, 그것들을 그룹화하고 분류한 다음, 각 유형을 나타내는 다이어그램이 포함된 HTML 파일을 만들라고 했습니다. 이 글에서 보는 다이어그램들은 그 결과물입니다.
파일 시스템 외에도 Claude Code는 MCP들(Slack, Linear 등), 웹 브라우저(Chrome의 Claude), git 히스토리 등을 통해 추가 컨텍스트를 찾을 수 있습니다.
Claude로 HTML 문서를 만드는 것은 그냥 더 재미있고, 제가 창작 과정에 더 깊이 관여하고 투자하고 있다는 느낌을 줍니다. 그것만으로도 충분한 이유입니다.
사람들이 이 글을 읽고 이것을 /html 스킬 같은 것으로 만들어 버릴까 봐 약간 걱정되기도 합니다. 물론 거기에도 어느 정도 가치는 있을 수 있지만, Claude에게 이런 작업을 시키기 위해 많은 것을 할 필요는 없다는 점을 강조하고 싶습니다. 그냥 “HTML 파일을 만들어줘” 또는 “HTML artifact를 만들어줘”라고 요청하면 됩니다.
핵심은 그 artifact가 무엇을 하길 원하는지, 그리고 그것을 어떻게 활용할지 아는 것입니다. 시간이 지나면서 스킬을 만들게 될 수도 있겠지만, 지금은 먼저 매번 처음부터 프롬프트를 작성해 보면서 다양한 경우에 이것을 어떻게 사용할지 감을 익히는 것을 권합니다.
좀 더 구체적으로 말하자면, 저는 다양한 사용 사례를 위해 여러 종류의 HTML 파일을 만들어 왔습니다. 모두 여기에서 볼 수 있습니다:
하지만 여기서는 개요를 보여드리겠습니다.
HTML은 Claude가 문제 속으로 깊이 들어갈 수 있게 해주는 풍부한 캔버스입니다. 저는 문제를 다루기 시작할 때 단순한 markdown 계획 하나 대신 HTML 파일들의 거미줄 같은 묶음을 만들게 될 것이라고 기대합니다. 예를 들어, 먼저 Claude Code에게 브레인스토밍을 하고 다양한 선택지에 대한 탐색 결과를 만들라고 할 수 있습니다. 그다음 그중 하나를 더 확장하게 하고, 목업이나 코드 스니펫을 만들게 할 수 있습니다. 마지막으로 충분히 마음에 들면 구현 계획을 작성하게 합니다. 계획이 만족스러우면 새 세션을 만들고 이 파일들을 모두 넘겨 구현하게 합니다.
검증할 때도 검증 에이전트에게 이 파일들을 읽게 하면, 무엇이 필요한지에 대해 훨씬 더 넓은 컨텍스트를 갖게 됩니다.
예시 프롬프트:
온보딩 화면을 어떤 방향으로 가져가야 할지 잘 모르겠어요. 서로 확실히 다른 6가지 접근을 생성해 주세요. 레이아웃, 톤, 정보 밀도를 다양하게 바꾸고, 하나의 HTML 파일 안에 그리드로 배치해서 나란히 비교할 수 있게 해주세요. 각각이 어떤 트레이드오프를 선택한 것인지 라벨도 붙여 주세요.
HTML 파일로 철저한 구현 계획을 만들어 주세요. 목업도 몇 개 포함하고, 데이터 흐름도 보여주고, 제가 검토하고 싶을 중요한 코드 스니펫도 넣어 주세요. 읽기 쉽고 소화하기 쉽게 만들어 주세요.
사용 사례:
코드에서 무언가를 구현하는 다른 방법 탐색
여러 시각적 디자인 탐색
코드는 Markdown 파일 안에서는 읽기 어려울 수 있습니다. 하지만 HTML을 사용하면 diff, 주석, 플로차트, 모듈 등을 렌더링할 수 있습니다. 이를 통해 에이전트가 작성한 코드를 이해하고, 코드 리뷰를 하거나, 코드를 검토하는 사람에게 PR을 설명할 수 있습니다. 저는 이것이 기본 Github diff 뷰보다 더 잘 작동하는 경우가 많다고 느끼며, 이제 제가 만드는 모든 PR에 HTML 코드 설명 자료를 첨부합니다.
예시 프롬프트:
이 PR을 설명하는 HTML artifact를 만들어서 리뷰를 도와주세요. 저는 streaming/backpressure 로직에 익숙하지 않으니 거기에 집중해 주세요. 실제 diff를 인라인 여백 주석과 함께 렌더링하고, 발견 사항은 심각도별로 색상 코딩해 주세요. 그리고 개념을 잘 전달하는 데 필요한 다른 요소도 자유롭게 추가해 주세요.
사용 사례:
PR 작성
PR 리뷰
코드 주제 이해
Claude Design이 HTML을 기반으로 하는 이유는, 최종 결과물이 HTML이 아니더라도 HTML이 디자인 표현에 놀라울 정도로 강력하기 때문입니다. Claude는 HTML로 디자인을 스케치한 다음, React, Swift 등 원하는 언어로 다시 작성할 수 있습니다.
애니메이션이나 액션 같은 인터랙션도 프로토타이핑할 수 있습니다. Claude에게 슬라이더, 노브 등을 만들어 달라고 요청해서 원하는 결과를 정확히 맞춰 보세요.
예시 프롬프트:
새로운 checkout 버튼을 프로토타이핑하고 싶어요. 클릭하면 재생 애니메이션이 실행된 뒤 빠르게 보라색으로 바뀌게 해주세요. 이 애니메이션의 여러 옵션을 시도해 볼 수 있도록 여러 슬라이더와 옵션이 있는 HTML 파일을 만들어 주세요. 잘 나온 파라미터를 복사할 수 있는 버튼도 넣어 주세요.
이런 용도로 활용하세요:
디자인 시스템 artifact 만들기
컴포넌트 조정
컴포넌트 라이브러리 시각화
즐거운 애니메이션 프로토타이핑
Claude Code는 여러 데이터 소스에 걸친 정보를 종합하고, 그것을 읽기 쉬운 보고서로 바꾸는 데 매우 뛰어납니다. Slack, 코드베이스, git 히스토리, 인터넷 등을 검색해서 자신을 위한 보고서, 리더십을 위한 보고서, 팀을 위한 보고서 등을 매우 읽기 쉽게 생성하라고 Claude에게 요청할 수 있습니다.
이것은 긴 HTML 문서, 인터랙티브 설명 자료, 혹은 슬라이드쇼/덱 형태로 구성할 수 있습니다. 시각화를 돕기 위해 다이어그램에 SVG를 사용하라고 요청해 보세요. 예를 들어 prompt caching에 관한 제 글들을 쓸 때, 저는 Claude에게 git 히스토리를 읽고 prompt caching과 관련된 모든 변경 사항을 정리한 심층 HTML 리서치 파일을 준비해 달라고 했습니다.
예시 프롬프트: 우리 rate limiter가 실제로 어떻게 동작하는지 잘 모르겠어요. 관련 코드를 읽고 단일 HTML 설명 페이지를 만들어 주세요: token-bucket 흐름도, 주석이 달린 핵심 코드 스니펫 3~4개, 그리고 하단의 "gotchas" 섹션을 포함해 주세요. 한 번 읽는 사람에게 최적화해 주세요.
이런 용도로 활용하세요:
기능이 어떻게 동작하는지 요약
개념을 설명받기
상사에게 보내는 주간 상태 보고서
리더십에 보내는 사고 보고서
SVG 일러스트, 플로차트, 기술 다이어그램 등
때로는 원하는 것을 텍스트 상자만으로 설명하기 어렵습니다. 이럴 때 저는 Claude에게 지금 작업 중인 바로 그 대상만을 위한 일회성 편집기를 만들어 달라고 합니다. 제품도 아니고, 재사용 가능한 도구도 아니라, 이 데이터 조각 하나만을 위해 특별히 만든 단일 HTML 파일입니다.
핵심은 항상 export로 끝내는 것입니다. 즉, "copy as JSON"이나 "copy as prompt" 버튼을 넣어서, UI에서 한 작업을 다시 Claude Code에 붙여 넣을 수 있는 형태로 되돌리는 것입니다.
예시 프롬프트:
이 30개의 Linear 티켓 우선순위를 다시 정해야 해요. 각 티켓을 드래그 가능한 카드로 만들어 Now / Next / Later / Cut 열 사이에서 옮길 수 있는 HTML 파일을 만들어 주세요. 먼저 당신의 최선의 추정으로 미리 정렬해 두고, 최종 순서를 버킷별 한 줄 근거와 함께 내보내는 "copy as markdown" 버튼도 추가해 주세요.
여기 우리 feature flag 설정이 있어요. 이것을 위한 폼 기반 편집기를 만들어 주세요. 영역별로 플래그를 묶고, 플래그 간 의존성을 보여주고, 선행 조건이 꺼져 있는 플래그를 제가 켜려고 하면 경고해 주세요. 변경된 키만 주는 "copy diff" 버튼도 추가해 주세요.
이 system prompt를 조정하고 있어요. 좌우 병렬 편집기를 만들어 주세요. 왼쪽에는 변수 슬롯이 강조된 편집 가능한 프롬프트를 두고, 오른쪽에는 템플릿이 채워진 결과를 실시간으로 다시 렌더링하는 샘플 입력 3개를 보여 주세요. 문자/토큰 카운터와 복사 버튼도 추가해 주세요.
이런 용도로 활용하세요:
무엇이든 재정렬, 트리아지, 또는 버킷 분류하기(티켓, 테스트 케이스, 피드백)
구조화된 설정 편집하기(feature flags, env vars, 제약 조건이 있는 JSON/YAML)
프롬프트, 템플릿, 문구를 실시간 미리보기와 함께 조정하기
데이터셋 큐레이션, 행 승인/거절, 예시 태깅, 선택 결과 내보내기
문서, 대화록, diff에 주석을 달고 주석 결과 내보내기
텍스트로 표현하기 까다로운 값 선택하기: 색상, easing curves, crop regions, cron schedules, regexes.
제가 HTML로 전환했다고 많은 사람들에게 이야기해 왔는데, 반복해서 받는 질문이 몇 가지 있습니다.
토큰 효율이 더 낮지 않나요? markdown이 보통 더 적은 토큰을 쓰기는 하지만, HTML의 추가적인 표현력과 제가 실제로 그것을 읽게 될 가능성이 훨씬 높다는 점을 감안하면 전체적으로 더 나은 결과를 얻는다고 느꼈습니다. Opus 4.7의 1MM 컨텍스트 윈도우에서는 늘어난 토큰 사용량도 사실상 눈에 띄지 않습니다.
그렇다면 이제 markdown은 언제 쓰나요? 솔직히 말하면 저는 거의 모든 것에서 markdown을 완전히 쓰지 않게 되었습니다. 다만 저는 HTML 극대주의 쪽에 꽤 치우쳐 있는 편일 겁니다.
HTML 파일은 어떻게 보나요? 저는 보통 로컬에서 브라우저로 그냥 엽니다(Claude에게 열라고 요청할 수도 있습니다). 공유 가능한 링크가 필요하다면 S3에 업로드하면 됩니다.
markdown보다 생성 시간이 더 오래 걸리지 않나요? 맞습니다, 더 오래 걸립니다! HTML은 Markdown보다 2~4배 더 오래 걸릴 수 있습니다. 하지만 결과는 그만한 가치가 있다고 느꼈습니다.
버전 관리는 어떻죠? 솔직히 이것은 HTML의 가장 큰 단점 중 하나입니다. HTML diff는 Markdown에 비해 노이즈가 많고 리뷰하기 어렵습니다.
Claude가 내 취향에 맞추고 못생기지 않게 하려면 어떻게 하나요? frontend design plugin은 Claude가 좋은 HTML 파일을 만들도록 도와줍니다. 하지만 회사 스타일에 맞추려면, Claude에게 코드베이스를 보게 해서 하나의 디자인 시스템 HTML 파일을 만들 수 있습니다. 그러면 그 디자인 시스템 파일을 다른 html 파일의 참고 자료로 사용할 수 있습니다.
이 모든 이야기를 종합하면, 제가 HTML을 사용하는 진짜 이유는 Claude와 함께 작업의 흐름 안에 더 깊이 들어와 있다는 느낌을 받기 때문이라고 생각합니다. 저는 한때 계획을 깊이 읽지 않게 되면서, 결국 Claude가 스스로 선택하게 내버려 둘 수밖에 없을까 두려워하기 시작했습니다.
하지만 이제는 오히려 HTML을 사용할 때 그 어느 때보다도 더 깊이 흐름 안에 들어와 있다는 느낌이 들어서 기쁩니다. 여러분도 그러길 바랍니다.
