Anthropic Claude Code 팀의 Thariq Shihipar(@trq212)가 공개한 글 "Using Claude Code: The Unreasonable Effectiveness of HTML"의 핵심을 정리하고, 어떻게 적용할지 실전 프롬프트와 함께 풀어 쓴 내용입니다. 그가 공유한 실제 HTML 예시 갤러리도 함께 보시면 이해가 빠릅니다.
html이라는 단어가 흰색 배경에 그려져 있습니다.
Claude Code의 HTML 출력 방식은 에이전트가 결과물을 마크다운(.md)이 아닌 HTML(.html) 파일로 만들어 주고받는 작업 방식입니다. Anthropic Claude Code 팀이 내부에서 디폴트로 채택한 새로운 방식으로, 복잡한 결과물을 더 정확하게 표현하고 사람·에이전트가 함께 다루기 쉽게 만들기 위한 전환입니다.
왜 지금 Claude Code 출력을 HTML로 바꿔야 할까
마크다운은 GPT-4 시절 8K 토큰 시대에 굳어진 디폴트였습니다. 토큰 절약과 휴대성, 사람이 직접 편집하기 좋다는 강점이 있었습니다. 그런데 Claude 같은 에이전트가 점점 강력해지면서 Thariq는 마크다운의 한계에 부딪혔다고 말합니다.
100줄 넘어가는 마크다운 파일은 본인도, 동료도 안 읽게 된다.
본인이 직접 편집할 일이 거의 없어졌다. 편집은 결국 Claude한테 시킨다. → 마크다운의 가장 큰 장점("사람이 편집하기 쉬움")이 사라진다.
더 풍부한 시각화, 색상, 다이어그램을 원하는데 마크다운으론 안 된다.
결과를 동료와 공유하기 어렵다. 첨부 파일로 보내야 한다.
Opus 4.7의 1M 토큰 컨텍스트 시대에 토큰 효율은 더 이상 1순위가 아닙니다. 결과물의 표현력·가독성·공유 용이성이 우선이라는 게 Thariq의 결론입니다.
HTML이 마크다운보다 좋은 6가지 이유
1. 정보 밀도
HTML은 마크다운이 할 수 있는 헤더·서식뿐 아니라 거의 모든 정보를 효율적으로 표현합니다. Thariq가 정리한 표현 범위는 다음과 같습니다.
표 형식 데이터:
<table>디자인 데이터: CSS
일러스트레이션: SVG
코드 스니펫:
<script>태그인터랙션: HTML 요소 + JavaScript + CSS
워크플로: SVG + HTML
공간 데이터: 절대 위치 + canvas
이미지:
<img>태그
Claude가 읽을 수 있는 거의 모든 정보가 HTML로 표현 가능합니다. 표현 수단이 없으니까 마크다운에서는 비효율적인 짓을 합니다. ASCII 다이어그램, 유니코드 문자로 색깔 흉내내기(Thariq가 직접 공유한 예시) 같은 것들이요.
2. 시각적 명확성과 가독성
Claude가 더 복잡한 일을 하게 되면서 스펙·플랜도 점점 길어집니다. Thariq는 100줄 넘는 마크다운은 본인도 안 읽게 되고, 조직의 누구도 안 읽게 된다고 말합니다.
HTML 문서는 다릅니다. 탭, 일러스트, 링크로 구조를 시각적으로 정리할 수 있고, 모바일 반응형으로 만들면 디바이스에 맞춰 다르게 읽을 수도 있습니다.
3. 공유 용이성
마크다운 파일은 대부분의 브라우저가 기본 렌더링을 안 합니다. 그래서 이메일이나 메시지에 첨부로 보내야 합니다. HTML은 S3 같은 곳에 업로드만 하면 링크 하나로 끝납니다. 동료가 실제로 스펙·리포트·PR 설명을 읽을 확률이 훨씬 높아집니다.
4. 양방향 상호작용 (이게 진짜 핵심)
HTML에 슬라이더, 노브, 토글을 넣어 결과물을 직접 조작할 수 있습니다. 디자인 옵션을 즉석에서 바꿔보고, 알고리즘 파라미터를 돌려보며 결과를 확인합니다. 그리고 "copy as prompt" 버튼을 만들어두면 조정한 값이 다시 Claude Code 프롬프트로 돌아갑니다. 결과물이 정적 문서가 아니라 살아 있는 프로토타입이 됩니다.
5. 데이터 인제스천(Claude Code 전용)
"왜 Claude.ai나 Claude Design이 아니라 Claude Code에서 HTML을 만드나"의 답은 컨텍스트입 니다. Claude Code는 파일 시스템, MCP(Slack·Linear), 웹 브라우저(Claude in Chrome), git 히스토리까지 끌어와서 HTML을 만들 수 있습니다.
Thariq 본인이 이 글을 쓰면서 한 일이 좋은 예입니다. 자기 코드 폴더를 Claude Code에 읽힌 뒤 그동안 만든 HTML 파일을 다 찾아 분류하게 했고, 각 유형의 다이어그램이 들어간 HTML 한 장을 만들게 했습니다. 글 안의 다이어그램들이 그 결과물입니다.
6. 재미
Thariq의 표현 그대로: "It's joyful." Claude로 HTML 문서를 만드는 일은 그 자체로 더 즐겁고, 결과물에 대한 관여도와 애착이 높아집니다. 이 점만으로도 충분한 이유라고 그는 말합니다.
실전 활용 5가지 — 실제 프롬프트와 함께
Thariq가 본인 GitHub Pages에 "html-effectiveness" 갤러리로 공개한 5가지 카테고리를 그대로 가져왔습니다. 프롬프트는 한국어로 다듬어 바로 복붙해 쓸 수 있게 정리했습니다.
활용 1: 스펙·기획·탐색
복잡한 문제를 시작할 때 단순 마크다운 플랜이 아니라 HTML 파일들의 거미줄을 만든다고 Thariq는 말합니다. Claude Code에 브레인스토밍과 탐색을 시키고 → 마음에 드는 방향으로 확장 → 목업·코드 스니펫 → 구현 플랜. 마지막에 새 세션을 열어 이 파일들을 통째로 넘기면 구현 단계의 컨텍스트가 훨씬 풍부해집니다.
온보딩 화면을 어떤 방향으로 갈지 모르겠어.
완전히 다른 6가지 접근을 만들어줘 — 레이아웃·톤·정보 밀도를 다르게.
한 HTML 파일에 그리드로 나란히 배치해서 비교할 수 있게.
각 시안 옆에는 어떤 트레이드오프를 잡고 있는지 라벨로 붙여줘.구현 플랜을 HTML 한 파일로 자세히 작성해줘.
목업, 데이터 흐름, 검토할 만한 핵심 코드 스니펫까지 포함해서.
읽고 소화하기 쉽게 정리해.활용 2: 코드 리뷰와 코드 이해
코드는 마크다운 안에서 읽기가 어렵습니다. HTML이면 diff를 직접 렌더링하고, 인라인 주석을 달고, 플로우차트와 모듈 구조를 그릴 수 있습니다. Thariq는 본인이 만드는 모든 PR에 HTML 코드 익스플레이너를 첨부한다고 말합니다. GitHub 기본 diff 뷰보다 종종 더 잘 작동한다고요.
이 PR을 리뷰할 수 있게 HTML 아티팩트로 설명해줘.
streaming/backpressure 로직은 내가 익숙하지 않으니 거기 중점.
실제 diff를 렌더링하고, 인라인 마진 주석을 달아주고,
발견사항은 심각도별 색상으로 분류해줘.
개념 전달에 필요한 건 뭐든 넣어.활용 3: 디자인과 프로토타입
Claude Design이 HTML 기반인 이유가 있습니다. HTML은 디자인 표현이 매우 강력합니다. 최종 결과물이 HTML이 아니어도(React, Swift 등) Claude는 HTML에서 디자인을 스케치한 뒤 원하는 언어로 옮길 수 있습니다. 인터랙션이나 애니메이션 프로토타입도 가능합니다. 슬라이더와 노브를 넣어 정확히 원하는 값을 찾아낼 수 있어요.
새 체크아웃 버튼 프로토타입을 만들고 싶어.
클릭하면 플레이 애니메이션 뒤에 빠르게 보라색으로 바뀌게.
이 애니메이션을 시험할 수 있게 슬라이더와 옵션을 여러 개 넣은 HTML 파일을 만들어줘.
잘 맞는 파라미터를 복사할 수 있는 copy 버튼도.활용 4: 리포트·연구·학습
Claude Code는 여러 데이터 소스(Slack, 코드베이스, git 히스토리, 인터넷)를 가로질러 정보를 합성하는 데 강합니다. 본인용, 팀 보고용, 리더십 보고용으로 매우 읽기 쉬운 리포트를 뽑을 수 있어요. 긴 HTML 문서, 인터랙티브 익스플레이너, 슬라이드/덱 형태 모두 가능합니다. 다이어그램은 SVG로.
Thariq가 본인이 든 예: 프롬프트 캐싱 관련 글을 쓸 때 git 히스토리를 다 읽힌 뒤 캐싱 변경 사항 전부를 HTML 리서치 파일로 정리하게 했다고요.
우리 rate limiter가 실제로 어떻게 동작하는지 모르겠어.
관련 코드를 읽고, HTML 한 페이지 익스플레이너로 만들어줘.
- 토큰 버킷 흐름 다이어그램
- 핵심 코드 스니펫 3~4개에 주석
- 맨 아래에 "주의할 점" 섹션
한 번만 읽고 이해할 수 있게 최적화.활용 5: 일회용 커스텀 편집 인터페이스 (가장 강력한 패턴)
이게 Thariq가 가장 좋아하는 패턴입니다. 텍스트로 설명하기 힘든 작업이 있을 때, "한 번 쓰고 버릴 에디터"를 HTML로 한 장 만들게 합니다. 제품이나 재사용 도구가 아니라 이번 한 번을 위한 전용 UI입니다.
핵심 트릭: 항상 export 버튼으로 끝낼 것. "copy as JSON" 또는 "copy as prompt" 버튼을 넣어 UI에서 한 작업을 다시 Claude Code에 붙여 넣을 수 있는 형태로 뽑아냅니다.
이 Linear 티켓 30개를 재우선순위화해야 해.
각 티켓을 카드로 만들어서 Now / Next / Later / Cut 컬럼 사이에서
드래그할 수 있는 HTML 파일을 만들어줘.
네가 추측한 우선순위로 미리 정렬해두고.
"copy as markdown" 버튼을 추가해서 최종 순서와
각 버킷마다 한 줄 근거를 내보낼 수 있게.이 시스템 프롬프트를 튜닝하는 중이야.
좌우 분할 에디터를 만들어줘.
왼쪽: 변수 슬롯이 하이라이트된 편집 가능한 프롬프트.
오른쪽: 샘플 입력 3개가 채워진 템플릿이 실시간 렌더링.
캐릭터/토큰 카운터와 copy 버튼도.활용 시나리오:
티켓·테스트케이스·피드백 재정렬·분류·버킷팅
구조화된 설정 편집 (feature flags, env vars, 제약 있는 JSON/YAML)
프롬프트·템플릿·카피를 실시간 미리보기로 튜닝
데이터셋 큐레이션 — 행 승인/거부, 예시 태깅, 선택분 내보내기
문서·트랜스크립트·diff 주석 달고 주석만 export
텍스트로 표현하기 힘든 값 (색상, easing curve, 크롭 영역, cron, regex) 정하기
어떻게 시작하나요
Thariq의 조언은 단순합니다. /html 같은 스킬을 굳이 만들지 마세요. "make a HTML file"이나 "make a HTML artifact"라고 그냥 요청하면 됩니다. 진짜 어려운 건 "내가 이 아티팩트로 뭘 하고 싶은지" 아는 것입니다. 여러 케이스를 직접 프롬프팅해보면서 감을 잡고, 나중에 필요해지면 스킬로 만드세요.
CLAUDE.md에 한 줄 추가해두면 매번 지시할 필요가 없어집니다.
복잡한 스펙·리포트·디자인 결과물은 기본적으로 HTML 파일로 출력한다.
짧은 회신, 일회용 노트는 마크다운으로 출력한다.자주 묻는 질문
토큰 효율은 떨어지지 않나요?
마크다운보다 토큰을 더 쓰는 건 맞습니다. 하지만 Thariq는 표현력 증가와 실제로 읽힐 확률이 훨씬 높아져서 결과적으로 더 좋은 산출물을 얻는다고 말합니다. Opus 4.7의 1M 컨텍스트에서는 토큰 증가가 체감 안 됩니다.
마크다운은 언제 쓰나요?
Thariq 본인은 "거의 안 쓴다"고 말하지만 자기는 HTML 맥시멀리스트라고 인정합니다. 현실적인 분기 기준은 "이 결과물을 다시 볼 일이 있는가?"입니다. 한 번 보고 버릴 거면 마크다운, 반복 열람·팀 공유·후속 편집이면 HTML.
HTML 파일은 어디서 여나요?
로컬에서 브라우저로 그냥 엽니다(Claude한테 열어달라고 해도 됩니다). 공유 링크가 필요하면 S3 같은 곳에 업로드.
마크다운보다 생성에 오래 걸리지 않나요?
오래 걸립니다. 2~4배 정도. Thariq는 그 시간만큼의 값어치는 한다고 말합니다.
버전 관리는요?
이게 HTML의 가장 큰 단점입니다. HTML diff는 노이즈가 많고 리뷰하기 어렵습니다. 마크다운 대비 단점이라고 본인도 인정.
Claude가 만든 HTML이 못생기지 않나요?
frontend-design 플러그인이 도움이 됩니다. 회사 스타일에 맞추고 싶다면 코드베이스를 Claude에 읽혀서 디자인 시스템 HTML 한 장을 미리 만들어두세요. 이후 HTML 파일들은 그 디자인 시스템 파일을 레퍼런스로 사용하면 됩니다.
한 발 더 — 나의 생각
이번 변화의 본질은 "출력 포맷 교체"가 아니라 에이전트와 사람이 협업하는 인터페이스가 통째로 바뀌는 신호라고 봅니다.
지금까지 LLM 출력은 "사람이 텍스트로 읽고 → 다른 도구로 옮기는" 일방향 흐름이었습니다. 마크다운은 그 흐름에 최적화된 포맷이었습니다. 그런데 HTML은 사람도, 다른 에이전트도, 다른 도구도 같이 다룰 수 있는 포맷입니다. Thariq가 가장 강조한 "활용 5: 일회용 커스텀 편집 인터페이스"가 이걸 정확히 보여줍니다. 결과물을 한 번 더 사람이 조작하고, 그 조작 결과를 다시 에이전트에 던지는 양방향 루프가 자연스러워집니다. 멀티 에이전트 협업이 이런 식으로 자라날 것 같습니다.
지피터스 멤버 입장에서는 두 가지를 당장 시도해볼 만합니다.
첫째, PR이나 보고서 1개를 HTML로 받아보세요. Thariq처럼 PR 익스플레이너부터 시작하면 만드는 데 부담이 적고, 동료가 읽을 확률 차이를 바로 체감하실 거예요. 안 읽힌다고 답답해하던 스펙·플랜이 갑자기 읽히기 시작합니다.
둘째, "일회용 편집기 패턴"을 한 번 써보세요. 30개 Linear 티켓을 재정렬해야 한다거나, feature flag 30개를 한꺼번에 손봐야 한다거나, 광고 카피 후보 20개를 A/B/C 카테고리로 분류해야 한다거나. 이런 작업을 텍스트 프롬프트로 끝내려고 끙끙대지 말고, 그 작업만을 위한 일회용 HTML 에디터를 Claude한테 만들게 시키는 발상의 전환이 진짜 생산성 변곡점이라고 느꼈습니다.
다만 한국 직장 환경에서 한 가지 함정도 짚어둡니다. 상사 보고용 결과물을 HTML로 받으면 윗선에서 "이걸 어떻게 봐?"가 됩니다. 결국 PDF나 PPT로 옮겨야 하는 경우가 많아요. 이때는 Claude한테 "PDF 인쇄용으로 한 페이지에 들어가게 레이아웃 짜줘"라고 부탁하면 됩니다. 또는 HTML을 슬라이드/덱 형태로 만들어달라고 해도 됩니다.
요약하자면 — 이 결과물을 다시 볼 일이 있는가, 누군가와 공유할 일이 있는가. 둘 중 하나라도 yes면 HTML로 받으세요. 마크다운으로 묵혀두기엔 Claude의 표현력이 이제 너무 아깝습니다.
원문: Using Claude Code: The Unreasonable Effectiveness of HTML — Thariq Shihipar (Anthropic Claude Code 팀)
시몬 윌리슨의 정리: Simon Willison — Unreasonable Effectiveness of HTML
저자 X: @trq212
플레이그라운드(양방향 인터랙션 예시): @trq212 playgrounds 트윗