Using Claude Code: The unreasonable effectiveness of HTML
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
<!-- 단일 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
Related Papers
When to Vote, When to Rewrite: Disagreement-Guided Strategy Routing for Test-Time Scaling
Disagreement-guided routing boosts LLM accuracy on math and code by 3-7% with adaptive problem solving.
Less Is More: Engineering Challenges of On-Device Small Language Model Integration in a Mobile Application
Five failure modes and eight practical solutions emerged after five days of running on-device SLMs (Gemma 4 E2B, Qwen3 0.6B) with Wordle.
Dynamic Context Evolution for Scalable Synthetic Data Generation
A framework that completely eliminates duplication and repetition in large-scale synthetic data generation with LLMs using three mechanisms (VTS + Semantic Memory + Adaptive Prompt).
90%+ fewer tokens per session by reading a pre-compiled wiki instead of exploring files cold. Built from Karpathy's workflow.
This is a workflow sharing post about how pre-organizing a codebase in Wiki format can reduce token usage per Claude session by more than 90% instead of directly exploring the codebase every time.
I mass deleted 3 months of AI generated code last week. Here is what I learned.
A retrospective post by a developer who deleted 3 months' worth of code after over-relying on AI code generation, but access to the original post is blocked, making it impossible to verify the actual content.