Claude Code로 HTML 쓰기: 마크다운을 버리고 HTML을 출력 포맷으로 택한 이유
목차
개요
Anthropic Claude Code 팀의 Thariq(@trq212)가 “Using Claude Code: The Unreasonable Effectiveness of HTML”이라는 글에서, 에이전트의 출력 포맷으로 마크다운 대신 HTML을 쓰게 된 이유를 정리했습니다. 마크다운은 에이전트가 사람과 소통하는 지배적 포맷이 됐습니다. 단순하고, 이식성이 좋고, 어느 정도 리치 텍스트가 되고, 사람이 직접 편집하기 쉽기 때문입니다. 하지만 에이전트가 점점 강력해지면서, 글쓴이는 마크다운이 오히려 제약이 된다고 느꼈습니다. 100줄이 넘는 마크다운 파일은 읽기 어렵고, 더 풍부한 시각화·색상·다이어그램을 원하며, 그것을 쉽게 공유하고 싶다는 것입니다.
게다가 이런 파일들을 점점 직접 편집하지 않게 됐습니다. 스펙, 레퍼런스 파일, 브레인스토밍 결과물로 쓰고, 편집할 때도 보통 Claude에게 시켜서 고칩니다. 그러면 마크다운의 가장 큰 장점 하나가 사라집니다. 그래서 글쓴이는 출력 포맷으로 HTML을 선호하게 됐고, Claude Code 팀의 다른 사람들도 점점 그렇게 쓰고 있다고 말합니다.
왜 HTML인가
정보 밀도
HTML은 마크다운보다 훨씬 풍부한 정보를 담을 수 있습니다. 헤더와 서식 같은 단순 문서 구조는 물론이고, 다음과 같은 것들도 표현할 수 있습니다.
- 표를 이용한 표 형식 데이터
- CSS를 이용한 디자인 데이터
- SVG를 이용한 일러스트레이션
- script 태그를 이용한 코드 스니펫
- JavaScript + CSS를 결합한 HTML 요소로 만드는 상호작용
- SVG와 HTML로 표현하는 워크플로우
- 절대 위치와 캔버스를 이용한 공간 데이터
- image 태그를 이용한 이미지
글쓴이는 “Claude가 읽을 수 있는 정보 중 HTML로 꽤 효율적으로 표현하지 못할 것은 거의 없다”고까지 말합니다. 이게 안 되면 모델은 마크다운 안에서 ASCII 다이어그램을 그리거나, 심지어 유니코드 문자로 색을 흉내 내는 비효율적인 짓을 하게 됩니다.
가독성과 공유 용이성
Claude가 더 복잡한 작업을 하면서 작성하는 스펙과 플랜도 점점 커집니다. 실제로 글쓴이는 100줄 넘는 마크다운 파일은 잘 안 읽게 되고, 조직의 다른 사람에게 읽히는 건 더더욱 어렵다고 말합니다. 반면 HTML 문서는 훨씬 읽기 쉽습니다. Claude가 탭, 일러스트레이션, 링크로 구조를 시각적으로 정리할 수 있고, 모바일 반응형으로 만들면 기기에 맞게 다르게 볼 수도 있습니다.
공유도 마찬가지입니다. 마크다운 파일은 대부분의 브라우저가 잘 렌더링하지 못해서 이메일·메시지에 첨부 파일로 붙여야 합니다. HTML은 S3 같은 곳에 업로드해 두면 링크 하나로 공유되고, 동료가 원하는 곳에서 열어 참조할 수 있습니다. 스펙·리포트·PR 설명이 HTML이면 실제로 누군가 그것을 읽을 확률이 훨씬 높아집니다.
양방향 상호작용과 데이터 수집
HTML은 문서와 상호작용하게 해 줍니다. 예를 들어 디자인을 조정하는 슬라이더나 노브를 추가하거나, 알고리즘의 옵션을 바꿔 가며 결과를 볼 수 있습니다. 그 변경 사항을 Claude Code에 다시 붙여 넣을 프롬프트로 복사하는 버튼을 만들어 달라고 할 수도 있습니다.
ClaudeAI나 Claude Design 대신 Claude Code로 HTML을 만드는 가장 큰 이유 중 하나는 Claude Code가 흡수할 수 있는 컨텍스트의 양입니다. 글쓴이는 이 글을 쓸 때 Claude Code에게 자신의 코드 폴더를 훑어 만들어 둔 HTML 파일을 모두 찾아 그룹화·분류하고, 각 유형을 대표하는 다이어그램을 담은 HTML 파일을 만들게 했습니다. 파일 시스템 외에도 MCP(Slack, Linear 등), 웹 브라우저(Claude in Chrome), git 히스토리 등에서 컨텍스트를 끌어올 수 있습니다. 그리고 무엇보다, HTML 문서를 Claude와 함께 만드는 일 자체가 더 즐겁고 창작에 더 몰입하게 만든다고 말합니다.
어떻게 시작하나
글쓴이는 사람들이 이 글을 읽고 /html 스킬 같은 걸로 만들까 봐 약간 두렵다고 합니다. 그런 데에 어느 정도 가치가 있을지는 몰라도, Claude에게 이걸 시키는 데 거창한 게 필요하지 않다는 점을 강조합니다. 그냥 “HTML 파일 만들어 줘” 또는 “HTML 아티팩트 만들어 줘”라고 하면 됩니다. 핵심은 그 아티팩트가 무엇을 하길 원하는지, 그걸 어떻게 쓸지를 아는 것입니다. 시간이 지나면 스킬을 만들 수도 있지만, 처음에는 그냥 맨바닥에서 프롬프트를 던지며 여러 경우에 어떻게 쓰는지 감을 잡으라고 권합니다.
활용 사례
글쓴이는 다양한 용도로 HTML 파일을 만들어 왔습니다.
스펙·계획·탐색
문제를 시작할 때 단순한 마크다운 플랜 대신 여러 HTML 파일의 묶음을 만듭니다. Claude Code에게 여러 옵션을 브레인스토밍하고 탐색안을 만들게 한 뒤, 하나를 골라 확장하고 목업이나 코드 스니펫을 만들고, 만족스러우면 구현 플랜을 작성하게 합니다. 플랜이 마음에 들면 새 세션을 열어 이 파일들을 모두 넘겨 구현하게 합니다. 검증할 때도 검증 에이전트에게 이 파일들을 읽히면 무엇이 필요한지에 대한 훨씬 넓은 컨텍스트를 갖게 됩니다.
예시 프롬프트는 이렇습니다.
1
2
3
온보딩 화면을 어떤 방향으로 갈지 모르겠어. 레이아웃, 톤, 밀도를 다르게 한
6가지 확연히 다른 접근을 만들어서 하나의 HTML 파일에 그리드로 나란히 비교할 수
있게 배치해 줘. 각각이 어떤 트레이드오프를 택했는지 라벨을 달아 줘.
코드 리뷰와 이해
코드는 마크다운에서 읽기 어렵습니다. HTML에서는 diff, 주석, 플로차트, 모듈을 렌더링할 수 있습니다. 에이전트가 작성한 코드를 이해하거나, 코드 리뷰를 받거나, PR을 리뷰어에게 설명하는 데 씁니다. 글쓴이는 이게 깃허브 기본 diff 뷰보다 잘 동작하는 경우가 많아서, 만드는 모든 PR에 HTML 코드 설명 파일을 첨부한다고 합니다.
디자인과 프로토타입
Claude Design이 HTML 기반인 이유는, 최종 결과물이 HTML이 아니더라도 HTML이 디자인 표현에 매우 강력하기 때문입니다. Claude가 HTML로 디자인을 스케치한 뒤 React, Swift 등 원하는 언어로 옮길 수 있습니다. 애니메이션·액션 같은 상호작용도 프로토타이핑할 수 있고, 슬라이더·노브를 만들어 원하는 값을 정확히 맞춰 볼 수 있습니다.
리포트·리서치·학습
Claude Code는 여러 데이터 소스를 가로질러 정보를 종합해 읽기 좋은 리포트로 바꾸는 데 매우 능합니다. Slack, 코드베이스, git 히스토리, 인터넷 등을 검색하게 해서 자신이나 리더십, 팀을 위한 읽기 좋은 리포트를 생성할 수 있습니다. 긴 HTML 문서, 인터랙티브 설명, 슬라이드/덱 형태로 조립할 수 있고, 다이어그램에는 SVG를 쓰게 하면 됩니다.
커스텀 편집 인터페이스
원하는 것을 텍스트로만 설명하기 어려울 때, 글쓴이는 Claude에게 지금 다루는 바로 그 데이터를 위한 일회용 에디터를 만들어 달라고 합니다. 제품이나 재사용 도구가 아니라, 이 한 조각의 데이터를 위한 단일 HTML 파일입니다. 핵심은 항상 export로 끝내는 것입니다. “copy as JSON”이나 “copy as prompt” 버튼으로, UI에서 한 작업을 다시 Claude Code에 붙여 넣을 수 있는 것으로 바꿉니다. 티켓·테스트 케이스·피드백을 재정렬·분류하거나, 제약이 있는 설정(피처 플래그, 환경 변수, JSON/YAML)을 편집하거나, 프롬프트·템플릿을 라이브 프리뷰와 함께 튜닝하거나, 데이터셋을 큐레이션하거나, 색·이징 커브·크롭 영역·cron 스케줄·정규식처럼 텍스트로 표현하기 까다로운 값을 고르는 데 씁니다.
자주 묻는 질문
글쓴이가 HTML 전환에 대해 반복해서 받은 질문들입니다.
| 질문 | 답변 |
|---|---|
| 토큰 효율이 떨어지지 않나 | 마크다운이 토큰을 덜 쓰지만, HTML의 표현력과 실제로 읽힐 확률이 높다는 점 덕분에 전체적으로 더 나은 결과를 얻음. Opus 4.7의 100만 토큰 컨텍스트에서는 늘어난 토큰 사용이 거의 체감되지 않음 |
| 지금도 마크다운을 쓰는 경우는 | 거의 모든 것에서 마크다운을 안 쓰게 됐지만, 글쓴이 본인이 HTML 극단주의 쪽에 가깝다는 점은 인정 |
| HTML 파일은 어떻게 보나 | 보통 로컬 브라우저에서 열거나(Claude에게 열어 달라고 할 수 있음), 공유 링크가 필요하면 S3에 업로드 |
| 마크다운보다 생성이 오래 걸리지 않나 | 더 오래 걸림. HTML은 마크다운보다 2~4배 느릴 수 있지만 결과가 그만한 값을 함 |
| 버전 관리는 | HTML의 가장 큰 단점 중 하나. HTML diff는 마크다운보다 노이즈가 많고 리뷰하기 어려움 |
| 못생기게 안 만들려면 | 프런트엔드 디자인 플러그인이 도움이 됨. 회사 스타일에 맞추려면 코드베이스를 가리켜 디자인 시스템 HTML 파일 하나를 만든 뒤, 그 파일을 다른 HTML 파일의 레퍼런스로 사용 |
의미와 시사점
이 글의 핵심은 “에이전트가 사람과 소통하는 매체를 다시 생각하라”는 것입니다. 에이전트가 직접 편집하기 쉬운 포맷이 필요했던 시절에는 마크다운이 정답이었지만, 이제는 사람이 편집하지 않고 에이전트에게 시키는 시대가 됐고, 그렇다면 더 표현력 있고 공유하기 쉬운 HTML이 더 나은 선택일 수 있다는 주장입니다. 글쓴이가 HTML을 쓰는 진짜 이유는 따로 있습니다. 플랜을 깊이 안 읽게 되면서 Claude의 선택을 그냥 맡겨 둘 수밖에 없게 될까 봐 두려웠는데, HTML 덕분에 오히려 그 어느 때보다 “루프 안에(in the loop)” 있다고 느낀다는 것입니다.
결론
마크다운은 단순함과 편집 용이성으로 에이전트의 기본 출력 포맷이 됐지만, 에이전트가 점점 복잡한 작업을 하면서 그 한계가 드러났습니다. HTML은 표·CSS·SVG·스크립트·상호작용을 담아 정보 밀도가 높고, 시각적으로 읽기 쉽고, 링크 하나로 공유되며, 슬라이더 같은 양방향 인터페이스까지 만들 수 있습니다. 거창한 스킬 없이 “HTML 파일 만들어 줘”라고 하는 것에서 시작해, 스펙·코드 리뷰·디자인·리포트·일회용 편집 도구로 넓혀 가 보라는 것이 글쓴이의 권유입니다. 생성이 2~4배 느리고 버전 관리가 까다롭다는 단점은 있지만, 결과가 그만한 값을 한다는 것이 핵심입니다.