지금 제가 Claude Code로 하는 작업들을 보면, 마크다운보다 HTML이 훨씬 잘 맞는 이유가 몇 가지 있습니다.

정보 밀도

HTML은 마크다운과 비교할 수 없을 만큼 풍부한 정보를 담을 수 있습니다. 기본적인 헤더나 텍스트 서식은 물론이고, 다음과 같은 다양한 형태의 정보도 표현할 수 있습니다:

테이블을 이용한 표 형식 데이터
CSS를 활용한 디자인 데이터
SVG를 이용한 일러스트레이션
script 태그를 활용한 코드 스니펫
JavaScript + CSS 기반의 HTML 요소 인터랙션
SVG와 HTML을 결합한 워크플로우
절대 위치와 캔버스를 활용한 공간 데이터
이미지 태그를 이용한 이미지

제 생각엔, Claude가 읽을 수 있는 정보라면 HTML로 표현하지 못할 것이 거의 없습니다. 그래서 모델이 심층적인 정보를 전달하고 사용자가 이를 검토하는 방식으로는 HTML이 가장 효율적입니다.

이런 표현 수단이 없을 경우, 모델은 마크다운 안에서 ASCII 다이어그램이나 — 제가 특히 좋아하는 예로 — 유니코드 문자로 색상을 어림잡는 것처럼 비효율적인 방식에 의존하게 됩니다.

‍

시각적 명확성과 가독성

‍

Claude가 처리할 수 있는 작업의 복잡도가 높아질수록, 스펙 문서나 계획서의 분량도 함께 늘어납니다. 그런데 100줄이 넘는 마크다운 파일은 저도 끝까지 읽기가 어렵고, 팀의 다른 구성원들에게 읽어달라고 하기는 더더욱 힘든 게 현실입니다.

반면 HTML 문서는 Claude가 탭, 일러스트레이션, 링크 등을 활용해 탐색에 최적화된 구조로 시각적으로 구성할 수 있어 훨씬 읽기 편합니다. 모바일 반응형으로 만들면 디바이스 환경에 맞게 다른 방식으로 읽을 수도 있습니다.

공유 편의성

마크다운 파일은 대부분의 브라우저가 네이티브로 제대로 렌더링하지 않아 공유가 번거롭습니다. 보통 이메일이나 메시지에 첨부 파일로 붙여 보내야 합니다.

HTML 파일은 업로드만 하면 링크 하나로 손쉽게 공유할 수 있습니다. 동료들이 원하는 곳 어디서든 열어볼 수 있고, 필요할 때 다시 찾아보기도 쉽습니다.

스펙, 리포트, PR 작성 내용을 HTML로 작성하면 실제로 읽어볼 확률이 훨씬 높아집니다.

양방향 인터랙션

‍

HTML은 문서와 직접 인터랙션할 수 있다는 점도 큰 장점입니다. 예를 들어 디자인을 조정하는 슬라이더나 노브를 추가하거나, 알고리즘의 다양한 옵션을 직접 조작해 결과를 확인할 수 있습니다. 변경된 내용을 프롬프트로 복사해 Claude Code에 바로 붙여넣을 수 있는 기능도 넣어달라고 요청할 수 있습니다.

이 방식이 유용할 때는, 지금 풀고 있는 문제에 꼭 맞는 전용 편집 환경을 만들어낼 수 있습니다.

데이터 수집 능력

Claude.ai나 Claude Design 대신 Claude Code로 HTML 파일을 만드는 가장 큰 이유 중 하나는, Claude Code가 수집할 수 있는 컨텍스트의 폭이 훨씬 넓다는 점입니다. 예를 들어 이 글을 쓸 때 저는 Claude Code에게 코드 폴더를 훑어보며 생성했던 HTML 파일들을 모두 찾아내고, 이를 종류별로 분류한 뒤 각 유형을 다이어그램으로 표현한 HTML 파일을 만들어달라고 요청했습니다. 이 글에 담긴 다이어그램들이 바로 그 결과입니다.

파일 시스템 외에도, Claude Code는 MCP(Slack, Linear 등), 웹 브라우저(Chrome의 Claude), git 히스토리 등 다양한 경로로 추가적인 컨텍스트를 수집할 수 있습니다.

시작하기

한 가지 알아두면 좋은 점은, Claude가 이런 HTML을 생성하도록 하기 위해 복잡한 설정이 필요하지 않다는 것입니다. "HTML 파일 만들어줘"나 "HTML 아티팩트 만들어줘"처럼 간단하게 요청하면 됩니다. 핵심은 아티팩트가 어떤 역할을 해야 하고, 어떻게 활용할지를 미리 생각해두는 것입니다. 자주 반복되는 패턴이 생기면 나만의 방식을 다듬어가면 되지만, 처음에는 그냥 프롬프트로 시작해보는 것이 다양한 사용 사례를 익히기에 좋은 방법입니다.

활용 사례

좀 더 구체적으로 살펴볼 수 있도록, 마크다운보다 HTML 파일이 더 적합하다고 생각하는 활용 사례 예시를 아래에 정리했습니다. GitHub 갤러리에서도 이 사례들을 확인할 수 있습니다. 여기를 참고하세요.

스펙 작성, 계획 수립, 탐색

HTML은 Claude가 문제를 깊이 파고들 수 있는 풍부한 작업 공간입니다. 새로운 문제에 접근할 때 저는 단순한 마크다운 계획서 대신, 여러 HTML 파일로 이루어진 네트워크를 만드는 방식을 택합니다. 예를 들어 Claude Code에게 먼저 다양한 접근 방식을 브레인스토밍하고 각 옵션에 대한 탐색 결과를 만들어달라고 한 뒤, 그 중 하나를 더 깊이 발전시켜 인터페이스 목업이나 예시를 만들게 합니다. 방향이 잡히면 구현 계획서를 작성하도록 요청하고, 계획이 마음에 들면 새 세션을 열어 이 파일들을 모두 전달해 구현을 시작합니다.

검증 단계에서도 검증 에이전트에게 이 파일들을 읽게 하면, 요구사항에 대한 훨씬 넓은 컨텍스트를 바탕으로 작업할 수 있습니다.

‍

예시 프롬프트:

온보딩 화면의 방향을 아직 정하지 못했어. 레이아웃, 톤, 정보 밀도를 각각 다르게 해서 6가지 확연히 다른 접근 방식을 만들어줘. 하나의 HTML 파일에 그리드로 나란히 배치해서 한눈에 비교할 수 있게 해주고, 각각 어떤 트레이드오프를 취하고 있는지 레이블로 표시해줘.
HTML 파일로 꼼꼼한 구현 계획을 작성해줘. 목업도 넣고, 데이터 흐름도 보여주고, 검토가 필요한 주요 코드 스니펫도 포함해줘. 읽고 파악하기 쉽게 구성해줘.

활용 상황:

코드의 다른 구현 방식 탐색
여러 시각적 디자인 동시 실험

코드 리뷰와 이해

마크다운에서는 코드를 읽기가 까다롭지만, HTML에서는 diff, 주석, 플로우차트, 모듈을 모두 렌더링할 수 있습니다. 에이전트가 작성한 코드를 이해하거나, 코드를 리뷰하거나, 리뷰어에게 PR을 설명할 때 HTML을 활용해보세요.

‍

예시 프롬프트:

이 PR을 리뷰할 수 있도록 HTML 아티팩트로 설명해줘. 나는 스트리밍/백프레셔 로직에 익숙하지 않으니 그 부분에 집중해줘. 실제 diff를 인라인 마진 주석과 함께 렌더링하고, 발견된 사항은 심각도에 따라 색상으로 구분해줘. 개념을 잘 전달하는 데 필요한 건 뭐든 추가해줘.

활용 상황:

PR 작성
PR 리뷰
코드의 특정 개념 이해

디자인과 프로토타입

Claude Design이 HTML 기반인 것은, 최종 결과물이 HTML이 아니더라도 HTML이 디자인 표현에 있어 탁월하기 때문입니다. Claude는 HTML로 디자인을 먼저 스케치한 뒤, React나 Swift 등 원하는 언어로 재작성할 수 있습니다.

애니메이션, 동작 등 다양한 인터랙션도 프로토타이핑할 수 있습니다. Claude에게 슬라이더나 노브 같은 컨트롤을 만들어달라고 요청해 원하는 결과를 정밀하게 다듬어보세요.

‍

예시 프롬프트:

새로운 결제 버튼을 프로토타입으로 만들고 싶어. 클릭하면 재생 애니메이션이 실행되고 버튼이 빠르게 보라색으로 바뀌는 방식이야. HTML 파일에 슬라이더와 옵션들을 만들어줘서 이 애니메이션을 여러 방식으로 실험해볼 수 있게 해줘. 마음에 드는 파라미터를 복사할 수 있는 복사 버튼도 넣어줘.

활용 상황:

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

리포트, 리서치, 학습

Claude Code는 여러 데이터 소스에 걸친 정보를 종합해 읽기 쉬운 리포트로 만드는 데 탁월합니다. Slack, 코드베이스, git 히스토리, 인터넷 검색 결과를 바탕으로 가독성 높은 리포트를 생성하도록 요청해보세요.

긴 HTML 문서, 인터랙티브 설명 자료, 슬라이드쇼/덱 형태 등 다양한 방식으로 구성할 수 있습니다. 다이어그램은 SVG를 활용해 시각적으로 표현해달라고 요청해보세요.

예시 프롬프트:

우리 레이트 리미터가 실제로 어떻게 동작하는지 잘 모르겠어. 관련 코드를 읽고 HTML 설명 페이지 하나로 만들어줘. 토큰 버킷 흐름 다이어그램, 핵심 코드 스니펫 3~4개에 주석 달아서, 그리고 아래에 '주의사항' 섹션도 넣어줘. 한 번 읽고 바로 이해할 수 있도록 구성해줘.

활용 상황:

기능 요약 정리
개념 설명 자료 생성
주간 현황 리포트 작성
인시던트 리포트 작성
SVG 일러스트레이션, 플로우차트, 기술 다이어그램 제작

맞춤형 편집 인터페이스

원하는 것을 텍스트만으로 설명하기 어려울 때가 있습니다. 이런 경우, 저는 Claude에게 지금 작업 중인 내용에 딱 맞는 일회용 편집기를 만들어달라고 요청합니다. 완성된 제품도, 재사용 가능한 도구도 아닌, 이 데이터 하나를 위해 존재하는 HTML 파일입니다.

핵심은 항상 내보내기 기능으로 마무리하는 것입니다. UI에서 작업한 내용을 Claude Code에 붙여넣거나 파일로 커밋할 수 있도록, "JSON으로 복사" 또는 "프롬프트로 복사" 버튼을 넣는 것이 포인트입니다. 루프에서 벗어나지 않으면서도, 그 루프를 훨씬 촘촘하게 만들 수 있습니다.

예시 프롬프트:

Linear 티켓 30개의 우선순위를 다시 정해야 해. 각 티켓을 드래그 가능한 카드로 만들어서 지금(Now) / 다음(Next) / 나중에(Later) / 보류(Cut) 컬럼에 배치하는 HTML 파일을 만들어줘. 네가 생각하는 최선의 순서로 미리 정렬해두고, "마크다운으로 복사" 버튼도 추가해줘. 최종 순서를 내보낼 때 각 버킷별로 한 줄짜리 이유도 함께 포함되도록 해줘.
여기 우리 피처 플래그 설정 파일이야. 폼 기반 편집기로 만들어줘. 영역별로 플래그를 묶고, 플래그 간 의존 관계를 보여주고, 전제 조건이 꺼진 플래그를 활성화하려 하면 경고를 표시해줘. 변경된 키만 알 수 있도록 "diff 복사" 버튼도 넣어줘.
시스템 프롬프트를 다듬고 있어. 좌우 분할 편집기로 만들어줘. 왼쪽에는 변수 슬롯이 강조된 편집 가능한 프롬프트, 오른쪽에는 채워진 템플릿을 실시간으로 렌더링해주는 샘플 입력 3가지를 넣어줘. 글자 수/토큰 카운터와 복사 버튼도 추가해줘.

활용 상황:

항목 재정렬, 분류, 버킷 나누기 (티켓, 테스트 케이스, 피드백 등)
구조화된 설정 편집 (피처 플래그, 환경 변수, 제약 조건이 있는 JSON/YAML)
라이브 미리보기로 프롬프트, 템플릿, 문구 다듬기
데이터셋 큐레이션 — 행 승인/거부, 예시 태그 달기, 선택 내용 내보내기
문서, 대화 기록, diff에 주석 달고 내보내기
텍스트로 표현하기 어려운 값 선택: 색상, 이징 곡선, 크롭 영역, cron 스케줄, 정규식

자주 묻는 질문

Claude Code에서 HTML을 사용하는 것에 대해 가장 자주 받는 질문들과, 실제로 사용하면서 정착된 저의 방식을 함께 정리했습니다:

비효율적이지 않나요?

마크다운이 보통 더 적은 토큰을 사용하는 건 맞습니다. 하지만 HTML의 풍부한 표현력 덕분에 실제로 읽을 확률이 훨씬 높아지고, 그 결과 전반적인 산출물의 질이 올라간다는 걸 경험으로 느꼈습니다. Opus 4.7의 100만 토큰 컨텍스트 윈도우 덕분에 토큰 사용량 증가는 실질적으로 체감되지 않습니다.

지금도 마크다운을 쓰는 경우가 있나요?

솔직히 말하면, 거의 모든 상황에서 마크다운을 완전히 그만뒀습니다. 아마 제가 HTML 극단주의 쪽에 꽤 치우쳐 있는 편이긴 합니다.

계획 수립 방식이 바뀐 건가요?

단일 계획서 대신, 계획의 각 부분과 단계별로 여러 HTML 파일을 나눠 사용하는 방식으로 바뀌었습니다. 예를 들어 구현 계획은 HTML로 작성하고, UI 탐색을 위한 별도 파일을 만든 뒤, 모든 디자인을 목록화한 HTML 컴포넌트를 따로 만들기도 합니다. 이 파일들은 나중에 참고하거나 검증 단계에서 활용할 수 있도록 보관해둡니다.

Claude와 긴밀하게 연결되어 있으려면

결국 제가 마크다운 대신 HTML을 쓰는 진짜 이유는, Claude와의 작업에서 훨씬 더 긴밀히 연결된 느낌을 받을 수 있기 때문입니다. Claude가 점점 더 많은 것을 처리하게 되면서, 계획을 꼼꼼히 읽는 일이 줄어들고 있다는 걸 느꼈습니다. Claude의 선택들을 그냥 넘기는 게 아니라 직접 관여하고 싶었고, HTML이 바로 그 역할을 해줬습니다. 지금은 예전 어느 때보다 루프 안에 있다는 감각이 뚜렷합니다.

Claude Code로 시작해보세요.

이 글은 기술 스태프 멤버 Thariq Shihipar가 작성했으며, Claude Code에서 HTML 파일을 사용하는 것에 대한 그의 개인적인 의견과 애정이 담겨 있습니다.

‍