Claude Code 결과물은 왜 Markdown보다 HTML이 나을까 — AI가 만든 문서를 끝까지 읽게 만드는 법

1. 영상의 출발점: 100줄 넘는 Markdown은 아무도 끝까지 안 읽는다

영상의 첫 질문은 꽤 현실적이다. Claude가 만들어 준 Markdown 파일을 정말 끝까지 읽느냐는 것이다. 많은 사용자는 “잘 정리됐겠지”라고 생각하고 스크롤만 넘긴다. 문제는 게으름이 아니라 포맷이다. 긴 Markdown 문서는 구조가 단조롭고, 정보의 우선순위가 눈에 빨리 들어오지 않는다.

Thariq Shihipar가 던진 메시지도 이 지점에 있다. Claude Code처럼 파일, git 이력, 이슈 관리 도구, 업무 맥락을 읽을 수 있는 AI 도구가 긴 분석을 만들어도, 사람이 실제로 읽지 않으면 의사결정 품질은 좋아지지 않는다. AI가 더 많이 쓰는 시대에는 “얼마나 잘 썼느냐”보다 “사람이 그 결과를 읽고 판단할 수 있느냐”가 중요해진다.

Markdown은 개발자 문화에서 오래 살아남은 좋은 포맷이다. 텍스트로 diff가 잘 남고, README나 문서 저장소에 적합하다. 하지만 색, 배치, 시각적 위계, 상호작용을 거의 표현하지 못한다. 긴 계획서에서 위험 항목은 빨간색으로, 대안 비교는 카드형으로, 아키텍처는 SVG 도식으로 보여주고 싶다면 Markdown만으로는 한계가 온다.

2. HTML이 강한 다섯 가지 이유: 정보 밀도, 가독성, 공유, 상호작용, 맥락 흡수

영상은 HTML 전환의 이유를 다섯 가지로 정리한다. 첫째는 정보 밀도다. HTML은 한 화면에 표, 카드, 색상, SVG, 작은 일러스트, 버튼을 함께 담을 수 있다. AI가 분석한 내용을 단순한 문단이 아니라 화면 구조로 바꿀 수 있다는 뜻이다.

둘째는 시각적 명확성이다. 긴 Markdown은 위에서 아래로 읽어야 하지만, HTML은 탭, 카드, 경고 박스, 비교표로 관심 지점을 먼저 보게 만들 수 있다. 셋째는 공유다. 파일을 첨부하거나 저장소 링크를 설명하지 않아도, 정적 HTML을 올려 브라우저 링크 하나로 공유할 수 있다.

넷째는 양방향 상호작용이다. 예를 들어 버튼 애니메이션을 비교할 때 재생 속도, 색상, 둥근 정도를 슬라이더로 바꿔 보고, 마음에 드는 값을 “프롬프트로 복사”하게 만들 수 있다. 다섯째는 Claude Code의 맥락 흡수력이다. 로컬 파일, git 이력, 이슈 관리, 슬랙이나 리니어 같은 업무 데이터가 들어오면, 그 복잡한 맥락을 한 장의 HTML 대시보드처럼 정리할 수 있다.

3. Karpathy의 해석: HTML은 단순한 꾸밈이 아니라 AI 출력의 진화 단계다

Andrej Karpathy는 X에서 LLM에게 응답을 HTML로 구조화해 달라고 요청한 뒤 브라우저에서 보라는 취지의 글을 올렸다. 핵심은 “예쁜 문서”가 아니라 정보가 사람에게 들어오는 대역폭이다. 텍스트만 있는 답변은 단선적인 흐름이다. HTML은 시각적 배치와 상호작용을 통해 더 많은 정보를 한 번에 처리하게 만든다.

영상은 이를 “텍스트 → Markdown → HTML → 인터랙티브 신경 비디오”라는 진화 흐름으로 설명한다. 미래 단계까지 단정할 필요는 없다. 다만 현재 단계에서 이미 분명한 변화는 있다. AI가 사람이 읽을 문서를 만든다면, 결과물은 사람이 가장 잘 이해하는 감각 경로를 써야 한다는 것이다.

이 관점에서 HTML은 개발자만의 도구가 아니다. 기획자, 마케터, 법무 담당자, 경영지원 담당자에게도 의미가 있다. 긴 분석을 문단으로 받는 대신, 위험도 카드, 일정표, 의사결정 표, 체크리스트, 필터 가능한 이슈 목록으로 받으면 검토 속도가 달라진다.

4. 바로 쓸 수 있는 프롬프트: 끝에 한 줄만 붙이면 된다

영상에서 가장 실용적인 대목은 “거창한 설정이 없어도 된다”는 점이다. 별도 스킬을 만들거나 복잡한 플러그인을 설치하지 않아도, 프롬프트 끝에 HTML 파일로 만들어 달라는 한 줄을 붙이면 된다. 물론 결과 품질을 높이려면 제약 조건을 조금 더 주는 편이 좋다.

다음 자료를 바탕으로 의사결정용 보고서를 만들어줘.
조건:
- 결과는 self-contained HTML 파일 하나로 작성
- 모바일에서도 읽기 쉽게 카드와 표를 사용
- 핵심 결론, 리스크, 대안 비교, 다음 행동을 분리
- 중요한 수치와 판단 근거는 표로 정리
- 마지막에 "복사용 요약" 버튼을 넣어줘

여기서 중요한 것은 “HTML로 만들어줘”만이 아니다. 어떤 목적의 HTML인지 말해야 한다. 보고용인지, 비교용인지, 코드 리뷰용인지, 드래그 가능한 임시 편집기인지에 따라 화면 구조가 달라진다. AI에게 포맷을 맡기되, 사람의 의사결정 방식은 사용자가 지정해야 한다.

5. 활용 시나리오 다섯 가지: 계획서, 코드 리뷰, 프로토타입, 리서치, 1회성 에디터

첫 번째는 계획서와 스펙이다. 새 기능을 만들 때 대안 여섯 개를 카드로 비교하고, 각각의 장점·리스크·예상 작업량을 한 화면에 보여 달라고 할 수 있다. Markdown 표보다 훨씬 빠르게 판단된다.

두 번째는 코드 리뷰다. PR 내용을 HTML로 설명하게 하면 파일별 변경 요약, 위험도, 테스트 영향, 되돌림 전략을 색상과 카드로 나눌 수 있다. 개발자가 아닌 이해관계자도 큰 흐름을 파악하기 쉽다.

세 번째는 디자인 프로토타입이다. 버튼 애니메이션, 카드 배치, 색상 팔레트처럼 눈으로 봐야 하는 항목은 HTML 미니 프로토타입이 Markdown 설명보다 낫다. 네 번째는 리서치 보고서다. 코드베이스 인증 흐름, 고객 여정, 정책 비교처럼 복잡한 내용을 SVG 도식과 함께 정리할 수 있다.

다섯 번째가 가장 흥미롭다. 바로 1회성 에디터다. 리니어 티켓 30개를 “Now, Next, Later, Cut” 네 칸으로 드래그해 우선순위를 정하고, 마지막에 Markdown으로 결과를 복사하게 만들 수 있다. 예전에는 이런 도구를 만들 시간이 더 오래 걸렸지만, 이제는 작업을 하기 위해 그 작업에 맞는 작은 도구를 즉석에서 만드는 방식이 가능해졌다.

6. 단점도 분명하다: 토큰, diff, 보안, 장기 보관 문제

HTML이 만능은 아니다. 먼저 토큰을 더 쓴다. 같은 내용을 Markdown으로 쓰는 것보다 HTML은 태그와 스타일 때문에 길어진다. 응답 시간도 늘 수 있다. 작은 메모나 짧은 체크리스트라면 굳이 HTML로 받을 이유가 없다.

둘째, 버전 관리가 불편할 수 있다. HTML은 한 줄 스타일이나 자동 줄바꿈 때문에 diff가 지저분해진다. 오래 관리해야 하는 정책 문서라면 Markdown 원본을 유지하고, HTML은 읽기용 산출물로 따로 만드는 편이 낫다.

셋째, 보안이다. HTML에는 JavaScript가 들어갈 수 있다. 외부 링크, 원격 스크립트, 로컬 파일 접근, 복사 버튼 같은 기능은 편하지만 회사 환경에서는 통제 대상이다. 민감한 자료를 다루는 조직이라면 self-contained HTML, 외부 스크립트 금지, 네트워크 호출 금지 같은 규칙을 먼저 정해야 한다.

• 짧은 답변은 Markdown으로 충분하다. 1~2페이지짜리 요약에 HTML을 쓰면 과하다.
• 장기 보관 문서는 원본 텍스트를 남긴다. HTML은 읽기용, Markdown은 기록용으로 병행하는 방식이 안전하다.
• 회사 자료에는 외부 스크립트를 제한한다. 브라우저에서 열리는 파일도 보안 표면이 될 수 있다.
• 숫자와 법률 문구는 이미지가 아니라 텍스트와 표로 둔다. 시각화는 보조 역할이어야 한다.
• 의사결정 화면에는 복사용 결과를 붙인다. 사람이 선택한 값을 다시 AI나 업무툴에 넘길 수 있어야 한다.

7. 직장인에게 더 중요한 이유: AI 결과물을 ‘읽는 사람’ 중심으로 바꾸는 습관

AI를 잘 쓰는 사람은 프롬프트를 길게 쓰는 사람만이 아니다. 결과물을 어떤 형태로 받을지 설계하는 사람이다. 같은 리서치를 시켜도 “요약해줘”라고 하면 문단이 나오고, “임원 보고용 HTML 대시보드로 만들어줘”라고 하면 결론, 근거, 리스크, 선택지가 분리된다.

업무 현장에서는 이 차이가 크다. 회의록은 액션 아이템 보드가 될 수 있고, 고객 VOC는 원인별 카드가 될 수 있으며, 계약서 비교는 위험 조항 표가 될 수 있다. AI가 작성한 결과를 사람이 읽지 않는 문제를 해결하려면, AI에게 더 많이 쓰게 하는 것이 아니라 더 읽히는 형태로 만들게 해야 한다.

따라서 다음부터 Claude Code나 다른 AI 도구를 쓸 때는 질문 끝에 목적을 붙여 보는 것이 좋다. “HTML로 만들어줘”보다 한 단계 더 나아가 “읽는 사람이 3분 안에 결론, 위험, 다음 행동을 판단할 수 있는 HTML로 만들어줘”라고 요청하는 것이다.