Claude Code에서 HTML이 ‘비합리적으로 효과적인’ 이유

핵심 요약

이 글은 Claude Code 같은 코딩 에이전트가 산출물을 만들 때 Markdown보다 HTML이 더 강력한 커뮤니케이션 형식이 될 수 있다는 Anthropic 측 작성자의 경험담입니다.

• 문제의식: Markdown은 단순하고 편집하기 쉽지만, 긴 계획서·스펙·리뷰 문서가 되면 읽기 어렵고 표현력이 제한됩니다.
• 주장: HTML은 표, CSS, SVG, 이미지, 인터랙션, 레이아웃, 시각적 계층을 활용해 에이전트의 복잡한 결과물을 더 잘 전달합니다.
• 핵심 효과: 사용자가 문서를 실제로 읽고, 비교하고, 조작하고, 공유할 가능성이 높아집니다.
• 주의점: HTML은 생성 시간이 더 오래 걸리고, 버전관리 diff가 지저분해질 수 있습니다.

왜 Markdown이 부족해졌나

작성자는 Markdown이 그동안 에이전트와 인간 사이의 기본 파일 형식처럼 쓰였다고 봅니다. 이유는 분명합니다. 단순하고, 이식성이 좋고, 어느 정도 서식 표현이 가능하며, 사람이 직접 편집하기 쉽습니다. Claude가 Markdown 안에서 ASCII 다이어그램까지 꽤 잘 그리게 된 것도 장점으로 언급됩니다.

하지만 에이전트가 더 복잡한 일을 하게 되면서 Markdown의 한계가 커졌다고 설명합니다. 특히 작성자는 100줄이 넘는 Markdown 문서를 읽기 어렵다고 말합니다. 스펙, 참고 문서, 브레인스토밍 결과, 계획서처럼 점점 길고 복잡해지는 산출물에는 텍스트 중심 구조만으로 부족하다는 문제의식입니다.

또 하나의 변화는 사용자가 더 이상 이 문서를 직접 많이 편집하지 않는다는 점입니다. 예전에는 Markdown의 큰 장점이 사람이 쉽게 고칠 수 있다는 것이었지만, 지금은 수정도 Claude에게 프롬프트로 요청하는 경우가 많아졌습니다. 즉, 사람이 직접 편집하기 쉬운 형식이라는 Markdown의 강점이 상대적으로 약해졌다는 뜻입니다.

HTML이 강력한 이유

1. 정보 밀도: HTML은 거의 모든 정보를 담는 캔버스

작성자는 HTML이 Markdown보다 훨씬 풍부한 정보를 표현할 수 있다고 강조합니다. 단순한 제목, 문단, 목록뿐 아니라 표, CSS 기반 디자인 정보, SVG 일러스트, 이미지, 워크플로우 다이어그램, 절대 위치 기반 공간 정보, 상호작용 UI까지 표현할 수 있습니다.

본문의 강한 표현을 빌리면, Claude가 읽을 수 있는 거의 모든 정보 집합은 HTML로 꽤 효율적으로 표현할 수 있다는 주장입니다. 그래서 HTML은 모델이 깊이 있는 정보를 사용자에게 전달하고, 사용자가 이를 검토하는 데 효율적인 형식이 됩니다.

반대로 Markdown만 사용할 경우, 모델이 복잡한 시각 정보를 전달하기 위해 ASCII 다이어그램을 만들거나, 색상을 유니코드 문자로 흉내 내는 등 우회적인 방식을 쓰게 된다고 설명합니다. 이는 흥미롭지만 정보 전달 효율은 떨어질 수 있습니다.

2. 시각적 명료성: 긴 계획서와 스펙을 읽게 만든다

Claude가 더 복잡한 일을 하게 되면서 스펙과 계획서도 길어지고 있습니다. 작성자는 실제 업무에서 긴 Markdown 문서를 본인도 잘 읽지 않게 되고, 조직 내 다른 사람에게 읽히기는 더 어렵다고 말합니다.

HTML은 이 문제를 시각적 구조로 풀 수 있습니다. 예를 들어 섹션을 카드로 나누고, 탭으로 구분하고, 다이어그램과 링크를 배치하고, 모바일 반응형으로 만들 수 있습니다. 즉, 단순히 내용이 많아지는 것이 아니라 탐색 가능한 문서가 됩니다.

여기서 중요한 포인트는 산출물의 품질이 모델의 사고력만으로 결정되지 않는다는 점입니다. 같은 내용이라도 사용자가 읽고 이해할 수 있는 형식으로 제공되어야 실제 업무 효과가 생깁니다.

3. 공유성: HTML은 링크 하나로 읽히기 쉽다

Markdown 파일은 브라우저에서 기본적으로 잘 렌더링되지 않는 경우가 많고, 이메일이나 메시지에 첨부해야 하는 상황도 많습니다. 반면 HTML 파일은 S3 같은 곳에 올리면 링크로 공유할 수 있고, 동료가 브라우저에서 바로 열 수 있습니다.

작성자는 이 차이가 실제 읽힐 확률에 영향을 준다고 봅니다. 스펙, 보고서, PR 설명 문서가 HTML이면 조직 구성원이 열어 보고 참조할 가능성이 훨씬 높아진다는 주장입니다.

4. 양방향 상호작용: 문서가 도구가 된다

HTML의 차별점은 단순히 보기 좋은 문서를 만드는 데서 끝나지 않습니다. 작성자는 HTML 문서 안에 슬라이더, 노브, 선택지, 복사 버튼 같은 상호작용 요소를 넣을 수 있다고 설명합니다.

예를 들어 디자인 애니메이션을 조정하는 슬라이더를 만들고, 사용자가 마음에 드는 값을 찾은 뒤 그 파라미터를 Claude Code에 다시 붙여 넣을 수 있게 만들 수 있습니다. 또는 알고리즘 옵션을 바꿔 보며 결과를 비교하고, 선택한 설정을 JSON이나 prompt 형태로 export할 수도 있습니다.

이 관점에서 HTML은 보고서이자 임시 작업 도구입니다. 특히 텍스트로 설명하기 어려운 색상, easing curve, crop 영역, cron 스케줄, regex 같은 값을 고를 때 유용하다고 볼 수 있습니다.

5. Claude Code와 HTML의 궁합

작성자는 왜 ClaudeAI나 Claude Design이 아니라 Claude Code로 HTML 파일을 만들게 하느냐는 질문에 대해, Claude Code가 더 많은 맥락을 흡수할 수 있다는 점을 듭니다.

• 로컬 파일시스템의 코드와 기존 HTML 파일
• Slack, Linear 같은 MCP 기반 외부 컨텍스트
• 브라우저 컨텍스트
• git history
• 코드베이스 구조와 변경 이력

본문의 예시에서는 작성자가 Claude Code에게 자신의 코드 폴더를 읽고, 생성된 HTML 파일들을 찾아 분류한 뒤, 각 유형을 다이어그램으로 표현한 HTML 파일을 만들게 했다고 설명합니다. 즉, Claude Code는 단순 HTML 생성기가 아니라 맥락을 읽고 종합해 시각적 산출물로 변환하는 작업자로 쓰입니다.

주요 사용 사례

1) 스펙, 계획, 탐색

작성자는 단순 Markdown 계획서 대신 여러 HTML 파일의 웹을 만들 수 있다고 말합니다. 처음에는 여러 접근 방향을 브레인스토밍하고, 이후 특정 안을 확장해 목업이나 코드 조각을 만들고, 마지막에는 구현 계획으로 정리하는 흐름입니다.

• 여러 구현 방향 비교
• 여러 시각 디자인안 비교
• 데이터 흐름과 코드 스니펫이 포함된 구현 계획
• 검증 에이전트에게 더 넓은 맥락 제공

2) 코드 리뷰와 코드 이해

코드는 Markdown에서 읽기 어려울 수 있습니다. HTML에서는 diff, 주석, flowchart, 모듈 관계, severity 색상 표시 등을 함께 보여줄 수 있습니다. 작성자는 PR마다 HTML code explainer를 첨부한다고 말합니다.

• PR 설명 문서
• PR 리뷰 보조 자료
• 복잡한 코드 주제 설명
• GitHub 기본 diff보다 이해하기 쉬운 리뷰 화면

3) 디자인과 프로토타입

본문은 Claude Design이 HTML 기반이라는 점도 언급합니다. 최종 산출물이 React, Swift 등 다른 기술이어도 HTML은 디자인 스케치와 인터랙션 프로토타입에 적합하다는 설명입니다.

• 디자인 시스템 아티팩트
• 컴포넌트 조정
• 컴포넌트 라이브러리 시각화
• 애니메이션 프로토타이핑

4) 보고서, 리서치, 학습

Claude Code는 여러 데이터 소스를 종합해 읽기 쉬운 보고서를 만들 수 있습니다. Slack, 코드베이스, git history, 인터넷 등을 검색하고 HTML 문서, interactive explainer, slideshow 형태로 정리할 수 있다는 것이 본문의 주장입니다.

• 기능 동작 방식 설명
• 개념 학습용 explainer
• 주간 상태 보고
• 리더십 대상 incident report
• SVG 기반 기술 다이어그램

5) 맞춤형 편집 인터페이스

작성자는 특정 작업을 위해 일회성 HTML 편집기를 만들 수 있다고 말합니다. 제품이나 재사용 도구가 아니라, 지금 다루는 데이터 하나를 편집하기 위한 throwaway editor입니다.

• Linear 티켓을 Now / Next / Later / Cut으로 드래그해 재정렬
• feature flag config를 폼 기반으로 편집하고 dependency 경고 표시
• system prompt를 좌우 비교 편집하며 live preview 제공
• 데이터셋 row 승인·거절·태깅 후 export
• 문서, transcript, diff에 annotation 후 export

핵심은 항상 마지막에 export 기능을 두는 것입니다. 예를 들어 copy as JSON, copy as prompt, copy diff, copy as markdown 버튼을 통해 사람이 UI에서 조정한 내용을 Claude Code로 다시 가져갈 수 있게 합니다.

FAQ에서 드러나는 현실적 단점

분석: 이 글의 진짜 메시지

표면적으로는 Markdown 대신 HTML을 쓰자는 글이지만, 더 깊은 메시지는 AI 에이전트 시대의 산출물은 사람이 검토 가능한 형태여야 한다는 것입니다.

작성자는 한때 Claude가 작성한 긴 계획서를 자세히 읽지 않게 되면서, 결국 Claude가 알아서 선택하도록 방치하게 될까 봐 걱정했다고 말합니다. 그런데 HTML을 쓰기 시작하면서 오히려 더 많이 읽고, 더 많이 비교하고, 더 많이 조정하게 되었다고 설명합니다.

즉 HTML은 단순한 파일 포맷이 아니라, 사용자가 에이전트 작업 흐름에서 in the loop로 남기 위한 인터페이스입니다. Markdown은 에이전트가 생각을 적는 종이에 가깝고, HTML은 에이전트와 사람이 함께 검토하고 조작하는 작업대에 가깝습니다.

실무 적용 포인트

• 짧은 메모와 README: 여전히 Markdown이 적합할 수 있습니다.
• 긴 계획서, 리서치, PR 설명: HTML이 읽힐 확률을 높일 수 있습니다.
• 비교가 필요한 작업: 여러 안을 grid, tab, card 구조로 배치하면 효과적입니다.
• 복잡한 코드 이해: diff, annotation, flowchart를 함께 보여주는 HTML explainer가 유용할 수 있습니다.
• 디자인·파라미터 조정: 슬라이더와 copy/export 버튼이 있는 일회성 HTML 도구가 강력합니다.
• 조직 공유: HTML을 업로드해 링크로 공유하면 첨부 파일보다 접근성이 좋아질 가능성이 있습니다.

리스크와 확인 포인트

• 버전관리: HTML diff가 지저분해 리뷰 비용이 커질 수 있습니다. 중요한 문서는 원본 데이터와 생성된 HTML을 분리 관리하는 방식이 필요할 수 있습니다.
• 보안: 본문은 script 태그와 JavaScript 기반 상호작용을 언급하지만, 공유 문서에서는 실행 스크립트·외부 리소스·민감정보 노출을 반드시 점검해야 합니다.
• 디자인 일관성: 모델이 만든 HTML은 취향과 브랜드에 맞지 않을 수 있으므로 디자인 시스템 reference가 필요합니다.
• 생성 시간: 작성자 기준 HTML은 Markdown보다 2~4배 오래 걸릴 수 있습니다. 빠른 초안에는 과할 수 있습니다.
• 접근성: 시각적으로 풍부한 문서일수록 모바일, 스크린리더, 키보드 탐색을 함께 고려해야 합니다.
• 과잉 사용: 모든 것을 HTML로 만들 필요는 없습니다. 작성자 본인도 HTML maximalist 쪽에 가깝다고 인정합니다.

한 줄 결론

이 글은 HTML을 ‘예쁜 문서 형식’이 아니라, AI 에이전트의 복잡한 작업을 사람이 읽고, 이해하고, 조정하고, 다시 에이전트에게 넘기는 인터페이스로 보자는 제안입니다.