AG 시대 MD 보다 HTML
에이전트 시대, Markdown보다 HTML이 강력해지는 이유
Markdown은 오랫동안 AI 에이전트가 사람과 소통하는 기본 파일 형식이었다.
단순하고, 어디서나 열리고, 어느 정도의 서식도 가능하다. 사람이 직접 수정하기도 쉽다. Claude는 이제 Markdown 안에서 ASCII 문자만으로 꽤 그럴듯한 다이어그램까지 그린다.
하지만 에이전트가 점점 더 강력해질수록, Markdown은 오히려 제한적인 포맷이 되고 있다.
100줄이 넘어가는 Markdown 파일은 읽기 어렵다. 더 풍부한 시각화, 색상, 다이어그램, 더 쉬운 공유 방식이 필요하다. 게다가 우리는 이제 이런 파일을 직접 많이 편집하지도 않는다. 대부분은 스펙, 참고 자료, 브레인스토밍 결과, 구현 계획, 리포트로 사용한다. 수정이 필요하면 직접 고치기보다 Claude에게 다시 고쳐달라고 한다.
그렇다면 Markdown의 가장 큰 장점이었던 “사람이 쉽게 편집할 수 있다”는 장점도 예전만큼 중요하지 않다. 그래서 최근 Claude Code 쪽에서는 Markdown 대신 HTML을 산출물 포맷으로 쓰는 흐름이 늘고 있다. 이유는 단순하다.
HTML은 더 많이 담을 수 있고, 더 잘 읽히고, 더 쉽게 공유되고, 때로는 문서가 아니라 작은 도구가 될 수 있기 때문이다.
왜 HTML인가
1. 정보 밀도가 높다
HTML은 Markdown보다 훨씬 풍부한 정보를 표현할 수 있다.
Markdown도 제목, 문단, 목록, 강조, 표 정도는 표현할 수 있다. 하지만 HTML은 거기서 멈추지 않는다.
HTML은 다음과 같은 것들을 모두 담을 수 있다.
표를 통한 정리된 데이터
CSS를 활용한 디자인 정보
SVG를 활용한 다이어그램과 일러스트
코드 스니펫
JavaScript와 CSS를 활용한 인터랙션
SVG와 HTML로 표현한 워크플로우
absolute position이나 canvas를 활용한 공간 정보
이미지 태그를 활용한 시각 자료
Claude가 읽을 수 있는 정보라면, 거의 대부분은 HTML로 꽤 효율적으로 표현할 수 있다. 이 점은 모델이 복잡한 정보를 사람에게 전달할 때 매우 중요하다.
Markdown만 사용할 때 모델은 종종 비효율적인 방식을 택한다. ASCII 문자로 다이어그램을 만들거나, 색상을 유니코드 문자로 흉내 내려고 한다.
Claude Code가 Markdown 안에서 색상을 표현하려고 시도한 예시
재미있긴 하지만, 이건 정보 전달 방식으로는 한계가 있다. HTML이라면 CSS와 SVG를 사용해 훨씬 명확하게 보여줄 수 있다.
2. 긴 문서를 훨씬 읽기 쉽게 만든다
Claude가 더 복잡한 일을 할 수 있게 되면서, Claude가 작성하는 스펙과 계획 문서도 점점 길어지고 있다.
실무에서는 100줄이 넘는 Markdown 파일을 끝까지 읽기 어렵다. 조직 안의 다른 사람에게 공유해도 마찬가지다. 긴 Markdown 문서는 만들어졌다는 사실만 남고, 실제로 읽히지 않는 경우가 많다.
HTML 문서는 다르다.
Claude는 HTML 안에서 문서를 시각적으로 구성할 수 있다. 탭, 카드, 섹션, 링크, 다이어그램, 색상, 반응형 레이아웃을 활용할 수 있다. 모바일에서는 모바일에 맞게, 데스크톱에서는 데스크톱에 맞게 읽히도록 만들 수도 있다.
같은 내용이라도 HTML로 만들면 “읽어야 하는 긴 문서”가 아니라 “둘러볼 수 있는 화면”이 된다.
이 차이는 생각보다 크다.
3. 공유하기 쉽다
Markdown 파일은 공유가 애매하다.
대부분의 브라우저는 Markdown을 기본적으로 예쁘게 렌더링하지 않는다. 그래서 이메일이나 메신저에 첨부파일로 보내야 한다. 받는 사람은 파일을 내려받아 열어야 하고, 그 과정에서 읽을 확률은 낮아진다.
HTML은 다르다.
S3, GitHub Pages, Vercel, Netlify 같은 곳에 올리면 링크 하나로 공유할 수 있다. 동료는 어떤 환경에서든 브라우저로 열어볼 수 있다.
스펙 문서든, 리포트든, PR 설명이든, 연구 정리든, 실제로 누군가 읽어야 한다면 HTML이 훨씬 유리하다.
문서의 가치는 “작성했다”가 아니라 “누군가 읽고 이해했다”에서 나온다.
HTML은 그 가능성을 높인다.
4. 읽는 문서를 넘어, 조작하는 도구가 된다
HTML의 가장 큰 장점은 양방향 상호작용이다.
Markdown은 기본적으로 읽는 문서다. HTML은 읽는 문서이면서 동시에 조작하는 도구가 될 수 있다.
예를 들어 버튼 애니메이션을 조정하고 싶다고 해보자. Claude에게 이렇게 요청할 수 있다.
새로운 체크아웃 버튼을 프로토타입으로 만들어줘. 클릭하면 짧은 애니메이션이 재생되고 빠르게 보라색으로 변하게 해줘. 속도, 색상, easing 값을 조정할 수 있는 슬라이더도 넣고, 마음에 드는 설정을 복사할 수 있는 버튼도 만들어줘.
그러면 HTML 파일 하나가 나온다.
그 파일 안에서 직접 값을 조정하고, 결과를 보고, 마음에 드는 설정을 복사해서 다시 Claude Code나 실제 코드에 붙여넣을 수 있다.
문서를 읽는 게 아니라 문서 안에서 실험하는 것이다.
이 패턴은 생각보다 넓게 적용된다.
Linear 티켓 30개를 Now / Next / Later / Cut으로 드래그해서 재정렬하기
feature flag 설정을 폼으로 편집하고 변경 diff 복사하기
시스템 프롬프트를 좌우 비교하면서 live preview 보기
데이터셋을 승인/거절/태깅하고 JSON으로 내보내기
문서나 diff에 annotation 달기
색상, easing curve, crop region, cron schedule, regex 같은 값을 UI로 선택하기
핵심은 마지막에 export 기능을 넣는 것이다.
Copy as JSON
Copy as Prompt
Copy as Markdown
Copy Diff
이 버튼이 있으면 HTML 안에서 사람이 조작한 결과를 다시 에이전트에게 넘길 수 있다.
이때 HTML은 단순한 문서가 아니라 사람과 에이전트 사이의 작업 인터페이스가 된다.
Claude Code로 HTML을 만드는 이유
그렇다면 왜 일반 Claude 채팅이나 Claude Design이 아니라 Claude Code로 HTML 파일을 만들까?
가장 큰 이유는 Claude Code가 훨씬 많은 컨텍스트를 읽을 수 있기 때문이다.
Claude Code는 로컬 파일 시스템을 읽을 수 있다. 코드베이스를 읽고, Git 히스토리를 읽고, MCP를 통해 Slack이나 Linear 같은 외부 도구의 정보도 가져올 수 있다. 브라우저 컨텍스트도 활용할 수 있다.
예를 들어 글을 쓰기 위해 Claude Code에게 이렇게 시킬 수 있다.
내 코드 폴더를 훑어서 지금까지 생성된 HTML 파일을 모두 찾아줘. 유형별로 분류하고, 각 유형을 다이어그램으로 보여주는 HTML 파일을 만들어줘.
Claude Code는 파일 시스템을 읽고, HTML 파일들을 분류하고, 다시 사람이 보기 쉬운 HTML 리포트로 만들어낼 수 있다.
즉, HTML은 Claude Code가 여러 데이터 소스를 흡수한 뒤 사람에게 다시 보여주는 고밀도 인터페이스가 된다.
무엇에 쓸 수 있을까
1. 스펙, 기획, 탐색
문제를 처음 탐색할 때 Markdown 계획서 하나보다 HTML 탐색 파일이 더 좋을 수 있다.
예를 들어 온보딩 화면 방향을 고민한다고 해보자. Claude에게 이렇게 요청할 수 있다.
온보딩 화면에 대해 6가지 완전히 다른 방향을 만들어줘. 레이아웃, 톤, 정보 밀도를 모두 다르게 하고, 하나의 HTML 파일에 그리드로 배치해서 비교할 수 있게 해줘. 각 안이 어떤 trade-off를 선택했는지도 표시해줘.
그러면 텍스트 설명만 보는 것보다 훨씬 빠르게 방향을 판단할 수 있다.
기획 초반에는 하나의 정답을 찾기보다 여러 가능성을 한눈에 비교하는 것이 중요하다. HTML은 이런 비교에 강하다.
2. 코드 리뷰와 PR 설명
코드는 Markdown에서 읽기 어렵다. 단순 코드 블록으로는 맥락, 흐름, 위험도, diff의 의미를 한눈에 파악하기 어렵다.
HTML에서는 실제 diff를 렌더링하고, margin annotation을 달고, 심각도별로 색상을 구분하고, 플로우차트나 모듈 다이어그램을 함께 보여줄 수 있다.
예를 들어 이렇게 요청할 수 있다.
이 PR을 리뷰할 수 있도록 HTML artifact를 만들어줘. streaming/backpressure 로직이 낯설어서 그 부분을 중심으로 설명해줘. 실제 diff를 렌더링하고, margin annotation을 달고, 심각도별로 색상을 구분해줘.
이런 HTML 문서는 GitHub 기본 diff보다 이해하기 쉬울 때가 많다.
특히 누군가에게 PR을 설명해야 할 때, 단순한 텍스트보다 시각적 설명이 훨씬 강력하다.
3. 디자인과 프로토타입
Claude Design이 HTML 기반인 이유도 여기에 있다.
HTML은 디자인을 표현하기에 충분히 강력하다. 최종 제품이 React, Swift, Flutter, UIKit, Android View 무엇이든 상관없다. 초기 아이디어 탐색은 HTML로 빠르게 할 수 있다.
버튼 애니메이션, 컴포넌트 상태, 디자인 시스템, 마이크로 인터랙션을 HTML로 먼저 실험하고, 마음에 드는 값을 실제 코드에 반영할 수 있다.
HTML은 최종 구현 언어가 아니라, 디자인을 생각하고 조정하기 위한 빠른 캔버스가 될 수 있다.
4. 리포트, 리서치, 학습 자료
Claude Code는 여러 데이터 소스를 읽고 하나의 리포트로 합성하는 데 강하다.
코드베이스, Git 히스토리, Slack, Linear, 인터넷 검색 결과를 읽고, 그것을 사람이 이해하기 쉬운 HTML 리포트로 만들 수 있다.
예를 들어 이렇게 요청할 수 있다.
우리 rate limiter가 실제로 어떻게 동작하는지 모르겠어. 관련 코드를 읽고 HTML 설명 페이지 하나로 만들어줘. token-bucket flow 다이어그램, 핵심 코드 스니펫 3~4개, gotchas 섹션을 포함해줘. 한 번 읽고 이해할 수 있게 최적화해줘.
Markdown 리포트도 가능하다. 하지만 HTML 리포트는 훨씬 더 읽기 쉽다.
다이어그램, 코드 주석, 색상, 섹션, 카드, 접기/펼치기, 링크를 활용하면 복잡한 개념도 한 번에 이해하기 쉬워진다.
5. 커스텀 편집 인터페이스
가끔은 텍스트로 원하는 것을 설명하기 어렵다.
그럴 때 Claude에게 특정 데이터만을 위한 일회용 HTML 편집기를 만들게 할 수 있다. 제품도 아니고, 재사용 가능한 SaaS도 아니다. 하지만 그 순간의 문제를 해결하기에는 매우 강력하다.
예를 들어:
티켓 우선순위 재정렬
feature flag 편집
프롬프트 튜닝
데이터셋 큐레이션
문서 annotation
색상, easing curve, crop region 선택
cron schedule 편집
regex 조건 실험
중요한 것은 마지막에 export 기능을 넣는 것이다.
HTML 안에서 사람이 조작한 내용을 다시 JSON, Markdown, Prompt, Diff 형태로 복사할 수 있게 만들어야 한다.
그러면 HTML은 단순한 산출물이 아니라 에이전트와 다시 대화하기 위한 입력 장치가 된다.
단점도 있다
HTML이 항상 정답은 아니다.
Markdown보다 토큰을 더 많이 쓴다. 생성 시간도 더 오래 걸린다. 일반적으로 Markdown보다 2~4배 정도 더 오래 걸릴 수 있다.
버전 관리도 불편하다. HTML diff는 Markdown diff보다 훨씬 지저분하다. 사람이 Git에서 변경사항을 검토하기 어렵다.
그래서 간단한 메모, 짧은 TODO, 일일 로그, 자주 수정해야 하는 텍스트 문서는 여전히 Markdown이 좋다.
하지만 사람이 실제로 읽고, 비교하고, 공유하고, 조작해야 하는 복잡한 산출물이라면 HTML이 훨씬 강력하다.
간단히 말하면 이렇다.
Markdown은 작성하기 쉽다.
HTML은 이해하기 쉽다.
에이전트 시대에는 이 차이가 점점 중요해진다.
중요한 것은 사람이 루프 안에 남는 것이다
이 글의 핵심은 단순히 “HTML이 예쁘다”가 아니다.
진짜 중요한 것은 사람이 에이전트의 작업 루프 안에 계속 남아 있을 수 있느냐는 문제다.
에이전트가 점점 더 많은 일을 하게 되면, 사람은 어느 순간 결과물을 제대로 읽지 않고 승인만 하게 된다. 긴 Markdown 계획서를 대충 보고 넘기면, 사실상 Claude가 모든 결정을 하게 된다. 사람은 루프 밖으로 밀려난다.
HTML은 사람을 다시 루프 안으로 끌어들인다.
읽고, 비교하고, 클릭하고, 조정하고, 선택하게 만든다. Claude가 만든 결과물을 더 잘 이해하고, 더 잘 개입할 수 있게 만든다.
그래서 HTML은 단순한 문서 포맷이 아니다.
에이전트와 사람이 함께 일하기 위한 더 나은 인터페이스다.
Markdown은 에이전트가 글을 쓰는 포맷이었다.
HTML은 에이전트가 사람에게 생각을 보여주는 인터페이스다.
에이전트가 단순한 답변자가 아니라 기획자, 개발자, 리뷰어, 리서처, 디자이너가 되어갈수록 산출물도 달라져야 한다.
긴 Markdown 문서를 더 많이 만드는 것이 답은 아니다.
사람이 실제로 읽고, 이해하고, 조작하고, 다시 에이전트에게 넘길 수 있는 형태가 필요하다.
그 형태로 HTML은 매우 강력하다.
앞으로의 에이전트 작업물은 단순한 문서가 아니라 작은 화면, 작은 도구, 작은 인터페이스가 될 것이다.