"HTML vs Markdown" 전쟁이 지난주 인터넷을 뒤흔들었습니다. 양측 모두 틀렸으며, 진짜 정답은 내내 각주 속에 숨겨져 있었습니다.

지난주, Claude Code의 엔지니어링 리드(engineering lead)가 “HTML의 비합리적 유효성 (The Unreasonable Effectiveness of HTML)”이라는 게시물을 올렸고, 커피가 다 내려지기도 전에 개발자 커뮤니티는 양분되었습니다.

Anthropic의 Claude Code 엔지니어링을 총괄하는 Thariq Shihipar는 왜 AI 에이전트가 Markdown 대신 HTML을 출력해야 하는지를 보여주는 20가지 작업 예시를 공개했습니다. 대화형 내비게이션(Interactive navigation), 접이식 섹션(Collapsible sections), 색상 코드가 적용된 코드 리뷰(Color-coded code reviews), 임베디드 시각화(Embedded visualizations), 공유 가능한 링크(Shareable links) 등이 포함되었습니다. 이 게시물은 16시간 만에 440만 회의 조회수를 기록했습니다.

반응은 도구 선호도를 종교처럼 다루는 커뮤니티에서 예상할 수 있는 그대로였습니다.

HTML 팀은 Markdown의 종말을 선언했습니다. Markdown 팀은 이를 토큰 비용(token tax)이 부과된 보안 위험이라고 불렀습니다. 스레드는 가득 찼고, 인용 트윗(Quote-tweets)은 엉뚱한 방향으로 흘러갔습니다. 누군가는 분명히 "이래서 우리가 좋은 것을 가질 수 없는 것이다"라는 답글을 달았을 것입니다. 늘 있는 일이죠.

문제는 이것입니다: 양측 모두 완전히 잘못된 질문을 두고 논쟁하고 있었다는 점입니다.

HTML 진영은 방향은 맞게 잡았지만, 3~5배에 달하는 토큰 오버헤드(token overhead), AI가 생성한 JavaScript의 위험성, 그리고 Anthropic이 사용자가 더 많은 토큰을 사용함에 따라 직접적으로 이익을 얻는다는 약간은 어색한 사실 등의 비용 문제를 대수롭지 않게 넘겼습니다. Markdown 진영은 실제 위험을 식별했지만, 컨텍스트 윈도우(context windows)가 100만 토큰에 도달한 이후로는 더 이상 유효하지 않은 제약 조건들을 방어하고 있습니다. 그들은 2026년의 세상에서 2022년의 문제를 최적화하고 있는 것입니다.

양측 모두 질문조차 하지 않았던 실제 질문은 그 어떤 것보다 단순합니다: 이 출력을 누가 읽으며, 그들은 그것으로 무엇을 하는가?

그것이 전부입니다. 그것이 전체 프레임워크입니다. 그 외의 모든 것은 소음입니다.

그럼 이제 Markdown이 어떻게 기본값이 되었는지, Markdown의 세 가지 핵심 가정이 왜 조용히 부패하고 있는지, 실제로 계산했을 때 토큰 수학(token math)이 어떻게 나타나는지, 그리고 왜 형식 전쟁이 내내 그곳에 놓여 있던 의사결정 트리(decision tree)로부터 주의를 돌리는 방해 요소였는지에 대해 이야기해 봅시다.

Markdown이 어떻게 AI 출력의 기본값이 되었는가 (누구도 선택하지 않았고, 그저 상속되었을 뿐이다)

Markdown은 포맷 전쟁에서 승리한 것이 아닙니다. 그저 세 번 연속으로 적절한 시기에 나타났을 뿐이며, 결국 아무도 그것에 의문을 제기하지 않게 되었습니다.

첫 번째 물결은 개발자들이었습니다. John Gruber는 2004년에 Markdown을 HTML로 깔끔하게 변환되면서도 읽기 쉬운 일반 텍스트(plain text)를 작성하는 방법으로 만들었습니다. 블로거들에게는 편리한 도구였습니다. 그 후 GitHub가 README, 이슈(issues), 풀 리퀘스트(pull request) 설명에 이를 채택하면서, 하룻밤 사이에 지구상의 모든 오픈 소스 프로젝트가 Markdown을 작성하게 되었습니다. 그것이 평가를 거쳐 선택되었기 때문이 아니라, 이미 그곳에 있었기 때문입니다.

두 번째 물결은 지식 노동자들이었습니다. 2010년대를 거치며 Notion, Obsidian, Jekyll은 Markdown을 중심으로 전체 편집 경험을 구축했습니다. Markdown은 위키(wikis), 노트 테이킹(note-taking), 정적 사이트(static sites)의 기본값이 되었습니다. 제안 내용은 매번 동일했습니다: 인간이 읽을 수 있으면서도(human-readable) 동시에 기계가 파싱할 수 있다(machine-parseable)는 것이었습니다. 어떤 텍스트 에디터에서든 작성하고, 어디에서든 렌더링(render)할 수 있습니다. 누구나 오후 한나절이면 익힐 수 있을 만큼 단순하면서도, 다른 것이 정말로 필요 없을 만큼 강력했습니다.

세 번째 물결은 AI였습니다. 2022년 말 ChatGPT가 출시되었을 때, 모델은 응답을 Markdown으로 렌더링했습니다. OpenAI가 포맷 평가를 실시했기 때문이 아닙니다. 학습 데이터(training data)가 Markdown으로 포화되어 있었기 때문입니다. GitHub 저장소, 기술 문서, 위키, 블로그 포스트, README 등 눈이 닿는 곳마다 Markdown이 가득했습니다. Markdown은 모델이 가장 많이 본 것이었고, 따라서 Markdown은 모델이 생성하는 결과물이 되었습니다. 그 이후의 모든 챗봇과 코딩 어시스턴트(coding assistant)는 동일한 기본값을 따랐습니다.

저는 아직도 2016년 저장소에 있는 README들을 가지고 있는데, 그것들은 오늘날 제가 사용하는 Claude의 출력물과 구조적으로 동일해 보입니다. 동일한 헤딩 계층 구조(heading hierarchy). 동일한 불렛 패턴(bullet pattern). 동일한 코드 블록(code block) 스타일. 이것은 무언가가 자동 항법 장치(autopilot)로 작동하고 있다는 첫 번째 단서였어야 했습니다.

세 번의 물결. 각각의 물결이 이전의 물결을 강화했습니다. 아무도 AI 출력물을 위해 Markdown을 평가하고 그것이 가장 적합하다고 결정하지 않았습니다. Markdown은 이전의 세 번의 면접에서 이미 적절한 셔츠를 입고 있었기 때문에 그 직무를 상속받은 것입니다.

그 상속이 바로 문제입니다. Markdown이 설계되었던 세상과 우리가 현재 실제로 구축하고 있는 세상은 같은 세상이 아니기 때문입니다. 그리고 Markdown이 주도권을 잡았을 당시에는 완전히 합리적이었던 세 가지 가정이 동시에 무너지고 있습니다.

Markdown에 내장되어 조용히 부패하고 있는 세 가지 가정

Markdown은 세 가지 전제 조건 하에 AI 출력의 기본값이 되었습니다. 2022년에는 이 세 가지 모두 타당했습니다. 하지만 2026년에는 그 어느 것도 제대로 유지되지 않습니다.

전제 1: 인간이 출력을 편집한다.

Markdown은 자신의 텍스트를 직접 쓰고 수정하는 사람들을 위해 설계되었습니다. README, 문서(docs), 블로그 포스트는 여전히 그런 방식으로 작동합니다. 누군가 파일을 열고, 단락을 다시 쓰고, 커밋(commit)을 푸시합니다. 하지만 에이전트(agent)의 출력은 다릅니다. 당신은 프롬프트(prompt)를 보냅니다. 에이전트는 2,000단어 분량의 구현 계획, 코드 리뷰, 경쟁 분석 보고서를 생성합니다. 당신은 그것을 읽습니다. 어쩌면 공유할 수도 있습니다. 하지만 에디터(editor)를 열어 단락을 다시 쓰기 시작하는 일은 거의 없습니다.

마지막으로 실제로 그렇게 했던 적이 언제인가요?

Claude의 출력을 가져와서 VS Code에서 열고 산문을 편집했던 적이 있습니까?

손으로 쓰기 쉽고 수정하기 쉽다는 이 형식의 핵심 가치 제안(value proposition)은 더 이상 실제 사용 사례와 일치하지 않습니다. 에이전트가 작성했기 때문입니다. 이제 당신은 그저 독자일 뿐입니다.

전제 2: 콘텐츠의 양이 적다.

500단어 정도의 문서는 Markdown에서 잘 렌더링됩니다. 하지만 트레이드오프(trade-off) 표, 코드 샘플, 구현 노트가 포함된 에이전트 생성 3,000단어 분량의 아키텍처 결정(architecture decision) 문서는 그렇지 않습니다. 대략 100줄이 넘어가면 Markdown은 거대한 벽이 됩니다. 탐색 기능도, 접을 수 있는 섹션(collapsible sections)도 없으며, 관심 없는 부분을 모두 스크롤하지 않고 실제로 원하는 부분으로 바로 건너뛸 방법도 없습니다.

이에 대한 Thariq의 관찰은 직설적입니다. 아무도 100줄이 넘는 Markdown 파일을 제대로 읽지 않는다는 것입니다. 사람들은 훑어보고, 내용을 놓치고, 파일을 닫아버립니다. README에는 완벽했던 형식이 출력이 전체 기술 보고서가 될 때는 당신의 발목을 잡습니다.

전제 3: 출력이 읽기 전용(read-only)이다.

과거의 워크플로우는 선형적이었습니다.

프롬프트(Prompt) → 생성(generate) → 읽기(read) → 닫기(close).

완료되었습니다. 하지만 에이전트(Agent) 시대는 다른 무언가를 향해 나아가고 있습니다. 테이블을 필터링하고, 파라미터(Parameter)를 조정하며, 두 가지 옵션을 나란히 비교합니다. 하위 집합을 내보내고, 그 결과를 구조화된 입력(Structured input)으로서 다음 프롬프트(Prompt)에 다시 전달합니다. Markdown은 이 중 그 어떤 것도 수행할 수 없습니다. Markdown은 출구가 없는 일방통행로입니다.

세 가지 전제를 한 번에 관통하는 재정의는 다음과 같습니다: Markdown은 보고서(Report)입니다. HTML은 인터페이스(Interface)입니다. 보고서는 읽고 닫지만, 인터페이스는 조작하고 그 결과를 앞으로 전달합니다.

이러한 차이는 그 어떤 토큰 비용(Token cost) 계산보다 더 중요합니다. 하지만 토큰 비용은 모두가 계속 인용하는 수치이므로, 실제로 계산해 봅시다.

아무도 실제로 계산해보지 않은 토큰 수학

'Markdown 팀'이 계속해서 장전하고 있는 주요 탄약은 토큰 오버헤드(Token overhead)입니다. HTML은 3~5배 더 많은 토큰을 소모합니다. 그들은 마치 이 말이 논쟁을 끝낼 수 있다는 듯이 말합니다.

하지만 그것이 실제 달러(Dollar)로 얼마를 의미하는지 확인하는 사람은 거의 없습니다.

동일한 2,000단어 분량의 보고서를 세 가지 형식으로 비교해 보겠습니다. 일반적인 Markdown은 출력 토큰이 약 3,000개 정도입니다. 무거운 스타일링을 배제한 효율적인 시맨틱 HTML(Semantic HTML) 구조는 약 7,200개가 소모됩니다. CSS, 임베디드 차트, 인터랙티브 섹션이 포함된 전체 HTML은 대략 14,400개에 달합니다. 인용되는 '3~5배'라는 범위는 실제입니다. 풍부한 HTML의 경우, 거의 5배에 달하는 토큰을 태우게 됩니다.

현재 Anthropic API 가격 기준으로 보고서당 발생하는 비용은 다음과 같습니다:

• Markdown 보고서: Claude Sonnet 기준 약 $0.072
• 효율적인 HTML: 약 $0.17
• 스타일링이 포함된 전체 HTML: 약 $0.34

단일 HTML 보고서의 오버헤드는 지금 이 글을 읽고 있는 스마트폰을 충전하는 전기 요금보다 적습니다.

Markdown과 비교했을 때 단 1달러를 더 쓰려면 Claude Sonnet에서 171개의 HTML 보고서를 생성해야 합니다. 단 1달러입니다. 사람들이 자신의 형식 철학 전체를 구축하는 근거가 바로 이 숫자입니다.

이것이 제가 '토큰 함정(Token Trap)'이라고 부르는 것입니다. 실제로 중요한 비용은 무시한 채, 실제 엔지니어링 예산에서는 반올림 오차 수준에 불과한 비용을 최적화하는 것이죠.

하지만 이 수학에는 두 번째 막이 있으며, Markdown 팀은 그 부분에 대해서는 인정받을 만합니다.

규모를 키우면 숫자가 달라집니다. 하루에 100개의 보고서를 생성할 경우, Claude Sonnet에서 발생하는 HTML 오버헤드 비용은 한 달에 약 500달러가 추가됩니다. 엔터프라이즈 규모, 즉 플랫폼 전체에서 매일 수천 건의 에이전트 호출(agent calls)이 발생하는 상황이라면 이는 단순한 잔돈이 아니라 실제 재무 항목(line items)으로 다가옵니다. Markdown 팀의 말이 틀린 것은 아닙니다. 다만 그들은 이 논리를 실제로 적용해야 할 곳이 아닌 모든 곳에 적용하고 있을 뿐입니다.

여기서 두 진영 모두가 계속 간과하고 있는 사실이 있습니다. 인간의 주의력(human attention) 또한 비용이 발생한다는 점입니다.

시니어 엔지니어의 시급은 대략 75달러에서 150달러 사이입니다. 아홉 번째 문단에 파묻힌 아키텍처 결정 사항을 찾기 위해 Markdown의 벽을 스크롤하며 15분을 허비하거나, 필터링이 가능했어야 할 표를 다시 읽거나, 공유 가능한 링크가 없어 특정 섹션을 Slack에 복사하여 붙여넣는 데 드는 시간은 엔지니어 인건비 기준으로 19달러에서 38달러 사이의 비용을 발생시킵니다.

동일한 보고서를 HTML로 작성했을 때의 토큰 오버헤드는? Sonnet 기준으로 17센트입니다.

토큰 함정(Token Trap)은 양방향으로 작동합니다. 개별 개발자들은 0.17달러를 두고 논쟁하며 시간을 낭비합니다. 반면 엔터프라이즈 팀은 수백 달러의 토큰 비용을 아끼기 위해 수천 달러의 엔지니어 주의력을 태워버립니다. 두 경우 모두, 포맷 결정이 완전히 잘못된 변수를 기준으로 내려지고 있습니다.

올바른 변수는 더 간단합니다. 토큰 비용이 얼마냐가 아니라, 누가 출력을 읽고 그 결과물로 무엇을 하느냐입니다.

이것이 바로 우리가 다음에 다룰 내용입니다.

포맷 전쟁을 끝낼 의사결정 트리

모든 에이전트 출력물은 세 가지 대상 중 하나를 독자로 가집니다. 포맷 선택은 당신이 어떤 대상을 상대하느냐에 따라 직접적으로 결정됩니다. 이것이 전체 프레임워크의 핵심입니다.

독자 1: 인간.

당신의 이해관계자(stakeholder)는 브라우저 탭을 엽니다. 그들은 관심 있는 섹션을 훑어보고, Slack에 공유할 차트를 스크린샷 찍고, 팀과 링크를 공유하며, 자신에게 해당하지 않는 부분은 읽지 않고 접이식(collapsible) 아키텍처 섹션을 클릭하여 확인합니다. 이것이 Thariq가 20가지 사례를 통해 구축한 유스케이스입니다. 인라인 심각도 색상이 포함된 코드 리뷰, 점프 네비게이션(jump navigation)이 포함된 구현 계획, 실제로 상호작용할 수 있는 라이브 스와치(live swatches)가 포함된 디자인 시스템 비교 등이 그 예입니다.

이 지점에서는 HTML이 승리합니다. 왜냐하면 출력물이 하나의 목적지(destination)이기 때문입니다. 독자는 이를 탐색하고, 조작하며, 앞으로 공유합니다. Markdown은 이 모든 것을 단순한 스크롤 형태로 평탄화(flatten)한 뒤, 결과가 잘 나오기만을 바랄 뿐입니다.

독자 2: 또 다른 에이전트 (Agent).

당신의 출력물은 다운스트림 파이프라인(downstream pipeline)으로 전달됩니다. 에이전트가 분석 내용을 읽고, 구조화된 데이터(structured data)를 추출하며, 결정을 내리고, 다음 단계를 트리거합니다. 인간은 이를 전혀 보지 못합니다. 이 지점에서는 Markdown이 여전히 깔끔하게 승리합니다. 가볍고, 파싱(parseable) 가능하며, 디프(diffable)가 가능하고, 렌더링 오버헤드(rendering overhead) 없이 처리할 수 있기 때문입니다. 다른 모델들은 마찰 없이 이를 소비합니다. Git은 이를 추적합니다. CI 파이프라인은 막힘없이 이를 처리합니다.

에이전트 간 통신(agent-to-agent communication)을 위해 HTML을 사용하는 것은, 스프레드시트를 인쇄하여 코팅한 뒤, 어차피 모든 숫자를 다시 타이핑할 사람에게 건네주는 것과 같습니다.

독자 3: 둘 다.

이것이 실제 엔지니어링 워크플로에서 가장 흔한 사례이며, 양측 진영 모두가 언급하기를 꺼려하는 부분입니다. 개발자가 PR(Pull Request) 리뷰를 생성하면, 본인이 직접 읽기도 하지만 동시에 리포지토리(repo)에 기록되기를 원합니다. 팀 리더가 주간 상태 보고서를 생성하면, 이해관계자들은 브라우저에서 이를 확인하고, 그 데이터는 다음 주 계획을 위한 프롬프트(prompt)로 입력됩니다. 인간과 기계, 동일한 출력물이지만 요구사항은 다릅니다.

여기서의 정답은 어느 한 쪽을 선택하는 것이 아닙니다. 바로 이것입니다: Markdown 소스, HTML 아티팩트(artifact).

Markdown을 편집 가능하고, 디프(diffable)가 가능하며, Git으로 추적되는 단일 진실 공급원(source of truth)으로 유지하세요. 그리고 탐색과 공유가 필요한 인간들을 위해 HTML 동반 결과물을 생성하세요. 이것이 사실 Thariq가 자신의 포스트에서 권장한 내용입니다. 진영 간의 논쟁에 묻혀버렸지만, 그 안에 명시되어 있습니다: Markdown은 리포지토리에 유지하고, 리뷰를 위한 동반 아티팩트(companion artifact)로서 HTML을 생성하십시오.

양측 진영 모두, 자신들이 생각하는 바를 말하지 않은 권장 사항에 대해 반박하고 있었던 것입니다.

의사결정 트리(decision tree)는 세 가지 질문으로 이루어집니다. 오직 인간만이 이것을 읽는가?

그렇다면 HTML을 사용하십시오. 오직 에이전트만이 이것을 읽는가? 그렇다면 Markdown을 사용하십시오. 둘 다 읽는가?

Markdown 소스, HTML 아티팩트. 이 내용을 스크린샷 찍어두세요. 그러면 다시는 다른 포맷 전쟁(format war) 스레드를 읽을 필요가 없을 것입니다.

프레임워크는 깔끔합니다. 하지만 예상대로, 현실 세계는 그렇지 않습니다.

실제로 어디에서 문제가 발생하는가, 그리고 이 변화로 누가 이득을 보는가