Claude Code 활용하기: HTML의 놀라운 효율성

마크다운은 에이전트가 우리와 소통하기 위해 사용하는 지배적인 파일 형식이 되었습니다. 간단하고, 이식성이 좋으며, 일부 리치 텍스트 기능을 갖추고 있고 사용자가 편집하기 쉽습니다. Claude는 심지어 마크다운 파일 내에서 ASCII를 사용해 다이어그램을 만드는 데 놀라울 정도로 능숙해졌습니다.

하지만 에이전트가 점점 더 강력해짐에 따라, 마크다운은 제약이 되는 형식이라고 느끼게 되었습니다. 100줄이 넘는 마크다운 파일은 읽기가 어렵습니다. 더 풍부한 시각화, 색상, 다이어그램을 원하며, 이를 쉽게 공유할 수 있기를 바랍니다.

또한 점점 더 이러한 파일을 직접 편집하기보다는, 명세서, 참조 파일, 브레인스토밍 결과물 등으로 사용하고 있습니다. 편집을 할 때도 보통 Claude에게 프롬프트를 입력해 편집하도록 하는데, 이는 마크다운의 가장 큰 장점 중 하나를 없애는 셈입니다.

저는 마크다운 대신 출력 형식으로 HTML을 선호하기 시작했으며, Claude Code 팀의 다른 사람들도 점점 더 HTML을 사용하는 것을 보고 있습니다. 그 이유는 다음과 같습니다.

(몇 가지 예제로 시작하고 싶다면, 여기에서 많이 볼 수 있습니다: https://thariqs.github.io/html-effectiveness, 다시 돌아와서 이유에 대해 더 읽어보세요.)

HTML을 사용하는 이유

정보 밀도

HTML은 마크다운에 비해 훨씬 풍부한 정보를 전달할 수 있습니다. 물론 헤더나 서식과 같은 간단한 문서 구조도 가능하지만, 다음과 같은 다양한 정보도 표현할 수 있습니다:

• 표를 사용한 테이블 데이터
• CSS를 사용한 디자인 데이터
• SVG를 사용한 일러스트레이션
• script 태그를 사용한 코드 스니펫
• JavaScript + CSS를 사용한 HTML 요소와의 상호작용
• SVG와 HTML을 사용한 워크플로우
• 절대 위치와 캔버스를 사용한 공간 데이터
• 이미지 태그를 사용한 이미지

Claude가 읽을 수 있는 정보 중 HTML로 상당히 효율적으로 표현할 수 없는 정보는 거의 없다고 해도 과언이 아닙니다. 이는 모델이 심층 정보를 사용자에게 전달하고 사용자가 이를 검토할 수 있는 매우 효율적인 방법입니다.

이것이 불가능할 때, 모델은 마크다운에서 ASCII 다이어그램이나, 제가 가장 좋아하는 방식인 Claude Code의 이 스크린샷처럼 유니코드 문자로 색상을 추정하는 등 비효율적인 작업을 수행할 수 있습니다.

Claude Code가 마크다운에서 색상을 표시하려는 시도

시각적 명확성 및 가독성

Claude가 더 복잡한 작업을 수행할 수 있게 됨에 따라, 점점 더 크고 방대한 명세서와 계획을 작성하고 있습니다. 실제로 저는 100줄이 넘는 마크다운 파일은 거의 읽지 않으며, 조직의 다른 사람들이 읽도록 하는 것도 확실히 어렵다는 것을 알게 되었습니다.

하지만 HTML 문서는 훨씬 읽기 쉽습니다. Claude는 탭, 일러스트레이션, 링크 등으로 탐색하기에 이상적인 구조를 시각적으로 구성할 수 있습니다. 모바일 반응형으로 만들어 기기에 따라 다르게 읽을 수도 있습니다.

공유의 용이성

마크다운 파일은 대부분의 브라우저가 기본적으로 잘 렌더링하지 않기 때문에 공유하기가 상당히 어렵습니다. 종종 이메일이나 메시지에 첨부 파일로 추가해야 합니다.

HTML을 사용하면 파일을 업로드(예: S3)하기만 하면 링크를 쉽게 공유할 수 있습니다. 동료들은 원하는 곳에서 열어 쉽게 참조할 수 있습니다.

명세서, 보고서 또는 PR 설명을 실제로 읽을 확률은 HTML 형식일 때 훨씬 더 높습니다.

양방향 상호작용

HTML을 사용하면 문서와 상호작용할 수 있습니다. 예를 들어, 디자인을 조정하기 위한 슬라이더나 노브를 추가하거나 알고리즘의 다양한 옵션을 조정하여 결과를 확인하도록 요청할 수 있습니다. 또한 이러한 변경 사항을 Claude Code에 다시 붙여넣을 수 있는 프롬프트로 복사하도록 요청할 수도 있습니다.

이러한 양방향 상호작용의 예시는 제 playgrounds 게시물에서 더 자세히 읽어보세요: https://x.com/trq212/status/2017024445244924382

데이터 수집

왜 ClaudeAI나 Claude Design 대신 Claude Code를 사용하여 HTML 파일을 만들까요? 가장 큰 이유 중 하나는 Claude Code가 수집할 수 있는 방대한 컨텍스트 때문입니다.

예를 들어, 이 글을 작성할 때 Claude Code에게 코드 폴더를 읽고 제가 생성한 모든 HTML 파일을 찾아 그룹화 및 분류한 다음, 각 유형을 나타내는 다이어그램이 포함된 HTML 파일을 만들도록 요청했습니다. 이 글에서 볼 수 있는 다이어그램이 바로 그 결과입니다.

파일 시스템 외에도 Claude Code는 MCP(예: Slack, Linear 등), 웹 브라우저(Chrome의 Claude), git 히스토리 등을 사용하여 추가 컨텍스트를 찾을 수 있습니다.

즐거움

Claude로 HTML 문서를 만드는 것은 더 재미있고, 창작 과정에 더 몰입하고 투자하게 만듭니다. 이것만으로도 충분한 이유가 됩니다.

시작하는 방법

사람들이 이 글을 읽고 /html 스킬 같은 것으로 만들어버릴까 봐 조금 걱정됩니다. 어느 정도 가치가 있을 수 있지만, Claude가 이 작업을 수행하도록 하는 데 많은 것이 필요하지 않다는 점을 강조하고 싶습니다. 그냥 "HTML 파일을 만들어 줘" 또는 "HTML 아티팩트를 만들어 줘"라고 요청하면 됩니다.

핵심은 아티팩트가 무엇을 하길 원하는지, 그리고 그것을 어떻게 사용할 것인지 아는 것입니다. 시간이 지나면서 스킬을 만들 수도 있겠지만, 지금은 다양한 경우에 어떻게 사용하는지 감을 잡기 위해 처음부터 프롬프트를 작성하는 것을 추천합니다.

사용 사례

이를 더 구체적으로 설명하기 위해 다양한 사용 사례에 맞는 여러 HTML 파일을 만들었습니다. 모든 파일은 여기에서 볼 수 있습니다: https://thariqs.github.io/html-effectiveness/ 여기서는 개요를 설명하겠습니다.

명세서, 계획 및 탐색

HTML은 Claude가 문제를 깊이 파고들 수 있는 풍부한 캔버스입니다. 문제를 작업하기 시작할 때, 단순한 마크다운 계획 대신 HTML 파일의 웹을 만들 것으로 기대합니다. 예를 들어, Claude Code에게 브레인스토밍을 하고 다양한 옵션에 대한 탐색 결과를 만들도록 요청하는 것으로 시작할 수 있습니다. 그런 다음 특정 옵션을 더 확장하고, 목업이나 코드 스니펫을 만들도록 요청할 것입니다. 마지막으로, 만족스러울 때 구현 계획을 작성하도록 요청할 것입니다. 계획이 마음에 들면 새 세션을 만들고 모든 파일을 전달하여 구현하도록 할 것입니다.

확인할 때는 확인 에이전트에게 파일을 읽도록 요청할 것이며, 에이전트는 필요한 것에 대해 훨씬 더 광범위한 컨텍스트를 갖게 됩니다.

예시 프롬프트:

• 온보딩 화면을 어떤 방향으로 가져가야 할지 모르겠어요. 6개의 완전히 다른 접근 방식을 생성해 주세요. 레이아웃, 톤, 밀도를 다양하게 하고, 하나의 HTML 파일에 그리드로 배치하여 나란히 비교할 수 있게 해주세요. 각각의 트레이드오프를 레이블로 표시해 주세요.
• 철저한 구현 계획을 HTML 파일로 만들어 주세요. 목업을 만들고, 데이터 흐름을 보여주고, 검토하고 싶은 중요한 코드 스니펫을 추가해 주세요. 읽고 이해하기 쉽게 만들어 주세요.

사용 사례:

• 코드에서 다른 구현 방법 탐색
• 여러 시각적 디자인 탐색

코드 리뷰 및 이해

코드는 마크다운 파일에서 읽기 어려울 수 있습니다. 하지만 HTML을 사용하면 diff, 주석, 순서도, 모듈 등을 렌더링할 수 있습니다. 에이전트가 작성한 코드를 이해하거나, 코드 리뷰를 받거나, 코드를 검토하는 사람에게 PR을 설명하는 데 사용하세요. 저는 이것이 기본 GitHub diff 보기보다 종종 더 효과적이라고 생각하며, 이제 모든 PR에 HTML 코드 설명을 첨부하고 있습니다.

예시 프롬프트:

이 PR을 설명하는 HTML 아티팩트를 만들어서 리뷰를 도와주세요. 저는 스트리밍/백프레셔 로직에 익숙하지 않으므로 그 부분에 집중해 주세요. 실제 diff를 인라인 여백 주석과 함께 렌더링하고, 심각도에 따라 결과를 색상으로 구분하고, 개념을 잘 전달하는 데 필요한 다른 모든 것을 포함해 주세요.

사용 사례:

• PR 생성
• PR 리뷰
• 코드의 주제 이해

디자인 및 프로토타입

Claude Design은 HTML을 기반으로 합니다. HTML은 디자인 측면에서 매우 표현력이 뛰어나기 때문입니다. 최종 표면이 HTML이 아니더라도 마찬가지입니다. Claude는 HTML로 디자인을 스케치한 다음 React, Swift 등 원하는 언어로 작성할 수 있습니다.

애니메이션, 액션 등과 같은 상호작용도 프로토타입할 수 있습니다. Claude에게 슬라이더, 노브 등을 만들어 정확히 원하는 것을 조정하도록 요청하는 것을 고려해 보세요.

예시 프롬프트:

새로운 체크아웃 버튼을 프로토타입하고 싶습니다. 클릭하면 재생 애니메이션이 실행되고 빠르게 보라색으로 변합니다. 이 애니메이션의 다양한 옵션을 시도할 수 있도록 여러 슬라이더와 옵션이 있는 HTML 파일을 만들어 주세요. 잘 작동한 매개변수를 복사할 수 있는 복사 버튼도 제공해 주세요.

다음에 사용:

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

보고서, 연구 및 학습

Claude Code는 여러 데이터 소스의 정보를 종합하여 읽기 쉬운 보고서로 변환하는 데 매우 능숙합니다. Claude에게 Slack, 코드베이스, git 히스토리, 인터넷 등을 검색하도록 프롬프트하여 자신, 리더십, 팀 등을 위한 매우 읽기 쉬운 보고서를 생성할 수 있습니다.

긴 HTML 문서, 대화형 설명, 또는 슬라이드쇼/덱 형태로 구성할 수 있습니다. Claude에게 SVG를 사용하여 다이어그램을 만들고 시각화하도록 요청하세요.

예를 들어, 프롬프트 캐싱에 대한 게시물을 위해 Claude에게 git 히스토리를 읽은 후 프롬프트 캐싱의 모든 변경 사항에 대한 심층 연구 파일을 HTML로 준비하도록 요청했습니다.

예시 프롬프트:

우리의 속도 제한기가 실제로 어떻게 작동하는지 이해하지 못하겠어요. 관련 코드를 읽고 하나의 HTML 설명 페이지를 만들어 주세요: 토큰 버킷 흐름의 다이어그램, 주석이 달린 3-4개의 주요 코드 스니펫, 그리고 하단에 "주의사항" 섹션. 한 번만 읽는 사람을 위해 최적화해 주세요.

다음에 사용:

• 기능 작동 방식 요약
• 개념 설명
• 상사에게 주간 상태 보고
• 리더십에 사고 보고서
• SVG 일러스트레이션, 순서도, 기술 다이어그램 등

맞춤형 편집 인터페이스

때로는 텍스트 상자만으로는 원하는 것을 순수하게 설명하기 어렵습니다. 이런 경우, Claude에게 지금 작업 중인 특정 작업을 위한 일회용 편집기를 만들어 달라고 요청합니다. 제품이나 재사용 가능한 도구가 아니라, 이 하나의 데이터 조각을 위해 특별히 제작된 단일 HTML 파일입니다.

항상 내보내기로 끝내는 것이 핵심입니다: UI에서 수행한 작업을 Claude Code에 다시 붙여넣을 수 있는 형식으로 변환하는 "JSON으로 복사" 또는 "프롬프트로 복사" 버튼을 만드는 것입니다.

예시 프롬프트:

• 이 30개의 Linear 티켓의 우선순위를 다시 지정해야 합니다. 각 티켓을 Now / Next / Later / Cut 열에 걸쳐 드래그 가능한 카드로 만든 HTML 파일을 만들어 주세요. 최선의 추측으로 미리 정렬해 주세요. 최종 순서를 버킷당 한 줄의 근거와 함께 내보내는 "마크다운으로 복사" 버튼을 추가해 주세요.
• 다음은 우리의 기능 플래그 구성입니다. 이를 위한 폼 기반 편집기를 만들어 주세요. 플래그를 영역별로 그룹화하고, 플래그 간의 종속성을 표시하며, 필수 조건이 꺼져 있는 플래그를 활성화하려고 하면 경고를 표시해 주세요. 변경된 키만 제공하는 "diff 복사" 버튼을 추가해 주세요.
• 이 시스템 프롬프트를 조정하고 있습니다. 나란히 편집기를 만들어 주세요: 왼쪽에는 변수 슬롯이 강조 표시된 편집 가능한 프롬프트, 오른쪽에는 채워진 템플릿을 실시간으로 다시 렌더링하는 세 개의 샘플 입력. 문자/토큰 카운터와 복사 버튼을 추가해 주세요.

다음에 사용:

• 모든 것의 재정렬, 분류 또는 버킷화 (티켓, 테스트 케이스, 피드백)
• 구조화된 구성 편집 (기능 플래그, 환경 변수, 제약 조건이 있는 JSON/YAML)
• 실시간 미리보기로 프롬프트, 템플릿 또는 카피 조정
• 데이터셋 큐레이션, 행 승인/거부, 예제 태그 지정, 선택 항목 내보내기
• 문서, 대본 또는 diff에 주석 달고 주석 내보내기
• 텍스트로 표현하기 어려운 값 선택: 색상, 이징 곡선, 자르기 영역, cron 스케줄, 정규식

자주 묻는 질문

HTML로 전환한 방법에 대해 많은 사람들에게 이야기했고, 몇 가지 반복되는 질문을 보았습니다.

토큰 효율성이 떨어지지 않나요?

마크다운이 종종 더 적은 토큰을 사용하지만, HTML의 추가된 표현력과 제가 읽을 가능성이 훨씬 높다는 점을 고려하면 전반적으로 더 나은 결과를 얻을 수 있습니다. Opus 4.7의 1MM 컨텍스트 윈도우에서는 증가된 토큰 사용량이 컨텍스트 윈도우에서 실제로 눈에 띄지 않습니다.

지금은 언제 마크다운을 사용하나요?

솔직히 말해서 거의 모든 것에 마크다운 사용을 중단했습니다. 하지만 아마도 HTML 최대주의 쪽에 크게 치우쳐 있을 것입니다.

HTML 파일을 어떻게 보나요?

보통 로컬에서 브라우저로 열거나(Claude에게 열어 달라고 요청할 수 있습니다), 공유 가능한 링크를 원하면 S3에 업로드합니다.

마크다운보다 생성하는 데 시간이 더 오래 걸리지 않나요?

네, 시간이 더 오래 걸립니다! HTML은 마크다운보다 2-4배 더 오래 걸릴 수 있지만, 결과는 그만한 가치가 있다고 생각합니다.

버전 관리는 어떻게 하나요?

솔직히 이것은 HTML의 가장 큰 단점 중 하나입니다. HTML diff는 마크다운에 비해 노이즈가 많고 검토하기 어렵습니다.

Claude가 내 취향에 맞게 / 못생기지 않게 만들려면 어떻게 해야 하나요?

프론트엔드 디자인 플러그인은 Claude가 좋은 HTML 파일을 만드는 데 도움이 됩니다. 하지만 회사 고유의 스타일을 맞추려면 Claude에게 코드베이스를 가리켜 단일 디자인 시스템 HTML 파일을 만들 수 있습니다. 그런 다음 해당 디자인 시스템 파일을 다른 HTML 파일의 참조로 사용할 수 있습니다.

루프 안에 머물기

위의 모든 내용은 제가 HTML을 사용하는 진짜 이유가 Claude와 훨씬 더 긴밀하게 연결되어 있다고 느끼기 때문이라는 것을 말하기 위한 것입니다. 계획을 깊이 읽지 않게 되면서 Claude가 스스로 결정을 내리도록 놔둬야 할까 봐 두려워지기 시작했습니다.

하지만 HTML을 사용할 때 이전보다 더 연결되어 있다고 느끼게 되어 기쁘게 말할 수 있습니다. 여러분도 그러길 바랍니다.