AI가 만들어준 플랜이나 문서를 실제로 끝까지 읽은 적이 얼마나 되시나요? Anthropic Claude Code 팀의 Thariq Shihipar는 솔직하게 말합니다. 100줄이 넘는 Markdown 파일은 본인도 잘 읽지 않는다고.

Thariq는 Claude Code 팀 내에서 확산되고 있는 변화를 공유했습니다. AI에게 결과물을 요청할 때 Markdown이 아닌 HTML로 받기 시작했다는 것입니다. 단순한 선호의 문제가 아니라, AI와 협업하는 방식 자체를 다시 생각하게 된 계기에서 나온 선택입니다.

출처: Using Claude Code: The Unreasonable Effectiveness of HTML – Thariq Shihipar

Markdown이 기본값이 된 이유

Markdown은 GPT-4 시대부터 AI 출력의 기본 포맷으로 자리 잡았습니다. 이유는 명확했습니다. 당시 8,192 토큰이라는 빡빡한 컨텍스트 창 안에서 토큰을 아끼려면 Markdown이 HTML보다 훨씬 효율적이었습니다. 간결하고 편집하기 쉬우며, 어디서든 읽을 수 있었죠. 개발자이자 오픈소스 해커인 Simon Willison도 Thariq의 글을 접하기 전까지 GPT-4 시절부터 Markdown을 기본으로 써왔다고 밝혔습니다.

하지만 지금은 상황이 다릅니다. Claude는 최대 100만 토큰의 컨텍스트를 다룰 수 있고, AI 에이전트는 점점 더 긴 산출물을 만들어냅니다. 스펙 문서, 구현 계획, PR 리뷰, 리포트. 토큰 효율을 위해 Markdown을 선택해야 할 이유가 예전보다 훨씬 줄어들었습니다.

HTML이 더 잘 읽히는 이유

Markdown의 본질적인 한계는 포맷의 풍부함이 아니라 가독성의 한계입니다.

Thariq는 100줄이 넘는 Markdown을 자기 자신도 잘 읽지 않는다고 했습니다. 팀원에게 읽혀야 하는 문서라면 더욱 그렇습니다. 텍스트가 줄줄이 이어지면 중요한 정보가 묻히고, 구조가 있어도 한눈에 들어오지 않습니다.

HTML은 다릅니다. Claude가 탭 내비게이션, 색상 코딩, SVG 다이어그램, 인터랙티브 요소를 자유롭게 쓸 수 있어서 같은 내용도 훨씬 소화하기 쉬운 형태로 정리됩니다. 실제로 Thariq는 모든 PR에 HTML로 만든 코드 설명 문서를 첨부하기 시작했는데, GitHub의 기본 diff 뷰보다 오히려 더 잘 읽힌다고 말합니다.

공유도 간편합니다. Markdown 파일은 브라우저에서 바로 열리지 않아 첨부파일로 보내야 하지만, HTML 파일은 S3 같은 곳에 올리면 링크 하나로 누구든 열어볼 수 있습니다.

“살아있는 문서”로서의 HTML

Thariq가 강조하는 또 하나의 차이는 인터랙티비티입니다.

Markdown은 읽는 문서입니다. HTML은 조작할 수 있는 문서입니다. 슬라이더로 디자인 파라미터를 조정하거나, 티켓을 드래그해서 우선순위를 재배치하거나, 변경한 설정을 바로 복사해서 Claude에 다시 붙여넣을 수 있습니다. AI가 만든 결과물과 사람이 직접 상호작용하는 방식이 열리는 셈입니다.

이 점이 단순히 “더 이쁜 문서”와 다른 이유입니다. Thariq는 HTML을 쓰면서 AI 작업에 더 깊이 관여하고 있다는 느낌을 받게 됐다고 말합니다. 플랜을 훑어보는 게 아니라 실제로 검토하고 개입하게 된다는 것입니다.

실제로 어떻게 쓰나

Claude Code는 파일 시스템, git 히스토리, MCP 연결 도구(Slack, Linear 등), 브라우저까지 접근할 수 있습니다. Thariq는 이 맥락을 활용해 HTML 문서를 만듭니다. 예를 들어, 코드베이스의 HTML 파일을 전부 읽어서 유형별로 분류한 뒤, 각 유형을 다이어그램으로 표현한 HTML 문서를 생성하는 식입니다.

물론 단점도 있습니다. HTML은 Markdown보다 생성 시간이 2~4배 더 걸립니다. 버전 관리도 불편합니다. HTML diff는 노이즈가 많고 리뷰하기 까다롭습니다.

Thariq 본인도 이런 단점을 인정하면서, 자신이 HTML 극단주의자 쪽에 가깝다고 말합니다. 다만 그는 한 가지를 강조합니다. 복잡한 설정이나 스킬이 필요한 것이 아니라, Claude에게 그냥 “HTML 파일로 만들어줘”라고 하면 된다고.

Simon Willison도 이 글을 읽고 생각이 바뀌었다고 밝혔습니다. 즉각적인 정보 전달보다 풍부한 탐색 경험이 중요한 출력, 특히 애드혹 질문에 대한 설명을 요청할 때 HTML을 실험해볼 계획이라고요. 오랫동안 Markdown을 기본으로 써온 사람이 “재검토하게 됐다”고 말한다는 건, 이 논의가 단순한 팀 내부 유행을 넘어선다는 신호일 수 있습니다.

원문에는 플래닝, 코드 리뷰, 디자인 프로토타이핑, 보고서, 임시 에디터 등 다섯 가지 사용 패턴과 각각의 프롬프트 예시가 포함되어 있습니다.

참고자료: Using Claude Code: The Unreasonable Effectiveness of HTML – Simon Willison’s Weblog