Claude Code에서 HTML을 출력 포맷으로 쓰는 이유: Markdown보다 나은 점들

TL;DR Highlight

Claude Code 팀이 Markdown 대신 HTML을 LLM 출력 포맷으로 선호하기 시작한 이유와 그 실용적 장점을 정리한 글로, AI와 함께 문서/스펙/대시보드를 만드는 워크플로우에 직접적인 영향을 준다.

Who Should Read

Claude Code나 다른 LLM 코딩 에이전트를 써서 문서, 스펙, 대시보드, 리포트 등을 생성하는 개발자. 특히 Markdown으로 LLM 출력을 받다가 렌더링이나 공유 문제를 겪어본 사람.

Core Mechanics

Claude Code 팀 내부에서 LLM 출력 포맷으로 Markdown 대신 HTML을 선호하는 경향이 생기고 있다. 팀원들이 실제로 이 방식으로 문서와 스펙을 작성하고 있다는 점에서 단순한 실험이 아니라 실무 검증된 패턴이다.
HTML은 SVG(벡터 이미지), 인터랙티브 버튼, 커스텀 레이아웃, JavaScript 등 Markdown이 기본 지원하지 않는 요소들을 자연스럽게 포함할 수 있다. 복잡한 시각화나 동적 요소가 필요한 스펙 문서에서 특히 유리하다.
HTML 파일은 별도의 렌더러나 뷰어 없이 어떤 브라우저에서도 바로 열 수 있고, S3 같은 스토리지에 올리거나 이메일로 첨부하면 누구나 즉시 볼 수 있다. Markdown처럼 '이걸 보려면 특정 앱이 필요하다'는 장벽이 없다.
LLM이 HTML을 생성할 때 구조화된 포맷 덕분에 Markdown보다 더 일관되고 신뢰할 수 있는 출력을 낸다는 경험이 여러 사람에게서 공유됐다. JSON, XML과 마찬가지로 구조가 명확해서 모델이 덜 혼란스러워한다는 설명이다.
실제 사례로 definite.app 팀이 AI 에이전트가 YAML 스펙을 써서 대시보드를 렌더링하던 방식을 HTML 직접 생성 방식으로 전환했다. 생성 속도는 느려졌지만 커스터마이징 요청이 대폭 줄고 고객 만족도가 높아졌다.
비개발자들도 Claude Code나 OpenClaw로 HTML 파일을 만들어서 '스프레드시트', '프레젠테이션', '마케팅 자료' 등으로 활용하고 있다는 현장 관찰이 공유됐다. 이들은 결과물이 HTML인지도 모르지만 웹 기반 ChatGPT보다 훨씬 좋은 경험을 보고한다.
단일 `index.html` 파일에 의존성 없이 앱을 만드는 패턴(`In a single index.html, no dependencies, sparse styling, create an app that <idea>`)이 AI 이전부터 소규모 도구 제작에 쓰이던 방식이었고, AI 시대에 더욱 강력해졌다는 경험담이 있다.

Evidence

HTML이 인간과 LLM의 공동 편집을 어렵게 만든다는 우려가 제기됐다. Markdown은 사람이 직접 수정하기 쉽지만 HTML은 수정하려면 다시 LLM에 프롬프트를 넣어야 해서, 결국 문서 내용과 톤을 전적으로 LLM에 위임하는 방향으로 흐를 수 있다는 지적이다.
HTML이 Markdown보다 토큰을 훨씬 더 많이 소비한다는 트레이드오프가 지적됐다. 한 댓글은 이것이 Anthropic에게 유리한 전략(토큰 사용량 증가)이고, Claude Design 같은 HTML 마크업 도구 투자와 맞물려 벤더 락인 효과를 노린 것일 수 있다는 다소 비판적인 시각도 있었다.
Markdown이 원래 HTML의 shorthand로 설계됐다는 점을 상기시키며, Markdown 안에 HTML을 인라인으로 섞는 방식(CommonMark 스펙에서 지원)이 두 포맷의 장점을 모두 취할 수 있는 현실적인 중간 지점이라는 의견이 나왔다. VS Code에서 Cmd+Shift+V로 미리보기를 보면서 필요한 부분만 HTML 태그를 쓰는 식이다.
스펙 문서를 9개월 전부터 JSON으로 전환한 경험이 공유됐다. HTML과 같은 이유(구조화된 포맷에서 LLM이 더 신뢰할 만한 출력을 낸다)로 JSON을 쓰는데, 추가로 정적 분석(static analysis)을 돌려서 여러 스펙 문서 간 데이터베이스 필드 일치 여부를 자동 검증할 수 있다는 실용적 장점이 있다고 한다. YAML은 파일을 반으로 잘라도 유효한 YAML이 되는 등 신뢰성이 낮아서 비추천한다는 조언도 함께 달렸다.
Claude가 생성한 HTML 페이지들이 다 비슷하게 생겼다는 미적 피로감을 호소하는 댓글이 있었다. DALL-E 이미지가 너무 뻔하게 보이던 시절처럼, LLM이 만든 HTML도 '또 Claude가 만들었네'라고 바로 알아볼 수 있는 수준이 됐고, 기계는 평균으로 수렴하는 특성상 이 문제를 해결하기 어렵다는 지적이다.

How to Apply

LLM으로 리포트, 스펙 문서, 분석 자료를 만들 때 'Markdown으로 작성해줘' 대신 'In a single index.html, no external dependencies, create a report that...' 형태로 프롬프트를 바꾸면 브라우저에서 바로 열리고 이메일로 공유 가능한 독립 실행형 문서를 얻을 수 있다.
AI 에이전트가 대시보드나 리포트를 YAML/JSON 스펙으로 생성한 뒤 프론트엔드 프레임워크로 렌더링하는 파이프라인을 운영 중이라면, 에이전트가 HTML을 직접 생성하도록 전환을 검토해볼 만하다. definite.app 사례처럼 생성 속도는 느려지지만 커스터마이징 요청이 줄고 사용자 만족도가 올라갈 수 있다.
LLM 출력을 구조화된 포맷으로 받아야 하고 정적 분석이나 스키마 검증까지 필요한 경우라면 HTML보다 JSON이나 XML이 더 적합하다. 커스텀 스키마를 정의하고 여러 스펙 문서 간 필드 일관성을 자동 검증하는 데 유리하기 때문이다.
HTML과 Markdown 사이에서 고민된다면 Markdown 안에 HTML을 인라인으로 섞는 방식을 시도해볼 수 있다. 대부분의 텍스트는 Markdown으로 쓰고, SVG 삽입이나 특수 레이아웃이 필요한 부분만 HTML 태그를 직접 쓰면 VS Code 미리보기 등 기존 도구를 그대로 활용하면서 표현력을 높일 수 있다.

Code Example

snippet

<!-- 단일 HTML 파일로 의존성 없는 앱/문서를 만드는 기본 프롬프트 패턴 -->

프롬프트 예시:
"In a single index.html, no dependencies, sparse styling, create an app that [아이디어]"

<!-- 생성된 파일 구조 예시 -->
<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Tool</title>
  <style>
    /* Claude가 생성하는 sparse styling */
    body { font-family: system-ui; max-width: 800px; margin: 2rem auto; padding: 0 1rem; }
  </style>
</head>
<body>
  <!-- 인터랙티브 요소, SVG, 테이블 등 자유롭게 포함 가능 -->
  <script>
    // JavaScript도 인라인으로 포함 - 외부 의존성 불필요
  </script>
</body>
</html>

Terminology

static analysis코드나 문서를 실행하지 않고 구조를 분석해서 오류나 불일치를 자동으로 찾아내는 방법. 여러 JSON 스펙 파일에서 DB 필드명이 일치하는지 자동으로 검사하는 식으로 활용한다.

tokenLLM이 텍스트를 처리하는 단위. HTML은 태그가 많아서 같은 내용을 Markdown으로 표현할 때보다 토큰을 더 많이 소비하고, 이는 곧 API 비용 증가로 이어진다.

artifactLLM이 대화 맥락과 별개로 생성한 독립적인 파일이나 문서. Claude의 경우 Artifacts 기능으로 HTML, 코드 등을 별도 패널에서 렌더링해서 보여준다.

vendor lock-in특정 서비스나 플랫폼에 의존도가 높아져서 다른 곳으로 옮기기 어려워지는 상태. HTML 포맷 사용이 늘면 Anthropic의 토큰 매출이 늘고 사용자가 Claude 생태계에 더 묶이게 된다는 우려에서 나온 표현이다.

CommonMark여러 Markdown 구현체가 제각각이던 문제를 해결하기 위해 만든 Markdown 표준 스펙. 인라인 HTML 태그를 공식적으로 지원해서 Markdown과 HTML을 섞어 쓸 수 있다.

vibe codingAI가 코드 대부분을 생성하고 사람은 방향만 잡아주는 방식의 개발. 코드의 세부 구현보다 '이런 느낌으로 만들어줘'라는 의도 전달에 집중하는 개발 스타일을 일컫는다.