이제 Claude한테 마크다운 시키지 마세요 — Anthropic 직원이 직접 푼 HTML 워크플로우

핵심 요약 (TL;DR)

Anthropic Claude Code 팀의 Thariq Shihipar가 "AI 출력은 마크다운이 아니라 HTML로 받아라"는 워크플로우를 제안했고, Simon Willison이 5/8 Using Claude Code: The Unreasonable Effectiveness of HTML 포스트로 풀어 쓰면서 Hacker News 1면 502점·270댓글로 확산됐습니다. CLAUDE.md에 한 줄 추가하는 것만으로 산출물 퀄리티가 즉시 변합니다.

마크다운이 기본이었던 이유는 이미 옛날 이야기

AI 출력 기본 형식이 마크다운으로 굳어진 건 컨텍스트 윈도우가 작던 시절의 흔적입니다. 8,192 토큰 한도에서 모든 글자를 아껴야 하던 시기엔 마크다운이 합리적이었어요. 그런데 지금은 컨텍스트가 100만+로 확장됐고, 모델 자체가 HTML을 잘 짭니다.

Thariq Shihipar는 Anthropic Claude Code 팀에서 'ask user question' 도구를 만든 엔지니어로, 전 YC 파운더 출신입니다. 본인의 주장은 분명해요. "이제 출력 형태부터 바꾸자." 그 제안을 Simon Willison이 풀어 쓴 글이 5/8 HN 1면에 진입했습니다.

HTML 한 파일에 들어가는 것들

마크다운으로 표현하기 어렵거나 불가능한 것들이 HTML 한 파일에 자연스럽게 들어갑니다. 테이블, SVG 다이어그램, CSS 스타일, JavaScript 인터랙션, 이미지, 슬라이더와 노브 같은 UI 컴포넌트, 그리고 "이 프롬프트 다시 실행" 같은 버튼까지. 긴 문서엔 탭, 사이드 TOC, 접기 섹션, 반응형 레이아웃이 자동으로 들어가고, 모바일에선 알아서 재정렬됩니다.

공유 비용도 압도적으로 낮습니다. HTML 파일 하나면 S3나 사내 CDN에 올려 동료가 어디서든 클릭 한 번에 열람할 수 있어요. 사전 준비 없이 바로 쓰는 워크스페이스가 되는 거죠. Simon Willison 본인이 Linux 보안 익스플로잇 해설을 HTML로 받았더니, 스타일된 docs와 safety callouts, 번호 단계, 비교 테이블, visual hierarchy가 한 파일에 다 들어왔다고 기록했습니다.

지금 당장 적용하는 5분 작업

프로젝트 루트의 CLAUDE.md에 한 줄을 추가하면 됩니다. 예시는 이런 형태예요.

## 출력 형식 규칙

분석 결과, 코드 리뷰, 연구 보고서, 계획 문서는 기본적으로 단일 HTML 파일로 출력한다.
인라인 CSS와 JavaScript 포함, 인터랙티브 요소(접기 섹션, 탭, 색상 코딩)를 적극 활용.
출력 파일은 ./artifacts/ 디렉터리에 .html 확장자로 저장.

프롬프트 예시도 단순합니다.

PR 리뷰를 HTML artifact로 만들어 주세요.
diff를 인라인 마진 주석으로 렌더하고,
발견 사항을 심각도별로 컬러 코딩(red/yellow/green),
각 항목에 'GitHub에서 보기' 링크 포함.

결과물은 마크다운으론 도달할 수 없는 형태가 됩니다. 코드 리뷰가 클릭 가능한 워크스페이스가 되고, 연구 보고서가 인터랙티브 페이지가 되며, 클라이언트 보고용 산출물의 임팩트가 즉시 올라가요. 바이브코더 입장에서 'CLAUDE.md 한 줄로 산출물 퀄리티 2배'가 결코 과장이 아닙니다.

한 가지 trade-off

물론 단점도 있습니다. HTML은 마크다운보다 토큰이 더 들어요. 긴 채팅 컨텍스트가 비싼 케이스나 매 응답을 HTML로 받는 워크플로우는 비용 폭증을 만들 수 있습니다. 그래서 "기본 출력은 마크다운, 단 '산출물'·'보고서'·'리뷰' 명령일 때만 HTML"같이 트리거 기반 분기가 합리적입니다.

Anthropic 내부 사람이 직접 권한 워크플로우라는 점에서 Claude Code의 next default 방향을 짐작할 수 있습니다. 이번 분기 안에 공식 기능으로 들어올 가능성이 있어 보이고, 지금 미리 익혀 두는 것 자체가 학습 곡선 선점입니다.

FAQ

Q. Claude 외 다른 모델에서도 HTML 출력이 잘 되나요?
A. GPT-5.5나 Gemini도 HTML 출력 자체는 가능합니다. 다만 Anthropic 내부에서 명시적으로 권장한 워크플로우라는 점에서 Claude Code와 Opus 4.6/4.7 조합이 가장 안정적입니다. 다른 모델은 인라인 CSS와 JavaScript의 일관성이 다소 떨어지는 경우가 있어요.

Q. 모바일에서도 HTML 산출물이 잘 보이나요?
A. Thariq의 권고대로 반응형 CSS와 viewport 메타 태그를 프롬프트에 명시하면 모바일에서도 자동 재정렬됩니다. CLAUDE.md에 "모바일 반응형 필수" 같은 룰을 추가하면 더 안정적입니다.

Q. PDF로 변환해서 클라이언트에 보낼 수도 있나요?
A. 가능합니다. 브라우저의 인쇄 → PDF로 저장 기능만으로도 충분히 깔끔합니다. 단, 인터랙티브 요소(슬라이더·접기)는 PDF에서 사라지므로, PDF 변환을 염두에 둔다면 인쇄 친화적 CSS(@media print)를 함께 요청하는 게 좋습니다.

CLAUDE.md에 다섯 줄 추가하는 것만으로 이번 주 산출물의 인상이 완전히 바뀝니다. 지금 바로 한 파일 열고 출력 형식 규칙을 적어 보시는 걸 권합니다.