Claude Code 팀이 Markdown을 버린 이유 — HTML이 AI 시대의 진짜 커뮤니케이션 언어인 까닭

"저는 100줄이 넘는 AI 생성 마크다운 파일을 한 번도 끝까지 읽은 적이 없습니다." — Thariq, Anthropic Claude Code 팀 엔지니어

솔직하지 않나요? 이걸 가장 담담하게 인정한 사람이 바로 Claude Code를 만드는 팀의 엔지니어입니다.

Thariq(@trq212)가 2026년 X에 게시한 글 "Using Claude Code: The Unreasonable Effectiveness of HTML"은 AI 도구의 출력 형식에 대한 인식 전환을 촉구합니다. Markdown이 지배해온 자리를 HTML이 대체해야 한다는 주장인데, 이 글은 단순한 기술 트렌드가 아닙니다. AI와 인간이 협업하는 방식 자체를 다시 설계하자는 제안입니다.

이 글에서는 Thariq의 핵심 인사이트를 중심으로, Markdown의 한계와 HTML의 우위, 그리고 실전에서 바로 적용할 수 있는 5가지 사용 사례를 정리합니다.

Markdown은 왜 AI 도구의 표준이 됐을까

Markdown이 AI 에이전트의 기본 출력 형식이 된 데는 분명한 이유가 있었습니다.

AI가 짧은 메모, 요약문, 10~20줄의 설명을 쓰던 시절에 Markdown은 최적의 도구였습니다. 가벼웠고, 수동으로 편집하기 쉬웠고, GitHub나 Notion 같은 플랫폼에서 바로 렌더링됐습니다. "사람이 쓰고, AI가 보조하는" 시대의 형식으로는 최적이었죠.

그런데 지금은 상황이 달라졌습니다.

AI는 한 번에 1,000줄짜리 계획서를 씁니다. 전체 코드 리뷰를 한 번에 출력하고, 복잡한 플로우차트와 상세 스펙을 생성합니다. "AI가 쓰고, 사람이 읽는" 방향으로 역전이 일어난 것입니다.

이 변화 속에서 Markdown의 핵심 강점인 수동 편집 용이성은 사실상 무력화됐습니다.

Markdown의 4대 한계: 왜 지금 문제가 되는가

1. 정보 밀도의 한계

Markdown은 색상, 동적 다이어그램, 인터랙션을 표현할 수 없습니다. Claude가 유니코드 블록 문자(█ ▓ ░)로 차트를 흉내 내는 장면을 본 적 있으신가요? Thariq는 이것을 "우스꽝스럽다(comical)"고 직접 표현합니다. 도구가 표현 방식의 한계에 부딪혀 있다는 증거입니다.

2. 가독성의 한계

긴 Markdown 문서는 아무도 읽지 않습니다. Thariq 본인의 고백처럼, 100줄이 넘으면 작성자도 동료도 끝까지 읽지 않습니다. 정보가 담겨 있어도 전달되지 않는다면, 그 형식은 실패한 것입니다.

3. 공유의 한계

Markdown 파일은 브라우저에서 바로 열리지 않습니다. 파일 첨부나 복사-붙여넣기로만 전달됩니다. 팀원에게 리포트를 공유할 때마다 "렌더러 없어?" 같은 질문이 오가는 경험, 익숙하지 않으신가요?

4. 양방향성의 한계

Markdown의 수동 편집 용이성은 "사람이 파일을 고쳐야 할 때"를 전제합니다. 하지만 AI가 출력하고 사람은 읽기만 하는 흐름이 됐다면, 이 전제 자체가 무너집니다. 인터랙션이 일어나지 않는 형식은 단방향 텍스트 벽에 불과합니다.

HTML의 6대 우위: AI 시대의 진짜 언어

1. 압도적인 정보 밀도

HTML은 테이블, CSS 스타일링, SVG 벡터 그래픽, JavaScript 인터랙션, Canvas API, 이미지까지 표현할 수 있습니다. Claude가 읽고 생성할 수 있는 거의 모든 종류의 정보를 담을 수 있는 컨테이너입니다.

2. 시각적 명료성

탭으로 섹션을 분리하고, 일러스트로 구조를 시각화하고, 링크로 관련 정보를 연결합니다. 모바일 반응형으로 어떤 기기에서도 읽기 편한 형태가 됩니다. 텍스트가 아닌 인터페이스로서의 문서입니다.

3. 공유의 간결함

S3, Cloudflare Pages, GitHub Pages 중 어디든 업로드하면 링크 하나로 공유됩니다. 동료는 클릭 한 번이면 됩니다. 렌더러가 필요 없고, 파일 첨부가 필요 없습니다.

4. 양방향 인터랙션

이것이 HTML의 가장 강력한 우위입니다. 슬라이더로 디자인 파라미터를 실시간 조정하고, 드래그로 우선순위를 재배열하고, "copy as JSON" 버튼으로 Claude Code에 바로 피드백을 넣을 수 있습니다. 문서가 단순한 결과물이 아니라 협업 도구가 됩니다.

5. Claude Code의 컨텍스트 흡수력 극대화

Claude Code의 진짜 강점은 파일시스템, MCP(Slack, Linear), 브라우저, git history 등 다양한 소스를 맥락으로 흡수하는 능력입니다. HTML은 이 모든 소스를 하나의 파일에 통합해서 시각화하는 데 최적화돼 있습니다.

6. Joyful한 경험

Thariq가 직접 강조한 마지막 우위입니다. HTML 결과물을 만들고 보는 과정 자체가 재미있습니다. 이 경험이 사용자의 관여도를 높이고, 더 좋은 결과물로 이어집니다.

5가지 실전 사용 사례: 지금 바로 적용하기

사용 사례 1: 스펙 기획과 방향 탐색

단순한 .md plan 파일 대신, HTML로 여러 가지 방향을 나란히 비교하는 그리드를 만듭니다.

이런 상황에서: 온보딩 화면 방향을 정해야 하는데, 어느 쪽이 맞는지 감이 잡히지 않을 때

이런 프롬프트로:

I'm not sure what direction to take the onboarding screen.
Generate 6 distinctly different approaches—vary layout, tone, and density—
and lay them out as a single HTML file in a grid so I can compare them side by side.
Label each with the tradeoff it's making.

이런 결과가 나옵니다: 6가지 방향이 한 화면에 정렬돼 트레이드오프 레이블과 함께 표시됩니다. 팀원에게 링크 하나로 공유하고 즉시 피드백을 받을 수 있습니다.

사용 사례 2: 코드 리뷰와 이해

PR의 diff를 HTML로 렌더링하면 GitHub 기본 diff보다 훨씬 명확하게 변경 사항을 파악할 수 있습니다.

이런 상황에서: 스트리밍/백프레셔 로직이 낯설어서 PR 리뷰가 어려울 때

이런 프롬프트로:

Help me review this PR by creating an HTML artifact that describes it.
I'm not very familiar with the streaming/backpressure logic so focus on that.
Render the actual diff with inline margin annotations,
color-code findings by severity.

이런 결과가 나옵니다: 실제 diff에 인라인 주석이 달리고, 심각도별로 색상 코딩됩니다. 모듈 간 호출 그래프까지 시각화하면 복잡한 PR도 한눈에 파악됩니다.

사용 사례 3: 디자인 프로토타입

최종 구현 언어(Swift, React 등)와 무관하게 HTML로 먼저 스케치합니다. 슬라이더로 파라미터를 조정하고 마음에 드는 값을 복사하면 됩니다.

이런 상황에서: 체크아웃 버튼 애니메이션의 속도, 타이밍, 색상을 직접 조정해보고 싶을 때

이런 프롬프트로:

I want to prototype a new checkout button, when clicked it does a play animation
and then turns purple quickly. Create a HTML file with several sliders and options
for me to try different options on this animation,
give me a copy button to copy the parameters that worked well.

이런 결과가 나옵니다: 슬라이더로 애니메이션 지속 시간, 이징, 색상을 실시간 조정할 수 있고, "copy parameters" 버튼으로 최적값을 즉시 추출합니다.

사용 사례 4: 리포트와 학습 자료

Slack, 코드베이스, git history, 인터넷까지 다양한 소스를 통합해서 인터랙티브 HTML 리포트를 만듭니다.

이런 상황에서: 코드베이스의 rate limiter 동작 방식을 완전히 이해하고 싶을 때

이런 프롬프트로:

I don't understand how our rate limiter actually works.
Read the relevant code and produce a single HTML explainer page:
a diagram of the token-bucket flow, the 3–4 key code snippets annotated,
and a 'gotchas' section at the bottom.
Optimize it for someone reading it once.

이런 결과가 나옵니다: 토큰 버킷 플로우 다이어그램 + 주석이 달린 핵심 코드 스니펫 + 함정 섹션이 한 페이지에 담긴 학습 자료가 생성됩니다.

사용 사례 5: 커스텀 일회용 편집기(Throwaway Editor)

딱 지금 작업에만 맞는 단일 HTML 파일 에디터를 만들어 사용하고 버립니다. 중요: 반드시 export 버튼을 포함해야 합니다. "copy as JSON" 또는 "copy as prompt" 버튼이 없으면 작업 결과를 Claude Code에 다시 넣을 수 없습니다.

이런 상황에서: Linear 티켓 30개의 우선순위를 재정렬해야 할 때

이런 프롬프트로:

I need to reprioritize these 30 Linear tickets.
Make me an HTML file with each ticket as a draggable card
across Now / Next / Later / Cut columns.
Pre-sort them by your best guess.
Add a 'copy as markdown' button that exports the final ordering
with a one-line rationale per bucket.

이런 결과가 나옵니다: 드래그 앤 드롭으로 티켓을 재배치하고, "copy as markdown" 버튼으로 최종 순서와 근거를 즉시 추출합니다.

활용 영역: 피처 플래그 폼 에디터, 시스템 프롬프트 사이드바이 에디터, 색상·이징 커브·크론·정규식 같은 텍스트로 표현하기 어려운 값들을 시각적으로 조정할 때 모두 적용할 수 있습니다.

솔직한 트레이드오프

Thariq는 HTML의 단점도 명확히 인정합니다.

핵심은 균형입니다. 짧은 메모, 단순한 요약, 소스 코드 스니펫에는 여전히 Markdown이 더 적합합니다. HTML은 **"읽고 공유하고 인터랙션이 필요한 복잡한 결과물"**에 투자를 정당화합니다.

지금 바로 시작하는 방법

Thariq의 권고는 놀랍도록 단순합니다.

"별도 /html 스킬을 만들지 마세요. 그냥 'HTML 파일로 만들어줘' 또는 'HTML artifact로 출력해줘'라고 입력하면 됩니다."

새로운 도구를 설치하거나 복잡한 설정을 할 필요가 없습니다. Claude Code 프롬프트에 한 줄을 추가하는 것으로 충분합니다.

시작 단계별 권장 순서:

1. 첫 번째 시도: 다음 기획이나 리포트 요청에 "HTML 파일로 만들어줘" 추가
2. 반복 학습: 다양한 사용 사례에 시도하면서 어떤 상황에 가장 효과적인지 감각 파악
3. 패턴 정립: 팀이나 프로젝트에 맞는 자신만의 HTML 프롬프트 패턴 개발
4. 스킬화: 충분한 경험이 쌓이면 Claude Code 커스텀 스킬로 패키징

결론: 형식 경쟁이 아닌 협업 방식의 업그레이드

Markdown에서 HTML로의 전환은 단순히 파일 형식을 바꾸는 이야기가 아닙니다.

"AI가 보조하고 사람이 주도한다"는 패러다임에서 "AI가 출력하고 사람이 소비·반응한다"는 패러다임으로의 이동입니다. 이 변화에서 커뮤니케이션 형식도 함께 진화해야 합니다.

텍스트 벽이 아닌 인터페이스. 읽히지 않는 파일이 아닌 공유되고 상호작용하는 문서. Thariq의 말처럼, 이 전환은 단순한 효율 개선이 아니라 일하는 방식이 더 즐거워지는(Joyful) 경험이기도 합니다.

Claude Code를 쓰고 있다면, 오늘 당장 한 번 써보세요.

"HTML 파일로 만들어줘."

References

• Thariq(@trq212), "Using Claude Code: The Unreasonable Effectiveness of HTML", X(Twitter), 2026 — https://x.com/trq212/status/2052809885763747935
• Thariq(@trq212), HTML 사용 사례 쇼케이스 — https://thariqs.github.io/html-effectiveness
• Thariq(@trq212), 양방향 playgrounds 후속글 — https://x.com/trq212/status/2017024445244924382