Claude Code 사용: HTML의 비합리적 효과

• Claude Code에서 Markdown 대신 HTML을 출력 형식으로 쓰면 시각화, 색상, 다이어그램, 상호작용을 더 풍부하게 담아 사람이 읽고 검토하기 쉬운 결과물을 만들 수 있음
• HTML은 표, CSS, SVG, script, JavaScript 상호작용, 이미지, 캔버스와 절대 위치를 활용해 Claude가 읽을 수 있는 정보 대부분을 효율적으로 표현해 줌
• Claude Code는 파일 시스템, MCP, 브라우저, Git 기록 같은 맥락을 읽어 HTML 결과물로 엮을 수 있으며, “HTML 파일을 만들어줘”라고 요청하는 것만으로 시작 가능함
• 주요 활용 방식은 스펙·계획·탐색, 코드 리뷰와 코드 이해, 디자인과 프로토타입, 보고서·리서치·학습, 맞춤형 일회용 편집 인터페이스로 나뉨
• HTML은 Markdown보다 생성이 2~4배 더 오래 걸리고 diff가 시끄러워 버전 관리가 어렵지만, 표현력과 공유 가능성, 실제로 읽힐 가능성이 더 큰 장점으로 꼽힘

Markdown 대신 HTML을 선호하게 된 이유

• Markdown은 에이전트가 사람과 소통하는 지배적인 파일 형식이 되었고, 단순하고 이식성이 좋으며 약간의 서식을 표현할 수 있고 사람이 직접 편집하기 쉬움
• Claude는 Markdown 안에서 ASCII 다이어그램도 잘 만들지만, 에이전트가 더 강력해질수록 Markdown은 제약적인 형식으로 느껴짐
• 100줄이 넘는 Markdown 파일은 읽기 어렵고, 더 풍부한 시각화·색상·다이어그램을 쉽게 공유하고 싶어짐
• 직접 파일을 편집하기보다 Claude에게 편집을 요청하는 경우가 많아지면서, Markdown의 큰 장점인 쉬운 직접 편집의 가치가 줄어듦
• Claude Code 팀 안에서도 HTML을 출력 형식으로 쓰는 경우가 늘고 있으며, 예시는 html-effectiveness에서 볼 수 있음

HTML의 표현력과 공유성

• HTML은 제목과 서식 같은 문서 구조뿐 아니라 Markdown보다 훨씬 다양한 정보를 표현할 수 있음
• 표현 가능한 정보에는 표를 통한 테이블 데이터, CSS를 통한 디자인 데이터, SVG 일러스트, script 태그를 통한 코드 조각, JavaScript와 CSS를 이용한 상호작용이 들어감
• SVG와 HTML로 워크플로를 나타내고, 절대 위치와 캔버스로 공간 데이터를 표현하며, img 태그로 이미지를 넣을 수 있음
• Claude가 읽을 수 있는 정보 집합 대부분은 HTML로 꽤 효율적으로 표현 가능하며, 모델이 깊이 있는 정보를 전달하고 사람이 검토하기에도 효율적인 형식이 됨
• HTML을 쓰지 못하면 Claude가 Markdown에서 ASCII 다이어그램을 만들거나, Unicode 문자로 색상을 추정하는 식의 비효율적인 표현을 쓰게 될 수 있음
• Claude가 더 복잡한 작업을 수행하면서 더 큰 스펙과 계획을 작성하게 되었고, 실제로 100줄이 넘는 Markdown 파일은 잘 읽히지 않음
• HTML 문서는 탭, 일러스트, 링크 등을 통해 구조를 시각적으로 구성할 수 있어 탐색하기 쉽고, 화면 크기에 따라 다르게 읽히도록 모바일 반응형으로도 만들 수 있음
• Markdown 파일은 브라우저가 기본적으로 잘 렌더링하지 않아 이메일이나 메시지에 첨부해야 하는 경우가 많지만, HTML은 S3 같은 곳에 올리면 링크로 쉽게 공유 가능함
• HTML로 된 스펙, 보고서, PR 설명은 동료가 열어보고 참조하기 쉬워 실제로 읽힐 가능성이 훨씬 높아짐
• HTML 문서는 슬라이더나 노브를 넣어 디자인을 조정하거나 알고리듬 옵션을 바꿔 결과를 확인하는 양방향 상호작용을 지원할 수 있음
• 조정한 내용을 Claude Code에 다시 붙여넣을 프롬프트로 복사하는 기능도 만들 수 있으며, 관련 예시는 playgrounds post에서 다룸

Claude Code와 HTML을 함께 쓰는 이유

• Claude Code는 파일 시스템, MCP, 브라우저, Git 기록 등 다양한 맥락을 읽어 HTML 결과물로 엮을 수 있음
• 예를 들어 코드 폴더에서 생성된 HTML 파일을 모두 찾고, 그룹화·분류한 뒤 각 유형을 대표하는 다이어그램이 담긴 HTML 파일을 만들 수 있음
• 파일 시스템 외에도 Slack, Linear 같은 MCP, Claude in Chrome을 통한 웹 브라우저, Git 기록 등에서 추가 맥락을 찾을 수 있음
• HTML 문서를 Claude와 함께 만드는 과정은 더 재미있고, 생성물에 더 관여하고 투자하고 있다는 느낌을 줌
• 별도의 /html 스킬을 만들 필요 없이 “HTML 파일을 만들어줘” 또는 “HTML artifact를 만들어줘”라고 요청하는 것만으로 시작할 수 있음
• 중요한 요령은 artifact가 무엇을 해야 하는지, 어떻게 사용할 것인지 아는 것이며, 처음에는 매번 처음부터 프롬프트를 작성해 다양한 용도를 익히는 편이 좋음

주요 활용 방식

• 스펙, 계획, 탐색

  • HTML은 Claude가 문제를 파고들기 위한 풍부한 캔버스가 되며, 단일 Markdown 계획 대신 여러 HTML 파일의 묶음으로 작업을 시작할 수 있음
  • 먼저 여러 방향을 브레인스토밍하고, 이후 한 방향을 확장해 목업이나 코드 조각을 만들고, 마지막으로 구현 계획을 작성하는 흐름이 가능함
  • 계획이 만족스러우면 새 세션을 만들고 이 파일들을 넘겨 구현할 수 있으며, 검증 에이전트도 같은 파일을 읽어 필요한 맥락을 더 넓게 확보할 수 있음
  • 온보딩 화면에 대해 레이아웃·톤·밀도가 다른 6가지 접근을 하나의 HTML 그리드로 만들고 각 선택의 트레이드오프를 표시하게 할 수 있음
  • 목업, 데이터 흐름, 검토할 코드 조각을 포함한 읽기 쉬운 HTML 구현 계획도 만들게 할 수 있음
  • 코드 구현 방식 탐색과 여러 시각 디자인 비교에 사용할 수 있음

• 코드 리뷰와 코드 이해

  • 코드는 Markdown 파일에서 읽기 어려울 수 있지만, HTML에서는 diff, 주석, 흐름도, 모듈 구조 등을 렌더링할 수 있음
  • 에이전트가 작성한 코드를 이해하거나, 코드 리뷰를 받거나, PR을 검토하는 사람에게 변경 내용을 설명하는 데 사용할 수 있음
  • 기본 GitHub diff 보기보다 더 잘 작동하는 경우가 있으며, PR마다 HTML 코드 설명 파일을 첨부하는 흐름도 가능함
  • PR 리뷰용 HTML artifact를 만들고, 익숙하지 않은 streaming/backpressure 로직에 집중하며, 실제 diff에 여백 주석을 달고 심각도별로 색을 입히게 할 수 있음
  • PR 작성, PR 리뷰, 코드 주제 이해에 사용할 수 있음

• 디자인과 프로토타입

  • Claude Design은 HTML을 기반으로 하며, HTML은 최종 표면이 HTML이 아니더라도 디자인 표현력이 높음
  • Claude는 HTML로 디자인을 스케치한 뒤 React, Swift 등 원하는 언어로 작성할 수 있음
  • 애니메이션, 액션 같은 상호작용을 프로토타입할 수 있고, 슬라이더나 노브를 넣어 원하는 값을 조정할 수 있음
  • 클릭 시 재생 애니메이션 후 빠르게 보라색으로 바뀌는 체크아웃 버튼을 만들고, 여러 슬라이더와 옵션 및 잘 맞는 파라미터를 복사하는 버튼을 포함하게 할 수 있음
  • 디자인 시스템 artifact 생성, 컴포넌트 조정, 컴포넌트 라이브러리 시각화, 즐거운 애니메이션 프로토타입에 사용할 수 있음

• 보고서, 리서치, 학습

  • Claude Code는 여러 데이터 소스의 정보를 종합해 읽기 쉬운 보고서로 바꾸는 데 강함
  • Slack, 코드베이스, Git 기록, 인터넷 등을 검색하게 하고, 자신·리더십·팀을 위한 읽기 쉬운 보고서를 생성할 수 있음
  • 결과물은 긴 HTML 문서, 인터랙티브 설명서, 슬라이드나 deck 형태가 될 수 있음
  • SVG를 사용해 다이어그램을 만들게 하면 시각화에 도움이 됨
  • prompt caching 관련 글을 준비할 때 Git 기록을 읽고 prompt caching 변경 사항 전체를 다룬 심층 HTML 리서치 파일을 만들게 한 방식이 사용됨
  • rate limiter의 관련 코드를 읽고 token-bucket 흐름 다이어그램, 주석이 달린 핵심 코드 조각 3~4개, 하단 gotchas 섹션을 포함한 단일 HTML 설명 페이지를 만들게 할 수 있음
  • 기능 동작 요약, 개념 설명, 주간 상태 보고, 사고 보고, SVG 일러스트·흐름도·기술 다이어그램에 사용할 수 있음

• 맞춤형 편집 인터페이스

  • 텍스트 박스만으로 원하는 것을 설명하기 어려울 때, 현재 작업 중인 데이터에 맞춘 일회용 HTML 편집기를 만들 수 있음
  • 제품이나 재사용 도구가 아니라, 특정 데이터 조각 하나를 위해 목적에 맞게 만든 단일 HTML 파일이 됨
  • 핵심은 마지막에 “copy as JSON” 또는 “copy as prompt” 같은 내보내기를 넣어, UI에서 조작한 결과를 Claude Code에 붙여넣을 수 있게 하는 것임
  • 30개 Linear 티켓을 Now / Next / Later / Cut 열의 드래그 가능한 카드로 만들고, 최종 순서를 bucket별 한 줄 근거와 함께 Markdown으로 복사하게 할 수 있음
  • feature flag 설정을 폼 기반 편집기로 만들고, 영역별로 묶고, 의존성을 표시하며, 전제 flag가 꺼진 상태에서 flag를 켜면 경고하고, 변경된 키만 diff로 복사하게 할 수 있음
  • 시스템 프롬프트를 조정할 때 왼쪽에는 편집 가능한 프롬프트와 강조된 변수 슬롯을 두고, 오른쪽에는 세 가지 샘플 입력을 실시간 렌더링하며, 문자·토큰 카운터와 복사 버튼을 넣을 수 있음
  • 티켓·테스트 케이스·피드백 재정렬, 구조화된 설정 편집, 프롬프트·템플릿·문구 조정, 데이터셋 큐레이션, 문서·전사·diff 주석, 색상·easing curve·crop region·cron schedule·regex처럼 텍스트로 표현하기 어려운 값 선택에 사용할 수 있음

자주 나오는 질문과 한계

• Markdown은 보통 토큰을 덜 쓰지만, HTML은 표현력과 실제로 읽힐 가능성이 높아 전체 결과물이 더 나아짐
• Opus 4.7의 1MM context window에서는 늘어난 토큰 사용량이 컨텍스트 창에서 크게 눈에 띄지 않음
• 거의 모든 용도에서 Markdown 사용을 중단했지만, 이는 HTML을 최대한 선호하는 쪽에 가까운 사용 방식임
• HTML 파일은 로컬 브라우저에서 열 수 있고, Claude에게 열어달라고 요청할 수도 있으며, 공유 가능한 링크가 필요하면 S3에 올릴 수 있음
• HTML 생성은 Markdown보다 더 오래 걸리며, 2~4배 더 걸릴 수 있지만 결과가 그만한 가치가 있다고 판단됨
• 가장 큰 단점 중 하나는 버전 관리로, HTML diff는 Markdown보다 시끄럽고 리뷰하기 어려움
• Claude가 취향에 맞는 HTML을 만들게 하려면 frontend design plugin이 도움이 됨
• 회사 스타일에 맞추려면 Claude가 코드베이스를 보게 해 단일 디자인 시스템 HTML 파일을 만들고, 이후 다른 HTML 파일의 참고 자료로 사용할 수 있음
• HTML을 쓰면 Claude가 작성한 계획을 깊이 읽지 않게 되어 선택을 맡겨야 한다는 두려움이 줄고, Claude와 작업하는 과정에서 더 많이 흐름 안에 머무를 수 있음