갑자기 오늘, 당신의 상식이 무너질 것입니다. 솔직히, 99%의 사람들이 여전히 Claude Code와 함께 Markdown을 사용하고 있습니다. Anthropic의 Claude Code 팀 내부자가 한 말은, "그만 하세요"였습니다. 그는 "Markdown 대신 HTML로 출력하는 것이 압도적으로 낫다"고 말했습니다.
Claude Code의 출력이 더욱 발전함에 따라, Markdown은 읽기 어렵고, 전달에 실패하며, 공유되지 않기 때문입니다.
반면, HTML을 사용하면:
- 그림을 넣을 수 있습니다
- 색상을 구분할 수 있습니다
- 탭으로 정리할 수 있습니다
- 슬라이더와 버튼도 만들 수 있습니다
- 브라우저에서 직접 공유할 수 있습니다
즉, Claude Code의 진정한 가치를 끌어내기 위해서는 "무엇을 출력하는가"뿐만 아니라 "어떤 형식으로 출력하는가"가 엄청나게 중요해집니다.
제가 단언합니다.
Claude Code 시대의 최적의 해결책은 단순한 Markdown이 아니라, HTML 우선(HTML-first)입니다.
사실, 이 기사가 나오기 전부터 ClaudeCodeStudio는 이 방법을 활용하여 슬라이드 자료가 한 방에 이런 퀄리티로 나오도록 보장하고 있었습니다 👇
이 글을 끝까지 읽으신다면, 왜 그것이 가능한지 이해하실 수 있을 테니, 꼭 읽어보세요!
그런데, 이런 경험 해보신 적 없나요?
- Claude Code가 계획을 작성해줬는데, 100줄이 넘어가자 흥미를 잃었다.
- Markdown으로 작성된 스펙을 팀과 공유했지만, 아무도 끝까지 읽지 않았다.
- ASCII 아트 다이어그램을 보고 "...이게 뭐지?"라고 생각했다.
- 색상이나 레이아웃으로 정보를 정리하고 싶었지만, Markdown으로는 표현할 수 없었다.
- 계획을 Slack에 붙여넣었지만, 첨부 파일로 묻혀버렸다.
이 모든 것은 "출력 형식의 문제"였습니다.
Claude Code 개발팀 멤버인 Thariq (@trq212)가 쓴 "Claude Code 사용하기: HTML의 비합리적인 효과"라는 제목의 글이 현재 X에서 1,100만 뷰 이상을 기록하며 입소문을 타고 있습니다 😳
Thariq는 Anthropic의 Claude Code 팀 멤버이자 YC W20 출신 엔지니어입니다. 즉, 매일 최전선에서 Claude Code를 사용하는 사람이 "Markdown 사용을 중단했습니다"라고 선언한 글인 셈이죠.
이번에는 그 내용을 구체적인 프롬프트 예시와 함께 알기 쉽게 설명해드리겠습니다 👇
원본 게시물은 여기: https://x.com/trq212/status/2052809885763747935
■ Markdown의 문제점은 무엇인가?
Markdown은 AI 에이전트와 인간 간의 의사소통 수단으로 수년간 사용되어 왔습니다. 간단하고, 어디서나 사용할 수 있으며, 어느 정도 리치 텍스트를 작성할 수 있습니다. 물론 Claude Code도 기본적으로 Markdown으로 출력합니다.
하지만 솔직히, 이런 경험 익숙하지 않나요?
Claude Code가 더 복잡한 작업을 처리할 수 있게 되면서, 출력하는 계획과 스펙은 점점 길어집니다. 100줄이 넘는 Markdown 파일을 정말 끝까지 읽으시나요?
Thariq는 글에서 이렇게 씁니다:
"저는 100줄이 넘는 Markdown 파일을 읽는 것을 어렵게 느낍니다."
게다가 요즘 우리는 파일을 직접 편집하는 경우도 훨씬 줄었습니다. 스펙의 참고 자료로 사용하거나 브레인스토밍의 출력물로 사용합니다. 편집할 때도 Claude에게 "이걸 고쳐줘"라고 요청합니다. 즉, Markdown의 가장 큰 장점인 "인간이 손으로 직접 편집하기 쉽다"는 점이 더 이상 의미가 없어졌습니다.
이것은 많은 Claude Code 사용자들이 무의식적으로 느껴왔던 문제를 훌륭하게 언어화한 것입니다.
■ HTML 옵션이 "비합리적으로 효과적인" 이유
Thariq가 제안하는 것은 Claude Code의 출력 형식을 Markdown에서 HTML로 변경하는 것입니다.
"HTML은 웹 페이지 만드는 거 아니야?"라고 생각할 수 있습니다. 하지만 HTML의 표현력은 Markdown과 비교할 수 없을 정도로 뛰어납니다.
HTML로 구체적으로 무엇을 표현할 수 있는지 살펴보겠습니다:
- 테이블을 사용한 구조화된 데이터
- CSS를 사용한 디자인 및 색상 지정
- SVG를 사용한 일러스트레이션 및 다이어그램
- Script 태그를 사용한 코드 스니펫
- JavaScript 및 CSS를 사용한 상호작용
- SVG와 HTML을 결합한 워크플로우 다이어그램
- 절대 위치 지정 또는 Canvas를 사용한 공간 데이터
- 이미지 태그를 사용한 이미지 삽입
Thariq는 이렇게 주장합니다:
"Claude가 읽을 수 있는 정보 집합 중에서 HTML로 상당히 효율적으로 표현할 수 없는 것은 거의 없다고까지 말할 수 있습니다."
Claude에게 ASCII 다이어그램을 그리게 하거나 유니코드 문자로 색상을 표현하게 해본 사람이라면 이 말의 무게를 이해할 것입니다. "페라리를 타고 편의점에 가는" 것과 같은 비효율에서 해방될 수 있습니다.
■ 정보 밀도가 압도적으로 다르다
HTML의 가장 큰 강점은 "정보 밀도"입니다.
동일한 내용을 Markdown과 HTML로 작성했을 때, HTML은 훨씬 더 많은 정보를 훨씬 더 읽기 쉽게 전달할 수 있습니다. 탭으로 전환하거나, 색상으로 구분하거나, 다이어그램을 삽입할 수 있습니다.
100줄의 Markdown을 읽고 싶지 않더라도, 동일한 양의 정보가 탭과 색상으로 정리된 HTML이라면 머릿속에 쏙 들어옵니다.
이것은 단순한 "외관의 문제"가 아닙니다. 읽히지 않는 스펙은 존재하지 않는 것과 같습니다. 읽히는 형식으로 출력하는 것은 작업의 질 자체에 직결됩니다.
■ 공유의 용이성
Markdown 파일을 누군가와 공유하려고 할 때, 보통 이런 일이 벌어집니다:
- Slack에 파일로 첨부 → 아무도 열지 않음
- 이메일에 첨부 → 아무도 열지 않음
- GitHub에 올림 → 비개발자는 접근 불가
HTML을 사용하면 S3에 업로드하고 링크를 보내기만 하면 됩니다. 브라우저만 있으면 누구나 읽을 수 있습니다. 반응형으로 만들어 모바일에서도 읽을 수 있게 할 수도 있습니다.
Thariq의 원문:
"스펙, 보고서 또는 PR 설명을 누군가가 실제로 읽을 확률은 HTML로 되어 있을 때 훨씬 더 높습니다."
이것은 미묘하지만 실무에서 매우 중요한 포인트입니다.
■ 양방향 상호작용의 혁명
여기서 HTML의 진가가 발휘됩니다.
HTML은 단순히 "읽는" 것만이 아닙니다. 조작할 수 있습니다.
예를 들어, 디자인을 미세 조정하는 경우를 생각해보세요. Claude Code에게 "슬라이더가 있는 HTML 파일을 만들어 줘"라고 요청하면, 애니메이션 속도, 이징, 색상을 실시간으로 조정할 수 있는 파일을 출력합니다. 마음에 드는 파라미터를 찾으면 "복사" 버튼을 눌러 Claude Code에 다시 붙여넣기만 하면 됩니다.
이러한 양방향 상호작용은 텍스트 프롬프트만으로는 절대 도달할 수 없는 정밀도로 조정을 가능하게 합니다.
"조금 더 오른쪽으로", "조금 더 빠르게", "이 색상이 아니야"라는 말로 전달해야 하는 스트레스에서 해방됩니다. 그냥 슬라이더를 움직이면 됩니다.
■ 구체적인 사용 사례 (프롬프트 예시 포함)
이 글에서 Thariq는 구체적인 프롬프트 예시와 함께 HTML 활용 패턴을 소개합니다. 실용적이어서 그대로 소개하겠습니다.
𝟭. 디자인, 계획 및 탐색
Claude Code에서 복잡한 작업을 할 때, 하나의 Markdown 계획 대신 여러 HTML 파일을 사용하여 "탐색의 그물"을 던집니다.
프롬프트 예시:
"온보딩 화면의 방향을 결정할 수 없습니다. 레이아웃, 톤, 밀도를 다양하게 하여 완전히 다른 6가지 접근 방식을 생성하고, 비교할 수 있도록 하나의 HTML 파일에 그리드로 배열해 주세요. 각각의 트레이드오프를 레이블에 작성해 주세요."
"상세한 구현 계획을 HTML 파일로 작성해 주세요. 목업, 데이터 흐름, 검토해야 할 중요한 코드 스니펫을 포함하세요. 읽기 쉽고 이해하기 쉽게 만들어 주세요."
𝟮. 코드 리뷰 및 이해
GitHub의 diff 화면보다 읽기 쉬운 코드 리뷰를 만들 수 있습니다.
프롬프트 예시:
"이 PR을 리뷰하기 위한 HTML 아티팩트를 만들어 주세요. 저는 스트리밍/백프레셔 로직에 익숙하지 않으므로, 그 부분에 집중해 주세요. 실제 diff를 인라인 여백 주석과 함께 렌더링하고, 중요도에 따라 색상으로 구분해 주세요."
Thariq는 "이제 모든 PR에 HTML 형식의 코드 설명을 첨부하고 있습니다."라고 씁니다.
𝟯. 디자인 및 프로토타이핑
Claude Design의 기초가 HTML인 것처럼, HTML은 디자인 표현에 매우 뛰어납니다. 최종 구현이 React나 Swift라 하더라도, 먼저 HTML로 스케치한 다음 다시 작성하는 워크플로우가 효과적입니다.
프롬프트 예시:
"새로운 체크아웃 버튼의 프로토타입을 만들고 싶습니다. 클릭하면 애니메이션과 함께 보라색으로 변해야 합니다. 각 애니메이션 파라미터를 슬라이더와 옵션으로 시험해 볼 수 있는 HTML 파일을 만들어 주세요. 잘 작동한 파라미터를 복사할 수 있는 버튼도 포함해 주세요."
𝟰. 보고서, 리서치 및 학습
Claude Code는 여러 데이터 소스의 정보를 종합하여 읽기 쉬운 보고서로 요약하는 데 능숙합니다. Slack, 코드베이스, Git 히스토리, 인터넷을 검색하여 리더십 보고서나 인시던트 보고서를 만들도록 할 수 있습니다.
프롬프트 예시:
"Rate limiter가 어떻게 작동하는지 이해가 안 됩니다. 관련 코드를 읽고 하나의 HTML 설명 페이지를 만들어 주세요. 토큰 버킷 흐름 다이어그램, 주석이 달린 3-4개의 중요한 코드 스니펫, 마지막으로 '주의사항' 섹션을 포함하세요. 한 번 읽으면 이해할 수 있도록 최적화해 주세요."
𝟱. 맞춤형 편집 인터페이스
개인적으로 가장 충격적이었던 사용 사례입니다. 일회용 HTML 편집기로 텍스트 상자로는 전달하기 어려운 작업을 실현합니다.
프롬프트 예시:
"30개의 Linear 티켓의 우선순위를 재정리하고 싶습니다. 각 티켓이 드래그 가능한 카드이고, Now / Next / Later / Cut의 네 개의 컬럼에 배치된 HTML 파일을 만들어 주세요. 처음에는 당신의 추측에 따라 배열해 주세요. 최종 순서를 각 버킷에 대한 한 줄 설명과 함께 내보낼 수 있는 'Markdown으로 복사' 버튼을 포함해 주세요."
"이 시스템 프롬프트를 조정하고 있습니다. 사이드 바이 사이드 편집기를 만들어 주세요. 왼쪽에는 편집 가능한 프롬프트(변수 슬롯 강조 표시), 오른쪽에는 템플릿이 실시간으로 반영되는 세 개의 샘플 입력을 배치하세요. 문자/토큰 카운터와 복사 버튼을 포함해 주세요."
이 아이디어 정말 놀랍지 않나요? 그 작업을 위해, 그 자리에서 필요한 UI를 생성하는 것입니다. 재사용될 필요가 없습니다. 완벽할 필요도 없습니다. 하지만 텍스트만으로 하는 것보다 100배는 효율적입니다.
■ 자주 묻는 질문에 대한 답변
글에서 Thariq는 HTML에 대한 일반적인 질문에도 답변하고 있습니다.
"토큰 효율이 나쁘지 않나요?"
→ Markdown보다 더 많은 토큰을 사용하는 것은 사실입니다. 하지만 표현력과 "실제로 읽힐 확률"을 고려하면 총체적으로 효율적입니다. Opus 4.7의 100만 토큰 컨텍스트에서는 증가분이 무시할 수 있는 수준입니다.
"생성하는 데 시간이 걸리지 않나요?"
→ Markdown보다 2-4배 더 오래 걸립니다. 하지만 Thariq 자신은 그만한 가치가 있는 결과라고 느낍니다.
"버전 관리는 어떻게 하나요?"
→ 솔직히 이것은 단점입니다. HTML diff는 Markdown보다 노이즈가 많고 리뷰하기 어렵습니다. 현재로서는 HTML의 가장 큰 약점 중 하나입니다.
"디자인이 촌스러워지지 않나요?"
→ Claude Code의 프론트엔드 디자인 플러그인을 사용하면 개선됩니다. 나아가 Claude Code가 회사의 코드베이스를 읽어 "디자인 시스템 HTML 파일"을 만들게 하고, 이후에는 그것을 참조하도록 하면 회사 스타일과 통일할 수 있습니다.
■ 왜 "지금" HTML인가?
이 글이 공감을 얻는 이유는 타이밍입니다.
이제 Claude Code가 복잡한 작업을 처리할 수 있게 되면서 출력물은 길고 밀도가 높아졌습니다. 그것을 계속해서 "약간 꾸며진 텍스트"에 불과한 형식인 Markdown으로 받는 것은 이제 병목 현상이 되었습니다.
Thariq의 결론은 이것입니다:
"HTML을 사용할 때, 그 어느 때보다 루프 안에 있다는 느낌을 받습니다."
모든 것을 Claude Code에 맡기는 대신, 출력물을 HTML로 만듦으로써 "인간의 이해, 판단, 피드백"의 사이클이 돌아갑니다. 이것이 AI와의 협업의 본질입니다.
■ 실천 포인트 요약
- 어려운 기술이나 설정은 필요 없습니다. Claude Code에게 "HTML 파일을 만들어 줘"라고 말하기만 하면 됩니다.
- 처음부터 스킬 파일을 만들려고 하지 마세요. 먼저 Raw 프롬프트로 시도해보세요.
- 계획, 리뷰, 보고서, 프로토타입 등 "사람들이 읽길 바라는 것"부터 시작하세요.
- 슬라이더나 복사 버튼과 같은 "상호작용성"을 의식하면 효과가 두 배가 됩니다.
- 생성된 HTML을 브라우저에서 열거나 S3에 업로드하여 공유하세요.
Markdown이 나쁜 것은 아닙니다. 하지만 Claude Code의 출력이 이렇게 고도화된 지금, 수신자의 형식도 업그레이드할 때가 되었습니다.
다음에 Claude Code가 계획을 만들게 할 때, 한 줄을 추가해보세요: "HTML로 만들어 줘." 그 차이에 놀라실 겁니다.
이 글이 조금이라도 도움이 되셨다면:
𝗖𝗹𝗮𝘂𝗱𝗲 𝗖𝗼𝗱𝗲 𝗦𝘁𝘂𝗱𝗶𝗼 @ 𝗝𝗮𝗽𝗮𝗻 (@ClaudeCode_love) 은
세 명의 Claude Code 매니아가 운영하는 계정입니다.
CLI 실전 활용과 자동화에 관한 정보를 매일 게시하고 있습니다.
현재 상장 기업과 AI 에이전트를 공동 개발 중입니다.
평소 게시물 👇
- Claude Code 및 Claude를 사용한 실제 제품 개발 사례
- Claude Code 활용법 / Vibe Coding / 개발 트렌드 정리
- 해외 Claude Code 최신 정보
개발 철학부터 디자인, 구현, 개선까지,
"빌드 완료"에 그치지 않고 실제 작동하는 제품을 세상에 내놓는 것을 목표로
해외 및 1차 정보를 요약하여 전달합니다.
관심 있으시면 팔로우하고 확인해보세요 👀 도움이 될 거라고 생각합니다!
