Claude Code 팀에서 Markdown보다 HTML을 선호하는 이유 — 5가지 활용 패턴 완전 분석

Anthropic 엔지니어가 밝힌 "HTML의 놀라운 효율성" — 5가지 활용 패턴 완전 분석

---

들어가며: 2022년의 결정이 2026년에도 유효한가

2022년 ChatGPT가 8,192 토큰 컨텍스트 창으로 등장했을 때, Markdown은 최선의 선택이었다.

동일한 내용을 HTML로 표현하면 토큰을 약 3배 더 소비한다.
예산이 8K 토큰이고 출력이 입력을 잠식하는 상황에서 Markdown을 사용하는 것은 당연하였다.

 

2026년, 컨텍스트 창은 100만 토큰이 되었다.
이전의 계산이 더 이상 먹히지 않는다.

 

2026년 5월 8일, Anthropic의 Claude Code 엔지니어링 리드 Thariq Shihipar이
X에 "HTML의 놀라운 효율성"을 게시하였다.
24시간 안에 440만 뷰, 좋아요 8,200개, 북마크 15,700개를 기록하며 개발자 커뮤니티에서 가장 치열한 토론을 불렀다.

 

Simon Willison(Django 공동 창설자)의 반응이 이 글의 무게를 보여준다.
"GPT-4 시절부터 Markdown을 기본값으로 써왔다.
Thariq의 글이 그것을 재검토하게 만들었다, 특히 출력에서."

---

1. Markdown을 사용하는 게 제약이 되는 순간

Markdown이 에이전트 출력으로 도입된 것은 의도된 결정이 아니었다.
CLAUDE.md, AGENTS.md, SKILL.md가 설정 파일로 모든 프로젝트에 퍼지면서
Markdown이 에이전트 출력 형식으로도 자연스럽게 확산되었다.

 

문제는 용도의 미스매치이다.

 

Markdown의 원래 의도한 사용처는
"개발자가 에디터나 GitHub에서 읽는 것"이다.

 

에이전트가 생성하는 결과물의 독자는 다르다.
전화기로 보는 경영진, Slack에서 훑어보는 팀원, 링크를 클릭하는 클라이언트, 화요일 아침 그것을 열어보는 미래의 나 자신.

 

결국 핵심은 다음과 같다.
100줄이 넘는 Markdown 파일은 아무도 실제로 읽지 않는다.

Opus 4.7의 100만 토큰 컨텍스트가 가능해지면서 구현 계획과 기술 스펙이 수백 줄 단위로 생성된다.
그 결과물을 Markdown으로 받으면 스크롤만 내리다 끝난다.

---

2. HTML이 Markdown보다 더 잘 표현할 수 있는 것들

HTML이 Markdown보다 더 잘 표현할 수 있는 정보 유형이 많이 있다.

정보 유형	Markdown	HTML
테이블 데이터	기본 표	CSS 스타일 풍부한 표
다이어그램	ASCII 아트	SVG 일러스트
색상·스타일	불가	CSS 완전 지원
코드 조각	코드 블록	구문 강조 + 실행 버튼
상호작용	불가	슬라이더·토글·드롭다운
공간 데이터	불가	절대 위치·캔버스
공유	파일 첨부 필요	URL 링크

 

Markdown 안에서

• ASCII 다이어그램 생성,
• Unicode 문자로 색상 추정.
  이것은 표현력의 낭비이다.

▲ Claude Code에서 HTML 출력을 요청하면 탭·색상·다이어그램·상호작용이 포함된 풍부한 결과물이 생성된다

---

3. 5가지 핵심 활용 패턴

패턴 1. 스펙·계획·탐색

단일 Markdown 계획 대신 여러 HTML 파일의 묶음으로 작업을 시작한다.
레이아웃·톤·밀도가 다른 6가지 접근을 하나의 HTML 그리드로 만들고 각 선택의 트레이드오프를 표시하게 할 수 있다.

 

실전 프롬프트:

온보딩 화면에 대해 레이아웃·톤·밀도가 다른 
6가지 접근을 하나의 HTML 그리드로 만들어줘.
각 선택의 트레이드오프도 표시해줘.

패턴 2. 코드 리뷰와 코드 이해

HTML에서는 diff, 주석, 흐름도, 모듈 구조를 렌더링할 수 있다.

 

실전 프롬프트:

이 PR을 설명하는 HTML artifact를 만들어줘.
streaming/backpressure 로직에 집중하고,
실제 diff에 여백 주석을 달고 심각도별로 색을 입혀줘.

패턴 3. 디자인과 프로토타입

슬라이더나 노브를 넣어 디자인을 실시간으로 조정하고, 원하는 파라미터를 복사할 수 있다.

패턴 4. 보고서·리서치·학습

Git 기록, Slack, Linear 같은 MCP 소스를 읽어 탭·SVG 다이어그램·섹션 네비게이션이 있는 풍부한 리서치 파일을 만든다.

패턴 5. 맞춤형 일회용 편집 인터페이스

현재 작업 중인 데이터에 맞춘 일회용 HTML 편집기를 만들고,
마지막에 "copy as JSON" 또는 "copy as prompt" 버튼을 넣어 결과를 Claude Code에 다시 붙여넣을 수 있게 한다.

 

예시: 30개 Linear 티켓을 드래그 가능한 칸반 보드로 만들고, 최종 순서를 bucket별 한 줄 근거와 함께 Markdown으로 복사하는 버튼 포함.

---

4. 시작 방법: 딱 한 문장

별도 스킬 설치나 복잡한 설정이 필요 없다. 기존 프롬프트 끝에 한 문장을 추가하면 된다.

"HTML 파일로 만들어줘"
또는
"단일 HTML 파일로 만들어줘"
또는  
"HTML artifact를 만들어줘"

 

로컬 브라우저에서 열거나, Claude Code에 열어달라고 요청하거나, S3에 올려 링크로 공유할 수 있다.

---

5. 단점: 언제 Markdown이 여전히 나은가

HTML의 단점 두 가지:

① 생성 시간:
HTML은 Markdown보다 2~4배 더 걸린다.
빠른 간단한 응답이 필요한 경우에는 Markdown이 낫다.

② 버전 관리:
HTML diff는 Markdown보다 시끄럽고 리뷰하기 어렵다.
팀 전체가 소스를 검토해야 하는 장기 문서에는 적합하지 않다.

 

Markdown이 여전히 더 나은 경우:

• CLAUDE.md, AGENTS.md 같은 설정 파일
• 짧은 지침성 메시지
• 팀이 Git에서 직접 리뷰해야 하는 문서

HTML이 더 나은 경우:

• 100줄 이상의 계획·스펙·보고서
• 공유가 필요한 결과물
• 디자인·프로토타입·대시보드
• 한 번 읽히고 마는 일회용 데이터 편집기

▲ HTML 출력은 에이전트가 전달하는 정보를 사람이 실제로 읽고 상호작용할 수 있는 형태로 변환한다

---

마치며

"HTML artifact를 만들어줘" — 한 문장이다.
Thariq의 주장의 핵심은 복잡한 것이 없다. 그냥 요청하면 된다.

 

결과를 보면 왜 Claude Code 팀 내부에서 HTML이 기본 출력 형식으로 자리 잡았는지 이해하게 된다.

 

다음 계획을 HTML로 요청해보라.
그것을 처음으로 끝까지 읽게 될 가능성이 높다.

---

📎 참고 출처

• 원문(Thariq Shihipar, X): https://x.com/trq212
• Simon Willison: https://simonwillison.net/2026/May/8/unreasonable-effectiveness-of-html/
• pasqualepillitteri.it: https://pasqualepillitteri.it/en/news/2243/html-vs-markdown-claude-code-thariq-anthropic
• gogoai.xin: https://gogoai.xin/article/why-html-beats-markdown-for-claude-output