AI 에이전트를 위한 HTML vs Markdown: Anthropic Claude Code 팀이 전환한 이유

2026년 5월 8일, Anthropic의 Claude Code 팀 엔지니어인 Thariq Shihipar는 AI 개발자 커뮤니티의 스크롤을 멈추게 하는 글을 발행했습니다. 제목은 "Using Claude Code: The Unreasonable Effectiveness of HTML"입니다.

48시간 만에 이 글은 X에서 75만 회 이상의 조회수, 14,000개의 좋아요, 30,000개의 북마크, 1,600개의 인용 게시물을 기록했습니다. Simon Willison은 이 글을 시사하는 바가 크다고 평했습니다. 개발자 생태계는 이전에는 진지하게 제기된 적 없던 질문으로 들끓었습니다. 우리 모두가 AI 에이전트와 소통하기 위해 사용해온 Markdown이라는 형식이, 사실은 잘못된 형식이라면 어떨까?

Thariq가 글과 함께 공개한 20개의 실제 HTML 산출물 갤러리가 뒷받침하는 이 답변은, 개발자들이 에이전트 출력을 바라보는 방식을 재편하고 있습니다.

Markdown이 1차전에서 승리한 이유

이 전환이 왜 중요한지 이해하려면, 애초에 Markdown이 기본값이 된 이유를 이해해야 합니다.

2022년, ChatGPT가 8,192토큰 컨텍스트 윈도우로 출시되었을 때, 모든 토큰은 소중했습니다. 동일한 콘텐츠에 대해 HTML은 Markdown보다 약 3배 많은 토큰을 소모합니다. HTML 문서는 약 8,000토큰인 반면, 동등한 Markdown은 약 2,800토큰입니다. 전체 컨텍스트 예산이 8K 토큰이고 출력이 입력을 잠식할 때, 5,000토큰을 절약한다는 것은 사라질 뻔한 여러 문단의 컨텍스트를 살리는 것을 의미했습니다.

Markdown은 비용 측면에서 그 싸움을 이겼습니다. 당시의 제약 조건을 고려하면 합리적인 선택이었습니다.

AI 개발자 커뮤니티에서 가장 영향력 있는 목소리 중 하나인 Simon Willison은 지난주 이를 인정했습니다. 그는 바로 그 이유 때문에 GPT-4 시절부터 LLM을 위해 Markdown을 작성해왔습니다. 그리고 그는 틀리지 않았습니다. 당시의 계산법으로 보면 누구도 틀리지 않았습니다.

하지만 그 계산법이 바뀌었습니다.

Claude Opus 4.7은 100만 토큰 컨텍스트 윈도우를 탑재하고 출시되었습니다. 이는 Markdown을 기본값으로 만든 8K 윈도우보다 122배 더 큽니다. 예산이 100만 토큰일 때, 2,800과 8,000의 차이는 잡음에 불과합니다. Markdown 기본값을 만든 제약은 사라졌지만, 그 기본값 자체는 거의 4년 동안 의문 없이 살아남았습니다.

HTML이 담을 수 있지만 Markdown이 담지 못하는 8가지

Thariq의 글은 에이전트 출력을 Markdown으로 강제할 때 잃게 되는 것들의 간단한 목록으로 시작합니다. 전체 목록은 원문을 읽어볼 가치가 있지만, 여기 8가지 범주를 정리했습니다.

1. 정렬과 셀 병합이 가능한 진짜 테이블. Markdown 테이블은 단순한 그리드를 넘어서면 깨집니다. HTML 테이블은 열 병합, 행 병합, 정렬을 지원하며 중요한 행을 한눈에 강조하도록 스타일링할 수 있습니다.

2. CSS로 스타일링된 시각적 계층 구조. Markdown에서 강조는 굵게, 기울임꼴, 코드 블록으로 제한됩니다. HTML은 색상, 크기, 간격, 테두리, 레이아웃을 추가합니다. 정보를 훑어볼 수 있게 만드는 시각적 어휘입니다.

3. 인라인 SVG 다이어그램. 이것이 가장 큰 차이입니다. Markdown에서 Claude는 ASCII 아트에 의존합니다. 막대 차트는 파이프 문자로, 색상 견본은 유니코드 블록으로, 화살표는 대시로 표현합니다. HTML에서는 진짜 벡터 그래픽을 그립니다. 확장 가능하고, 정확하며, 실제로 읽을 수 있습니다.

4. JavaScript 인터랙티비티. 접을 수 있는 섹션, 탭으로 구분된 코드 샘플, 실시간 필터, 드래그 앤 드롭. Markdown은 정적 매체입니다. HTML은 런타임입니다.

5. 단일 파일에 포함된 이미지. Base64로 인코딩된 이미지가 HTML 내부에 함께 있습니다. 깨진 참조 링크도, 파일을 찾을 수 없다는 대화도 없습니다.

6. 공간적 캔버스 레이아웃. 나란히 비교, 그리드 레이아웃, 여백 주석, 콜아웃 박스. Markdown은 위에서 아래로 흐릅니다. HTML은 원하는 곳 어디로든 흐릅니다.

7. 클릭 가능한 노드가 있는 워크플로우 다이어그램. 배포 파이프라인을 상자와 화살표로 그리고, 단계를 클릭하면 실행 내용, 소요 시간, 실패 경로가 표시됩니다. Markdown은 번호 매긴 목록만 제공합니다.

8. 자기 완결형 공유 가능한 산출물. 하나의 .html 파일. 더블 클릭하세요. 모든 다이어그램, 스타일, 인터랙티비티가 그대로 유지된 채 어떤 브라우저에서든 열립니다. 의존성도, 빌드 단계도, 설정 문제도 없습니다.

공통된 핵심: Markdown은 사람이 산문을 작성하기 위해 만들어졌습니다. HTML은 풍부한 정보를 렌더링하기 위해 만들어졌습니다. 출력이 계획서, 보고서, 리뷰, 프로토타입일 때 — README가 아닐 때 — 풍부한 정보를 위해 만들어진 형식이 승리합니다.

ASCII 다이어그램 세금

Thariq 갤러리의 한 예시가 어떤 논증보다 더 명확하게 요점을 보여줍니다.

Claude Code에 데이터셋을 분석하고 결과를 Markdown으로 출력하라고 요청하면, 다음과 같은 결과가 나옵니다.

Q1 Sales by Region
| Region  | Revenue  |
|---------|----------|
| North   | ████████ | $2.4M
| South   | ██████   | $1.8M
| East    | ████████ | $2.6M
| West    | ████     | $1.2M

이것이 Claude가 1990년대 README 형식에 강제로 맞춰질 때 하는 일입니다. 즉흥적으로 대처합니다. 유니코드 블록 문자로 막대 차트를 흉내 냅니다. 데이터 대신 외형적 근사에 토큰을 소비합니다.

같은 질문을 하고 Claude에게 HTML로 출력하라고 지시하면, 적절한 축, 비례하는 막대, 레이블, 범례가 있는 진짜 SVG 막대 차트를 그립니다. 같은 데이터, 같은 에이전트. 하지만 두 번째 출력은 동료가 실제로 열어보고, 읽고, 행동으로 옮기는 것입니다.

우리가 직접 테스트해보았습니다. 같은 데이터셋, 같은 Claude Code 세션, 다른 두 가지 형식 지시. HTML 버전은 수정 없이 브라우저에서 렌더링되었습니다. Markdown 버전은 세 번의 명확화 과정을 거쳤고, 결국 막대를 근사하는 유니코드 블록 문자에 머물렀습니다. 형식이 에이전트를 제약할 때, 출력 품질도 따라갑니다.

Thariq의 논지를 요약하면: 에이전트에 표현 범위가 넓은 매체를 주면, 에이전트는 그것을 사용합니다. ASCII로 제한하면, 에이전트는 보상하려 하지만, 서툽니다.

토큰 비용 논쟁 (그리고 더 이상 중요하지 않은 이유)

HTML 에이전트 출력에 대한 가장 흔한 반론은 예측 가능합니다. 토큰 비용이 더 많이 든다는 것입니다.

실제로 그렇습니다. Thariq는 이에 대해 투명합니다. HTML 출력은 동등한 Markdown의 약 24배 토큰을 사용합니다. 2,800토큰의 Markdown 문서가 8,00011,000토큰의 HTML 문서가 됩니다.

하지만 이 반론은 Thariq와 다른 사람들이 지적했듯이, 2022년에는 참이었지만 지금은 무효인 가정에 기반합니다. 컨텍스트 윈도우가 8,192토큰일 때, 5,000토큰의 오버헤드는 치명적입니다. 컨텍스트 윈도우가 100만 토큰일 때, 이는 예산의 0.5%입니다.

Claude Opus 4.7, Gemini 3, GPT-5.5 — 2026년 중반의 최첨단 모델들은 모두 수십만에서 수백만 토큰 범위에서 작동합니다. Markdown을 필요하게 만든 토큰 절약 경제는 HTML을 실현 가능하게 만든 풍요 경제로 대체되었습니다.

더 중요한 것은, Thariq가 토큰 비용은 잘못된 지표라고 주장한다는 점입니다. 올바른 지표는 출력이 실제로 사용되는지 여부입니다. 아무도 읽지 않는 2,800토큰 Markdown 계획서는 모든 비용을 소모하고 아무것도 제공하지 않습니다. 열어보고, 이해하고, 실행에 옮겨지는 8,000토큰 HTML 계획서는 더 많은 토큰을 소모하고 가치를 제공합니다.

HTML이 Markdown을 능가하는 5가지 실무 활용 사례

Thariq의 20개 HTML 산출물 갤러리는 9개 범주에 걸쳐 있습니다. 이 중 5가지는 Claude Code를 넘어 모든 AI 에이전트 워크플로우에 일반화될 수 있는 것들입니다.

1. 명세서 및 구현 계획서

Markdown 명세서와 HTML 명세서의 차이는 텍스트 벽과, 타임라인, 데이터 흐름 다이어그램, 인라인 목업, 색상으로 심각도를 표시한 위험 테이블이 있는 문서의 차이입니다. 구현자는 두 번째 것을 엽니다. 첫 번째 것은 훑어봅니다.

2. AI 코드 리뷰

여백 주석, 심각도 태그, 점프 링크로 렌더링된 diff는 터미널을 스크롤하는 것보다 근본적으로 훑어보기 쉽습니다. HTML 버전은 전/후 비교를 나란히 렌더링하는 것도 지원합니다. 이는 어떤 순차적 형식보다도 변경 사항을 더 효율적으로 전달하는 공간적 레이아웃입니다.

3. 디자인 및 프로토타입

HTML은 디자인 시스템이 배포되는 매체입니다. 토큰은 견본이 됩니다. 컴포넌트는 컨택트 시트가 됩니다. 지속 시간과 이징을 위한 슬라이더가 있는 애니메이션 샌드박스는 산문 한 문단이 결코 전달할 수 없는 것을 5초 만에 알려줍니다. 실제 클릭 스루 동작으로 연결된 네 개의 화면은 읽는 것이 아니라 느낄 수 있는 프로토타입입니다.

4. 연구 및 보고서

접을 수 있는 섹션, 탭으로 구분된 코드 샘플, 여백의 용어집이 있는 해설서는 동일한 내용을 선형적으로 나열한 것과 다르게 읽힙니다. 작은 차트와 색상 타임라인이 있는 주간 현황 보고서는 사람들이 훑어보는 것을 실제로 읽는 것으로 바꿉니다. 분 단위 타임라인과 로그 발췌문이 있는 포스트모템은 팀이 무시하지 않고 참조하는 문서입니다.

5. 커스텀 편집 인터페이스

이것이 가장 급진적인 범주입니다. Thariq는 일회성 HTML 편집기를 시연합니다. 30개의 티켓을 Now, Next, Later, Cut으로 드래그하고 결과를 Markdown으로 내보내는 티켓 분류 보드, 의존성 경고와 diff 복사 버튼이 있는 기능 플래그 편집기, 실시간 재렌더링이 있는 프롬프트 튜너.

이것들은 제품이 아닙니다. 필요할 때 생성되고, 한 번 사용되고, 버려지는 일회성 도구입니다. 이러한 범주의 산출물은 Markdown에서는 존재하지 않습니다. 에이전트가 출력 기본 요소로서 HTML, CSS, JavaScript에 접근할 수 있을 때만 존재합니다.

진짜 이유: 나는 Markdown 계획서 읽기를 멈췄다

DIY Smart Code의 비디오 분석 마지막 부분에는 전체 전환을 설명하는 한 줄이 숨어 있습니다.

나는 Markdown 계획서 읽기를 멈추고 Claude가 모든 선택을 하도록 내버려두었다.

이것이 Thariq가 전환한 실제 이유이며, 토큰 수, SVG 충실도, 어떤 기능 비교보다 더 중요합니다.

에이전트 출력이 읽을 수 없는 Markdown 벽일 때, 인간은 루프에서 빠져나갑니다. 계획서를 검토하지 않습니다. 실수를 발견하지 못합니다. 판단력을 적용하지 않습니다. 그냥 괜찮아 보인다고 말하고 배포합니다. 아니면 더 나쁘게, 파일을 열어보지도 않습니다. 에이전트는 잘 작동했습니다. 형식이 그 작업을 보이지 않게 만들었습니다. 이것은 오늘날 AI 에이전트가 제공할 수 있는 것을 제한하는 능력 격차와 동일한 역학입니다. 출력은 기술적으로 정확하지만, 형식이 필요한 인간에게 도달하지 못하기 때문에 실질적으로 사용할 수 없습니다.

HTML 출력은 이 역학을 뒤집습니다. 출력이 시각적이고, 구조화되어 있으며, 훑어볼 수 있을 때, 인간이 루프로 다시 들어옵니다. 다이어그램을 보고 "저 흐름이 잘못되었네"라고 생각합니다. 접을 수 있는 섹션을 열고 잘못된 가정을 발견합니다. 분류 보드에서 티켓을 드래그하여 우선순위를 조정합니다. 형식이 인간이 의사 결정 과정에 머무를지 완전히 위임할지를 결정합니다.

이것이 AI 지원 워크플로우를 구축하는 누구에게나 가장 중요하게 여겨져야 할 논증입니다. 목표는 토큰 비용을 최소화하는 것이 아닙니다. 목표는 인간-에이전트 협업의 질을 최대화하는 것입니다. 그리고 협업을 더 쉽게 만드는 형식이, 토큰 수와 무관하게 더 나은 결과를 만들어냅니다.

AI 생성 HTML을 퍼블리싱하는 방법

에이전트가 SVG 차트가 포함된 연구 보고서, 주석이 달린 diff가 있는 코드 리뷰, 클릭 가능한 화면이 있는 프로토타입 등 자기 완결형 HTML 파일을 생성하면, 두 번째 질문에 직면합니다. 그것을 어디에 둘 것인가?

로컬 파일 시스템의 .html 파일은 자신에게만 유용합니다. 에이전트 출력의 가치는 URL을 가질 때 — 팀과 공유하고, Slack 스레드에 임베드하고, 이해관계자에게 보낼 수 있을 때 — 배가됩니다. HTML을 작성할 수 있지만 퍼블리싱할 수 없는 AI 에이전트는 초안은 쓸 수 있지만 인쇄할 수 없는 작가와 같습니다. 출력은 존재하지만, 누구에게도 도달하지 못합니다.

오늘날 개발자들이 사용하는 세 가지 접근 방식입니다. 가장 수동적인 것부터 가장 덜 수동적인 순서로.

GitHub Pages

레포지토리에 푸시하고, CI 빌드를 기다리고, URL을 얻습니다. 영구적인 문서 페이지와 프로젝트 사이트에 잘 맞습니다. 에이전트가 오늘 아침에 생성한 일회성 보고서에는 과합니다. 모든 퍼블리시마다 Git 커밋이 필요합니다. 즉, 에이전트에 레포지토리 접근 권한이 필요하고, 모든 일회성 산출물이 영구적인 이력을 만듭니다.

수동 클라우드 업로드 (S3, R2)

HTML 파일을 버킷에 업로드하고, 공개 접근을 구성하고, CORS를 관리하고, 캐시 무효화를 처리합니다. 이것은 작동하지만, 인프라 작업입니다. 에이전트가 처리해주길 바랐던 바로 그런 종류의 일입니다. 에이전트 보고서를 퍼블리싱하기 위해 버킷 정책을 구성하고 있다면, 자동화는 이미 깨진 것입니다.

에이전트 네이티브 퍼블리싱 플랫폼

세 번째 범주는 Thariq가 설명하는 워크플로우를 위해 목적에 맞게 구축된 것입니다. 에이전트가 출력을 생성하고, 퍼블리싱 레이어가 인간의 개입 없이 나머지 모든 것을 처리합니다.

이러한 플랫폼은 프로그래매틱 접근을 위해 설계되었습니다. 웹 대시보드도, 수동 구성도, CMS 로그인도 없습니다. CLI 또는 API를 통해 콘텐츠를 수락하고, 렌더링하고, 공개 URL을 반환합니다. 에이전트가 전체 파이프라인을 제어합니다.

예를 들어, AnyCap과 같은 플랫폼은 에이전트에 완전한 퍼블리싱 파이프라인을 구성하는 기능 집합을 제공합니다. 이는 AI로 즉시 웹 퍼블리싱하기 가이드에서 다룬 것과 동일한 패턴입니다.

• 클라우드 스토리지 (Drive) — 에이전트가 생성된 이미지, CSV 내보내기 및 기타 자산을 영구적인 클라우드 스토리지에 업로드합니다. 깨진 파일 경로도, 수동 업로드 단계도 없습니다.
• 페이지 배포 — 단일 명령으로 HTML 또는 Markdown 파일을 라이브 공개 웹 페이지로 변환합니다. anycap page deploy report.html --title "Q2 분석"이 전체 퍼블리싱 단계입니다.
• 다중 형식 지원 — 플랫폼이 Markdown과 HTML을 모두 네이티브로 렌더링합니다. 에이전트는 속도를 위해 Markdown으로 시작하고, SVG 다이어그램, 스타일링된 테이블, 인터랙티브 요소가 필요할 때 HTML로 전환할 수 있습니다. 모두 동일한 명령으로 배포됩니다.
• 통합 CLI — 페이지를 퍼블리싱하는 동일한 도구가 웹 검색, 이미지 생성, 웹 크롤링도 처리합니다. 에이전트는 하나의 작업을 완료하기 위해 5개의 서비스를 오가지 않습니다. 단일 런타임에서 연구하고, 차트를 생성하고, 퍼블리싱합니다.

실제로 완전한 파이프라인은 다음과 같습니다.

# 1. 에이전트가 주제를 연구합니다
anycap search --prompt "최신 Q2 실적 데이터" --json > research.json

# 2. 에이전트가 히어로 차트를 SVG로 생성합니다
anycap image generate --prompt "Q2 매출 막대 차트, 깔끔한 기업 스타일" \
  --model nano-banana-2 -o chart.png

# 3. 에이전트가 자산을 클라우드 스토리지에 업로드합니다
anycap drive upload chart.png

# 4. 에이전트가 자기 완결형 HTML로 보고서를 작성합니다
# (Claude Code가 차트가 포함된 HTML 파일을 출력합니다)

# 5. 에이전트가 페이지를 퍼블리싱합니다 — 단일 명령, 라이브 URL
anycap page deploy q2-report.html \
  --title "Q2 2026 실적 보고서" \
  --description "인터랙티브 차트가 포함된 AI 생성 분기별 분석"

인간이 CMS를 건드리지 않았습니다. 호스팅이 구성되지 않았습니다. 에이전트가 연구하고, 시각 자료를 생성하고, 퍼블리싱했습니다. 모두 단일 CLI를 통해 이루어졌습니다.

어떤 접근 방식을 사용해야 할까요?

올바른 선택은 워크플로우에 따라 다릅니다. 에이전트가 팀과 공유해야 하는 보고서를 주당 10개 출력한다면, 에이전트 네이티브 퍼블리싱 레이어는 즉시 그 가치를 증명합니다. 한 달에 한 페이지를 퍼블리싱한다면, GitHub Pages로 충분합니다.

형식 전환 — Markdown에서 HTML로 — 과 배포 전환 — 로컬 파일에서 라이브 URL로 — 은 동전의 양면입니다. 하나는 출력을 읽을 가치가 있게 만듭니다. 다른 하나는 공유할 가치가 있게 만듭니다.

에이전트 출력에 HTML과 Markdown 중 언제 무엇을 사용할까

HTML로의 전환이 교조적인 것은 아닙니다. 어떤 출력은 Markdown이 더 낫습니다. 결정 프레임워크는 간단합니다.

Thariq가 암묵적으로 제안하는 경험 법칙: 사람이 읽을 것으로 예상된다면, HTML을 고려하세요. 순수하게 기계 대 기계라면, Markdown으로 충분합니다.

결론

Markdown이 AI 에이전트 출력의 기본 형식이 된 것은 최선의 형식이었기 때문이 아니라, 심각한 토큰 제약 시대에 가장 저렴한 형식이었기 때문입니다. 그 시대는 끝났습니다.

Thariq Shihipar가 주장하고 20개의 실제 산출물로 입증하는 전환은, 실제로 HTML 대 Markdown에 관한 것이 아닙니다. AI 에이전트 출력을 기계가 파싱할 것으로 취급할지, 인간이 소비할 것으로 취급할지에 관한 것입니다. 4년 동안, 경제성이 강제했기 때문에 우리는 전자를 위해 최적화했습니다. 경제성이 더 이상 우리를 강제하지 않습니다.

에이전트는 더 나아지고 있습니다. 컨텍스트 윈도우는 더 커지고 있습니다. 출력은 더 복잡해지고 있습니다. 이제 형식이 따라잡을 때입니다.

AnyCap 팀 작성. 우리는 개발자들이 AI 에이전트로 구축하는 방식을 형성하는 도구, 형식, 워크플로우를 분석합니다.

더 읽어보기:

• Thariq Shihipar 원본 글 갤러리: 20가지 HTML 효과성 예시
• Thariq의 글 발표 X 스레드
• DIY Smart Code 비디오 분석: Markdown이 내 AI 워크플로우를 망가뜨렸다 (HTML이 고쳤다)