Claude Code 활용하기: HTML의 놀라울 정도로 뛰어난 효용성
TMT마크다운은 에이전트들이 우리와 소통할 때 사용하는 사실상 표준 파일 형식이 되었습니다. 단순하고, 이식성이 좋고, 일정 수준의 리치 텍스트 표현도 가능하며, 사람이 직접 편집하기도 쉽습니다. Claude는 마크다운 파일 안에서 ASCII를 써서 다이어그램을 그리는 데에도 이제 꽤 능숙해졌습니다.
하지만 에이전트들이 점점 더 강력해지면서, 저는 마크다운이 오히려 형식적으로 제약이 된다고 느끼기 시작했습니다. 100줄이 넘는 마크다운 파일은 읽기가 무척 힘들고, 저는 더 풍부한 시각화, 색상, 다이어그램을 원하며, 그것들을 쉽게 공유할 수 있기를 바랍니다.
게다가 저는 이 파일들을 직접 편집하기보다는, 스펙, 레퍼런스 파일, 브레인스토밍 산출물 등으로 사용하는 경우가 점점 더 많아지고 있습니다. 직접 수정이 필요할 때도 보통 Claude에게 편집을 요청하는 식으로 작업하기 때문에, 이 점은 마크다운이 가진 가장 큰 장점 중 하나를 사실상 없애버립니다.
그래서 저는 출력 포맷으로 마크다운 대신 HTML을 선호하기 시작했고, Claude Code 팀 내에서도 점점 이러한 방식이 더 많이 사용되는 모습을 보고 있습니다. 그 이유를 설명해 보겠습니다.
(먼저 예시들을 보고 싶다면, https://thariqs.github.io/html-effectiveness에서 한 번 쭉 살펴보셔도 됩니다. 다만 왜 이렇게 쓰는지에 대해서는 꼭 이 글로 다시 돌아와서 끝까지 읽어 주세요.)
왜 HTML인가?
정보를 얼마나 많이, 잘 담을 수 있는가
HTML은 마크다운에 비해 훨씬 더 풍부한 정보를 담아낼 수 있습니다. 기본적인 문서 구조(헤더, 서식 등)를 표현하는 것은 물론이고, 다음과 같은 온갖 종류의 정보를 표현할 수 있습니다.
- 표(table)를 이용한 표 형식 데이터
- CSS를 이용한 디자인 정보
- SVG를 이용한 일러스트레이션
- script 태그를 이용한 코드 스니펫
- HTML 요소 + JavaScript + CSS를 이용한 인터랙션
- SVG와 HTML을 결합한 워크플로우 표현
- absolute position과 canvas를 활용한 공간적/배치 데이터
- image 태그를 통한 이미지
저는 Claude가 읽을 수 있는 거의 모든 종류의 정보를 HTML로 꽤 효율적으로 표현할 수 있다고까지 생각합니다. 이는 모델이 여러분에게 깊이 있는 정보를 전달하고, 여러분이 그것을 검토하는 데 있어 매우 효율적인 방법이 됩니다.
이걸 할 수 없을 때, 모델은 마크다운 안에서 ASCII 다이어그램을 그리거나, 제가 특히 좋아하는(?) 방식인 아래 스크린샷처럼 유니코드 문자로 색을 “추정”해서 표현하는 등, 더 비효율적인 방식을 택하게 되곤 합니다.
Claude Code가 마크다운 안에서 색을 어떻게든 보여주려는 시도
보기 좋고 읽기 쉬운 구성
Claude가 더 복잡한 작업을 해낼 수 있게 되면서, 작성하는 스펙과 계획서도 점점 더 길고 방대해지고 있습니다. 그런데 실제로는 제가 100줄이 넘는 마크다운 파일을 끝까지 읽는 경우는 거의 없고, 조직 내 다른 사람들에게 그걸 읽게 만드는 것은 사실상 불가능에 가깝습니다.
반면 HTML 문서는 읽기가 훨씬 수월합니다. Claude는 탭, 일러스트, 링크 등을 활용해 구조를 시각적으로 잘 조직할 수 있고, 모바일에서도 잘 읽히도록 반응형 레이아웃을 만들 수도 있습니다. 덕분에 사용하는 기기 형태에 따라 다른 방식으로 읽을 수 있습니다.
공유하기가 훨씬 쉬움
마크다운 파일은 공유하기가 꽤 불편합니다. 대부분의 브라우저가 마크다운을 네이티브하게 잘 렌더링해주지 않기 때문에, 보통 이메일이나 메시지에 첨부 파일로 실어 보내야 합니다.
HTML의 경우, 파일만 업로드(예: S3)해두면 링크를 간단히 공유할 수 있습니다. 동료들은 원하는 환경에서 그 링크를 열어 쉽게 문서를 참조할 수 있죠.
스펙, 보고서, PR 설명문 등을 HTML로 만들면, 실제로 사람들이 그걸 읽어줄 가능성이 훨씬, 훨씬 높아집니다.
Two-way Interaction
HTML 문서는 여러분이 문서와 상호작용할 수 있도록 만들 수 있습니다. 예를 들어, 디자인을 조정할 수 있는 슬라이더나 노브(knob)를 추가해서, 알고리즘의 여러 옵션을 바꿔가며 어떤 결과가 나오는지 직접 확인해보고 싶을 수 있습니다. 또 이렇게 조정한 결과를 한 번에 복사해서 Claude Code 프롬프트에 붙여넣을 수 있도록 만들어달라고 요청할 수도 있습니다.
이런 양방향 상호작용에 대한 예시는 제가 쓴 playgrounds 글에서 더 자세히 볼 수 있습니다
데이터 수집 & 활용 방식
그렇다면 왜 ClaudeAI나 Claude Design이 아니라, 굳이 Claude Code를 사용해서 HTML 파일을 만들까요? 가장 큰 이유 중 하나는 Claude Code가 받아들일 수 있는 컨텍스트의 폭이 매우 넓기 때문입니다.
예를 들어, 이 글을 쓰면서 저는 Claude Code에게 제 코드 폴더 안의 HTML 파일들을 전부 훑어보고, 제가 만들어온 HTML 파일들을 찾아 유형별로 묶고 분류한 다음, 각 유형을 보여주는 다이어그램을 담은 새로운 HTML 파일을 만들라고 요청했습니다. 이 글에 등장하는 다이어그램들은 바로 그 결과물입니다.
파일 시스템 외에도 Claude Code는 MCP(예: Slack, Linear 등), 웹 브라우저(Chrome용 Claude), git 히스토리 등에서 추가 컨텍스트를 가져올 수 있습니다.
만드는 과정 자체가 즐겁다
Claude와 함께 HTML 문서를 만드는 일 자체가 훨씬 즐겁고, 제가 창작 과정에 더 깊이 관여하고 있다는 느낌을 줍니다. 사실 이 점만으로도 HTML을 쓸 이유로 충분합니다.
어떻게 시작하면 좋을까
사실 이 글을 읽은 사람들이 이걸 바로 /html 같은 스킬로 만들어버릴까 봐 조금 걱정이 됩니다. 물론 그런 방식에도 나름의 장점은 있겠지만, 제가 강조하고 싶은 점은: Claude에게 HTML을 쓰게 만들기 위해 꼭 뭔가 대단한 걸 준비할 필요는 없다는 것입니다. 그냥 “make a HTML file” 이나 “make a HTML artifact” 정도로 요청해도 충분합니다.
진짜 핵심은, 여러분이 그 아티팩트(artifact)로 무엇을 하고 싶은지, 그리고 그것을 어떻게 활용할지에 대한 상(image)을 가지고 있는가입니다. 시간이 지나면서 스킬을 만들 수도 있겠지만, 당장은 각 상황에 맞게 처음부터 프롬프트를 써보면서, 어떤 경우에 어떻게 쓰는 게 좋은지 감을 잡아보길 권합니다.
활용 사례
좀 더 구체적으로 설명하기 위해, 저는 다양한 사용 사례별로 여러 종류의 HTML 파일을 만들어 왔습니다. 전부 보고 싶다면 여기에서 확인할 수 있습니다.(https://thariqs.github.io/html-effectiveness/)
아래는 그 중 개요입니다.
스펙 잡기, 계획 세우기, 아이디어 탐색하기
HTML은 Claude가 어떤 문제에 깊이 파고들 때 사용할 수 있는 아주 풍부한 캔버스입니다. 어떤 문제를 시작할 때, 저는 이제 단순한 마크다운 계획서 하나 대신, 여러 개의 HTML 파일로 이루어진 “웹”을 만들 것이라 기대합니다. 예를 들면, 먼저 Claude Code에게 브레인스토밍을 시키고, 여러 가지 다른 옵션을 탐색하는 HTML 파일을 만들어 달라고 요청할 수 있습니다. 그러고 나서, 괜찮아 보이는 방향 하나를 골라 더 확장해보고, 목업이나 코드 스니펫을 만들도록 할 수 있습니다. 마지막으로, 방향성이 마음에 들면 구현 계획서를 작성해 달라고 요청합니다. 계획이 만족스러우면, 새 세션을 열고 이 모든 파일들을 컨텍스트로 넣어 실제 구현을 진행하게 합니다.
검증 단계에서도 검증용 에이전트에게 이 파일들을 읽게 하면, 필요한 것들에 대해 훨씬 넓은 컨텍스트를 갖고 검토를 진행할 수 있습니다.
예시 프롬프트:
- 온보딩 화면을 어느 방향으로 가져가야 할지 잘 모르겠어요. 레이아웃, 톤, 정보 밀도를 각각 다르게 해서 전혀 다른 방향의 시안 6가지를 만들어 주세요. 한눈에 비교할 수 있도록 하나의 HTML 파일 안에 그리드 형태로 배치해 주고, 각 시안마다 어떤 트레이드오프를 택했는지도 라벨로 표시해 주세요.
- 구현 계획을 한 번에 조망할 수 있는 상세한 플랜을 HTML 파일로 작성해 주세요. 몇 가지 목업과 데이터 흐름도, 제가 검토하면 좋을 핵심 코드 스니펫도 함께 넣어 주시고, 전체적으로 읽고 이해하기 쉽게 구성해 주세요.
활용 시나리오:
- 코드를 다른 방식으로 구현해 볼 수 있는 대안을 탐색할 때
- 여러 가지 시각적 디자인 방향을 비교·검토할 때
코드 구조를 파악하고 리뷰에 활용하기
코드는 마크다운 파일에서 읽기 꽤 힘든 대상입니다. 하지만 HTML을 사용하면 diff, 주석, 플로우차트, 모듈 구조 등 여러 요소를 한 번에 시각화할 수 있습니다. 이를 활용해서 에이전트가 작성한 코드를 이해하거나, 코드 리뷰를 받거나, PR을 검토하는 사람에게 내용을 설명하는 데 활용할 수 있습니다. 제 경험상, 기본 GitHub diff 뷰보다 이런 HTML 기반 설명이 훨씬 더 잘 작동했습니다. 그래서 저는 지금 제가 만드는 모든 PR에 HTML 코드 설명서를 하나씩 첨부하고 있습니다.
예시 프롬프트:
이 PR을 같이 리뷰할 수 있도록, PR 내용을 잘 설명해 주는 HTML 아티팩트를 하나 만들어 주세요. 제가 스트리밍/백프레셔 로직에는 익숙하지 않아서, 그 부분에 특히 집중해 주셨으면 합니다. 실제 diff를 렌더링하되, 여백에 인라인 주석을 달아 주고, 발견된 이슈는 심각도에 따라 색으로 구분해 주세요. 그 밖에 이 PR의 핵심을 잘 전달하는 데 필요한 요소들이 있다면 함께 넣어 주세요.
활용 시나리오:
- PR을 작성할 때
- PR을 리뷰할 때
- 특정 코드 주제나 개념을 이해하고 싶을 때
디자인 & 프로토타이핑
Claude Design은 HTML을 기반으로 합니다. 그만큼, HTML은 최종 표면이 HTML이 아닐지라도 디자인을 표현하는 데 엄청나게 풍부한 표현력을 갖고 있습니다. Claude에게 HTML로 디자인을 스케치하게 한 뒤, 그걸 React, Swift 등 원하는 언어로 다시 옮기게 할 수도 있습니다.
또한 애니메이션이나 액션 같은 인터랙션을 시제품(prototype)으로 만들어볼 수도 있습니다. 예를 들어 Claude에게 슬라이더나 노브 같은 컨트롤을 추가해달라고 요청해서, 원하는 결과가 나올 때까지 파라미터를 조정해볼 수 있습니다.
예시 프롬프트:
새로운 체크아웃 버튼을 하나 프로토타이핑해 보고 싶어요. 클릭하면 재생 애니메이션이 한 번 돌고, 그다음에 빠르게 보라색으로 바뀌는 동작을 했으면 합니다. 이 애니메이션의 여러 옵션을 직접 만져볼 수 있도록, 여러 개의 슬라이더와 설정 값을 넣은 HTML 파일을 만들어 주세요. 마음에 드는 조합을 찾으면 그 파라미터들을 한 번에 복사할 수 있는 버튼도 같이 넣어 주세요.
이런 데에 활용할 수 있습니다:
- 디자인 시스템용 컴포넌트 샘플 만들기
- 컴포넌트 세부 동작 미세 조정하기
- 컴포넌트 라이브러리를 시각적으로 정리해 보기
- 보고만 있어도 즐거운 애니메이션을 실험·프로토타이핑하기
리포트 만들기, 조사 정리하기, 개념 제대로 이해하기
Claude Code는 여러 데이터 소스를 가로질러 정보를 통합하고, 그것을 읽기 좋은 리포트로 바꿔주는 데에 굉장히 능숙합니다. Slack, 코드베이스, git 히스토리, 인터넷 등에서 관련 정보를 찾아, 나 자신을 위해, 리더십을 위해, 팀을 위해 읽기 쉬운 보고서를 만들어 달라고 프롬프트할 수 있습니다.
이걸 긴 HTML 문서나 인터랙티브한 설명 페이지, 혹은 슬라이드/데크 형태로 구성할 수도 있습니다. 특히 SVG를 사용해 다이어그램을 만들도록 부탁하면 시각화에 큰 도움이 됩니다.
예를 들어, 제가 프롬프트 캐싱에 대한 글을 쓸 때, git 히스토리를 모두 읽고 프롬프트 캐싱 변경 사항을 정리한 심층 HTML 리서치 파일을 만들어 달라고 Claude에게 요청했습니다.
예시 프롬프트:
우리 레이트 리미터가 실제로 어떻게 동작하는지 잘 모르겠어요. 관련 코드를 읽고, 하나의 HTML 설명 페이지를 만들어 주세요. 토큰 버킷(token-bucket) 흐름을 보여주는 다이어그램, 핵심이 되는 코드 스니펫 3~4개와 그에 대한 주석, 그리고 맨 아래에는 “주의할 점(gotchas)” 섹션을 넣어 주세요. 한 번만 읽어도 이해될 수 있도록 최적화해 주세요.
이런 데에 활용할 수 있습니다:
- 특정 기능이 어떻게 동작하는지 정리해서 보여줄 때
- 어떤 개념을 쉽게 설명해 달라고 할 때
- 상사에게 주간 상태 보고를 올릴 때
- 리더십 팀에 인시던트 리포트를 공유할 때
- SVG 다이어그램, 플로우차트, 기술 설명용 도식 등을 만들 때
특정 작업 전용 에디터 만들기
가끔은 텍스트 박스 안에서만 내가 원하는 것을 설명하기가 너무 어려울 때가 있습니다. 이럴 때 저는 Claude에게, 지금 제가 다루고 있는 “딱 그 데이터 한 덩어리”만을 위해 쓸 수 있는 일회용 에디터를 만들어 달라고 요청합니다. 제품이나 재사용 가능한 도구가 아니라, 정말 이 한 번을 위해 고안된 단일 HTML 파일입니다.
이때 중요한 요령은 항상 “export”로 마무리하는 것입니다. 예를 들어 “copy as JSON”이나 “copy as prompt” 같은 버튼을 달아서, UI에서 조작한 결과를 Claude Code에 붙여넣을 수 있는 형식으로 다시 변환해 주도록 하는 겁니다.
예시 프롬프트:
- 이 30개의 Linear 티켓 우선순위를 다시 정리해야 해요. 각 티켓을 Now / Next / Later / Cut 네 개 컬럼에 넣어서 드래그해서 옮길 수 있는 카드 형태로, HTML 파일 하나에 만들어 주세요. 처음엔 당신이 보기엔 가장 그럴듯한 순서로 미리 정렬해 두고, 마지막에는 최종 순서를 버킷별 한 줄짜리 이유와 함께 마크다운으로 내보내는 “copy as markdown” 버튼도 달아 주세요.
- 이게 우리 기능 플래그 설정입니다. 이걸 편집할 수 있는 폼 기반 에디터를 만들어 주세요. 플래그는 영역별로 묶어 보여 주고, 플래그 간 의존성도 표시해 주세요. 선행 플래그가 꺼져 있는데 그걸 필요로 하는 플래그를 켜려고 하면 경고를 띄워야 합니다. 마지막에는 바뀐 키만 추려서 보여주는 “copy diff” 버튼도 넣어 주세요.
- 지금 시스템 프롬프트를 튜닝하는 중입니다. 왼쪽에는 변수가 들어갈 부분을 하이라이트한 편집 가능한 프롬프트, 오른쪽에는 템플릿이 채워진 예시 입력 세 개가 실시간으로 다시 렌더링되는 형태의, 좌우 분할 에디터를 만들고 싶어요. 글자 수/토큰 수 카운터와, 마음에 든 버전을 복사할 수 있는 버튼도 함께 넣어 주세요.
이런 데에 활용할 수 있습니다:
- 티켓, 테스트 케이스, 피드백처럼 뭘 옮기고, 분류하고, 버킷으로 나눠 담아야 할 때
- 기능 플래그, 환경 변수, 제약이 많은 JSON/YAML 같은 구조화된 설정을 편집할 때
- 프롬프트나 템플릿, 카피를 라이브 프리뷰와 함께 조정하고 싶을 때
- 데이터셋을 다듬으면서 승인/거절하고, 태그를 달고, 선택된 것만 추려서 내보낼 때
- 문서, 대화록, diff에 주석을 달고 그 주석만 따로 뽑아낼 때
- 텍스트로 설명하기 고통스러운 값들(색상, 이징 커브, 크롭 범위, 크론 스케줄, 정규식 등)을 UI로 골라야 할 때
FAQ
제가 HTML로 전환하고 있다는 이야기를 여기저기 하다 보니, 반복해서 나오는 질문들이 몇 가지 있었습니다.
토큰 비효율적인 거 아니야?
마크다운이 보통 토큰을 덜 쓰는 건 맞아요. 그래도 저는 HTML이 훨씬 더 풍부하게 표현할 수 있고, 무엇보다 제가 실제로 그걸 읽을 확률이 훨씬 높아서, 전체적인 결과물은 오히려 더 좋아졌다고 느낍니다. Opus 4.7의 100만 토큰 컨텍스트 창에서는, HTML 때문에 토큰이 좀 더 드는 게 거의 체감이 안 되기도 하고요.
그럼 지금은 언제 마크다운을 써?
솔직히 말하면, 이제는 웬만한 건 거의 전부 마크다운을 안 쓰고 있습니다. 저 스스로도 HTML에 꽤 과몰입한 쪽이긴 할 거예요.
HTML 파일은 어떻게 봐?
보통은 그냥 로컬에서 브라우저로 열어 봅니다(Claude에게 대신 열어달라고 해도 되고요). 공유가 필요하면 S3 같은 데 올려서 링크만 돌립니다.
마크다운보다 생성 시간이 훨씬 오래 걸리는 거 아냐?
맞습니다, 더 오래 걸려요! HTML은 마크다운보다 2~4배 정도 오래 걸릴 때도 있습니다. 그래도 저는 그만한 값어치는 충분히 한다고 느꼈습니다.
버전 관리는 어떡해?
이건 솔직히 HTML의 가장 큰 단점 중 하나입니다. HTML diff는 시끄럽고, 마크다운에 비해 리뷰하기가 많이 힘듭니다.
Claude가 내 취향 맞춰서 안 촌스럽게 만들게 하려면?
프론트엔드 디자인 플러그인을 쓰면 Claude가 꽤 근사한 HTML을 만들어 줍니다. 거기에 더해, 회사 스타일에 맞추고 싶다면 코드베이스를 보여주고 한 번에 쓸 “디자인 시스템용 HTML 파일”을 하나 만들어 두면 됩니다. 이후에는 그 파일을 다른 HTML 아티팩트들이 참고하는 레퍼런스로 쓰면 돼요.
Stay in the Loop
위에서 이야기한 모든 내용을 한마디로 정리하면, 제가 HTML을 쓰는 진짜 이유는 Claude와 함께 일할 때 제가 훨씬 더 “루프 안에 있다(in the loop)”고 느끼기 때문이라는 점입니다. 예전에는, 제가 더 이상 계획서를 꼼꼼하게 읽지 않게 되면서, 결국 Claude가 내리는 선택을 그냥 받아들일 수밖에 없을 거라고 걱정하기도 했습니다.
하지만 지금은, HTML 덕분에 그 어느 때보다도 Claude와 함께 작업 과정에 깊이 관여하고 있다고 느끼고 있습니다. 여러분도 그렇게 느끼게 되길 바랍니다.
