HTML로 Markdown 대체하기: Claude Code 팀의 1차 실무 사례（영문·중문 대조）

*Claude Code 사용: HTML의 엄청난 효과성*

저자: Thariq Shihipar (Anthropic Claude Code 엔지니어링 책임자) | 영문·중문 대조판

Markdown은 에이전트가 사람과 소통할 때 가장 널리 쓰이는 파일 형식이 되어 왔습니다. 단순하고 휴대성이 좋으며, 기본적인 리치 텍스트 기능을 제공하고, 수정도 간단합니다. Claude는 Markdown 파일 안에서 ASCII로 다이어그램을 그려내는 데에도 놀랍도록 능숙해졌습니다.

Markdown은 AI 에이전트와 사람이 소통할 때 가장 지배적인 파일 형식이 되어 왔습니다. 단순하고 휴대가 간편하며 어느 정도의 리치 텍스트 기능을 가지고 있고, 수동으로 편집하기도 매우 쉽습니다. 심지어 Claude는 Markdown 파일 안에서 ASCII 문자만으로 여러 종류의 도표를 그리는 데도 놀라울 만큼 능숙해졌습니다.

But as agents have become more and more powerful, I've found that Markdown has become an increasingly restrictive format. Specifically, I find it difficult to read a Markdown file of more than a hundred lines; I want to use Claude to generate richer visualizations, color and diagrams; and I want to be able to share these outputs more easily.

하지만 에이전트가 점점 더 강력해질수록, Markdown은 점점 제약이 많은 형식이 된다는 것을 알게 되었습니다. 특히 백여 줄이 넘는 Markdown 문서는 더 이상 읽기 어렵고, Claude에게 더 풍부한 시각화·색상·도표를 생성하게 하고 싶고, 이런 산출물을 더 쉽게 공유하고 싶기 때문입니다.

I also am increasingly not editing these files myself, but using them as specs and reference files. When I do make edits, I'm usually prompting Claude to edit them, which removes one of Markdown's largest benefits.

또한 저는 이 파일들을 점점 직접 편집하지 않고, 사양서(Spec)나 참고 문서로 사용하는 쪽으로 전환했습니다. 수정이 필요할 때도 대부분 Claude에게 프롬프트로 편집을 맡기기 때문에, Markdown의 가장 큰 장점인 “사람이 직접 수정하기 쉬움”은 사실상 사라집니다.

Instead, I've started preferring HTML as an output format instead of Markdown and increasingly see this pattern being applied by others on the Claude Code team. In this post, I share why and how our team uses HTML to produce richer, more readable Claude Code outputs.

대신 저는 Markdown 대신 HTML을 출력 형식으로 선호하기 시작했고, Claude Code 팀의 다른 구성원들도 점차 이 방식을 많이 사용하고 있음을 보게 되었습니다. 이 글에서 왜 그런지, 그리고 팀이 HTML로 더 풍부하고 가독성 높은 Claude Code 산출물을 만드는 방법을 공유합니다.

Claude Code를 막 시작했다면, CC Switch 도구 소개로 여러 Claude 도구를 빠르게 전환할 수 있습니다; Claude의 기능을 재사용 가능한 Skill로 패키징하는 방법은 Skill 입문을 참고하세요.

Claude Code를 막 시작했다면, CC Switch 도구 소개에서 여러 Claude 도구를 빠르게 전환하는 방법을 확인할 수 있습니다. Claude의 기능을 재사용 가능한 Skill로 패키징하는 방법은 《Skill 전문 기획 입문》에서 살펴보세요.

1. 왜 HTML을 사용하나요? / Why Use HTML?

제가 지금 Claude Code로 하는 작업 방식에 있어 Markdown보다 HTML이 더 잘 맞는 점이 몇 가지 있습니다.

아래 항목은 제가 지금 Claude Code를 통해 수행하는 작업에서 HTML이 Markdown보다 더 적합하다고 느끼는 이유입니다.

1. 정보 밀도 / Information Density

HTML can convey much richer information compared to Markdown. It can, of course, do simple document structure like headers and formatting, but it can also represent all sorts of other information such as:

HTML은 Markdown보다 훨씬 풍부한 정보를 전달할 수 있습니다. 물론 제목과 기본 서식 같은 단순한 문서 구조를 처리할 수 있지만, 더 나아가 다음과 같은 다양한 정보를 표현할 수 있습니다.

• Tabular data using tables
• Design data with CSS
• Illustrations with SVG
• Code snippets with script tags
• Interactions using HTML elements with JavaScript + CSS
• Workflows using SVG and HTML
• Spatial data using absolute positions and canvases
• Images using image tags

• <table>로 표현한 표 데이터
• CSS로 정리한 디자인 데이터
• SVG를 활용한 일러스트레이션
• <script> 태그를 활용한 코드 조각
• HTML 요소, JavaScript, CSS로 구현한 상호작용
• SVG와 HTML을 결합한 워크플로우
• 절대 좌표와 캔버스를 이용한 공간 데이터
• <img> 태그를 활용한 이미지 삽입

In my opinion, there is almost no set of information that Claude can read that you cannot efficiently represent with HTML. This makes it a highly efficient way for the model to communicate in-depth information to you and for you to review it.

제 관점에서 Claude가 이해할 수 있는 정보라면, HTML로 효율적으로 표현할 수 없는 정보는 거의 없습니다. 그래서 HTML은 모델이 당신에게 깊이 있는 내용을 전달하고, 당신이 이를 검토하기에도 매우 효율적인 방식입니다.

I've found that in the absence of being able to do this, the model may do more inefficient things in Markdown, like ASCII diagrams or, my favorite, estimating colors with unicode characters.

이러한 표현이 어렵다면, 모델은 Markdown에서 ASCII 다이어그램을 만들거나, 제일 골때리는 예로 유니코드 문자로 색상을 흉내 내는 식의 비효율적인 방식에 의존하게 됩니다.

2. 시각적 선명도와 가독성 / Visual Clarity and Ease of Reading

As Claude is capable of tackling more complex work, it's also able to write larger and larger specs and plans. I've found that I tend to not actually read more than a 100-line Markdown file, and I certainly am not able to get anyone else in my organization to read it.

Claude가 더 복잡한 작업을 다룰 수 있게 되면서, 더 크고 복잡한 사양서와 계획서를 쓰기 시작했습니다. 실제로 제 기준에서는 100줄이 넘는 Markdown 문서를 제대로 읽지 않게 되었고, 조직 내 다른 누군가가 그것을 읽는 건 더더욱 어렵습니다.

But HTML documents are much easier to read because Claude can organize the structure visually to be ideal to navigate with tabs, illustrations, and links. It can even be mobile responsive so you can read it differently based on your form factor.

하지만 HTML 문서는 훨씬 읽기 쉽습니다. Claude가 탭, 일러스트, 링크 같은 시각적 요소로 구조를 정돈해 탐색을 쉽게 만들 수 있고, 모바일 반응형으로 구성해 장치 크기에 맞게 다른 읽기 방식으로 제공할 수도 있습니다.

3. 공유하기 쉬움 / Ease of Sharing

Markdown files are fairly hard to share since most browsers do not render them natively well. You often have to add them as attachments to emails or messages.

대부분의 브라우저가 Markdown을 제대로 렌더링하지 못하기 때문에, Markdown 파일은 공유가 번거롭습니다. 보통 이메일이나 메시지에 첨부파일로 붙여넣어야 하죠.

As long as you upload the HTML file, you can share the link easily. Your colleagues can open it wherever they wish and easily reference it.

반면 HTML은 파일을 업로드만 하면 링크를 간단히 공유할 수 있습니다. 동료들은 원하는 기기에서 언제든 열어서 참고할 수 있습니다.

The chance of someone actually reading your spec, report, or PR writeup is much higher if it's in HTML.

요구사항 문서, 리포트, PR 설명서를 HTML로 작성하면, 누군가가 실제로 끝까지 읽을 가능성이 훨씬 높아집니다.

4. 양방향 상호작용 / Two-Way Interactions

HTML can also allow you to interact with the document; for example, you might want to ask it to add sliders or knobs to adjust a design or allow you to tweak different options in the algorithm to see what happens. You can also ask it to let you copy these changes into a prompt to paste back into Claude Code.

HTML은 문서와의 실제 상호작용도 가능합니다. 예를 들어 디자인을 조정할 수 있는 슬라이더나 노브를 추가해 결과를 실시간으로 바꿔 보거나, 알고리즘 옵션을 바꿔가며 영향을 확인할 수 있습니다. 변경한 내용을 프롬프트로 다시 복사해 Claude Code로 붙여넣도록 요청할 수도 있습니다.

When useful, this can allow you to create individual editing environments for the specific problem you're working on.

이런 방식은 당신이 현재 해결해야 하는 특정 문제에 맞춘 일회성 편집 환경을 만들 수 있게 해줍니다.

5. 데이터 수집 / Data Ingestion

One of the biggest reasons to use Claude Code to make HTML files instead of Claude.ai or Claude Design is all of the context Claude Code can ingest. For example, when writing this article, I asked Claude Code to read through my code folder and find all the HTML files I've generated, group and categorize them, and then make an HTML file with diagrams representing each type. The diagrams you see in this article are a direct result of that.

Claude.ai나 Claude Design 대신 Claude Code로 HTML 파일을 만들기를 권장하는 가장 큰 이유 중 하나는 Claude Code가 훨씬 더 많은 컨텍스트를 흡수할 수 있다는 점입니다. 이번 글을 작성할 때도, 제가 작성한 코드 폴더를 Claude Code가 읽고 생성된 HTML 파일을 모두 찾아 분류한 뒤, 각 유형별 특성을 도식화한 HTML 파일을 만들도록 요청했습니다. 이 글에서 보이는 도표는 바로 그 작업의 직접적인 결과입니다.

Besides the file system, Claude Code can find additional context using your MCPs (like Slack, Linear, etc.), your web browser (with Claude in Chrome), and your git history.

파일 시스템 외에도 Claude Code는 MCP(Slack, Linear 등), 브라우저(Chrome의 Claude 연동), Git 기록처럼 추가적인 컨텍스트 소스에서 정보를 가져올 수 있습니다.

2. 시작하기 / Getting Started

One thing worth noting: you don't need to do much to get Claude to generate HTML like this. You can simply prompt it to "make an HTML file" or "make an HTML artifact." The main thing is knowing what you want the artifact to do and how you might use it. Over time, it may make sense to build a skill around recurring patterns, but starting by prompting from scratch is a good way to get a feel for how it works across different use cases.

중요한 점은 이 같은 HTML을 생성하기 위해 복잡한 준비가 필요하지 않다는 것입니다. 그냥 “HTML 파일을 만들어 줘” 또는 “HTML artifact를 만들어 줘”라고 요청하면 됩니다. 핵심은 이 산출물이 무엇을 해야 하는지, 당신이 어떻게 활용할지를 미리 정하는 것입니다. 반복되는 패턴이 생기면 Skill로 정리해도 좋지만, 처음에는 매번 처음부터 프롬프트를 넣어보며 다양한 사용 사례에서의 동작을 체감하는 것이 가장 좋습니다.

3. 사용 시나리오 / Use Cases

To make this approach more concrete, below are some example use cases where I think using HTML files make more sense than Markdown.

이 방식을 조금 더 구체적으로 이해하려면, Markdown보다 HTML이 더 합리적으로 느껴지는 사용 사례를 아래에 정리해 봅니다.

1. 요구사항, 계획 및 탐색 / Specs, Planning, and Exploration

HTML is a rich canvas for Claude to dive into a problem. When I start working on a problem instead of a simple Markdown plan I expect to make a web of HTML files. For example, I might start with asking Claude Code to brainstorm and create some explorations of different options. I would then ask it to expand more into one, maybe make mockups or examples of the type interfaces. Finally, when I feel good I'll ask it to write an implementation plan. When I'm happy with the plan I'll create a new session and pass in all of these files for it to implement.

HTML은 Claude가 문제를 깊게 파고들 때 매우 강력한 캔버스가 됩니다. 단순한 Markdown 계획 하나를 기대하는 대신, 저는 HTML 파일들의 웹처럼 서로 연결된 산출물을 만들고자 합니다. 예를 들어 먼저 Claude Code에 브레인스토밍을 요청해 여러 방식의 탐색안을 생성하게 하고, 그중 하나를 골라 더 확장해 목업이나 타입 인터페이스 예시를 만들게 합니다. 방향이 잡히면 구현 계획서를 쓰게 하고, 최종적으로 만족스러울 때는 새 세션을 열어 이 모든 파일을 전달하고 구현을 진행합니다.

When verifying I'll also ask the verification agent to read in the files and it will have much broader context on what is needed.

검증 단계에서는 별도의 검증 에이전트에게도 이 HTML 파일들을 읽게 해서 더 넓은 맥락에서 무엇이 필요한지 판단하도록 합니다.

프롬프트 예시 / Example prompts:

I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches—vary layout, tone, and density—and lay them out as a single HTML file in a grid so I can compare them side by side. Label each with the tradeoff it's making.

온보딩 화면의 방향성을 아직 정하지 못했습니다. 레이아웃, 톤, 정보 밀도 측면에서 서로 뚜렷하게 다른 6가지 접근 방식을 만들어 주세요. 각 안을 하나의 HTML 파일에 그리드로 배치해 나란히 비교할 수 있게 해주고, 각 안이 어떤 트레이드오프를 택했는지 라벨을 붙여 주세요.

Create a thorough implementation plan in an HTML file, be sure to make some mockups, show data flow and add important code snippets I might want to review. Make it easy to read and digest.

HTML 파일 하나로 상세한 구현 계획을 작성해 주세요. 이해를 돕는 목업, 데이터 흐름도, 그리고 리뷰가 필요한 핵심 코드 조각을 꼭 포함해 주세요. 읽기 쉽게 정리해 주세요.

적용 시나리오 / Use this for:

• Exploring other ways to implement something in code / 코드의 다른 구현 방법 탐색
• Experimenting with multiple visual designs at once / 여러 가지 시각적 디자인을 한 번에 병렬로 탐색

• 코드 구현의 다른 접근 방식 탐색 / 코드를 다른 방식으로 구현할 수 있는 방법 찾기
• 여러 시각 디자인 동시 실험 / 여러 UI 디자인 안을 병렬로 비교

2. 코드 리뷰 및 이해 / Code Review and Understanding

Code can be difficult to read in a Markdown file, but with HTML, we can render diffs, annotations, flowcharts, and modules. Use HTML to understand code that the agent has written, to review code, or to explain a PR to someone reviewing your code.

Markdown에서는 코드를 읽기 어렵지만, HTML에서는 diff, 주석(annotation), 플로우차트, 모듈 구조를 렌더링해 보여줄 수 있습니다. AI가 쓴 코드를 이해하거나 코드 리뷰를 수행할 때, 또는 PR의 내용을 리뷰어에게 설명할 때 HTML이 특히 유용합니다.

프롬프트 예시 / Example prompt:

Help me review this PR by creating an HTML artifact that describes it. I'm not very familiar with the streaming/backpressure logic, so focus on that. Render the actual diff with inline margin annotations, color-code findings by severity and whatever else might be needed to convey the concept well.

이 PR을 검토하는 데 도움을 줄 HTML 아티팩트를 만들어 주세요. 저는 스트리밍/역압(backpressure) 로직에 익숙하지 않으니 그 부분을 집중적으로 다뤄주세요. 실제 diff를 인라인 마진 주석과 함께 렌더링하고, 발견 항목은 심각도에 따라 색으로 구분해 주세요. 개념을 잘 전달할 수 있는 모든 시각 요소를 함께 넣어 주세요.

적용 시나리오 / Use this for:

• Creating a PR / PR 생성에 대한 설명 문서 작성
• Reviewing a PR / 동료 또는 AI가 제출한 PR 검토
• Understanding a topic in code / 코드베이스의 특정 복잡한 주제를 빠르게 이해

• PR 설명서 작성 / PR에 대한 요약 문서 생성
• PR 리뷰 / 동료 또는 AI가 제출한 PR 검토
• 코드 주제 이해 / 코드베이스의 특정 복잡한 주제를 빠르게 파악

3. 디자인 및 프로토타입 제작 / Design and Prototypes

Claude Design is based on HTML because HTML is incredibly expressive at design, even if your end surface is not HTML. Claude can sketch out a design in HTML and then write it in your language of choice, be it React, Swift, etc.

Claude Design이 HTML 기반인 이유는 최종 대상 플랫폼이 HTML이 아니더라도 디자인 표현력이 매우 뛰어나기 때문입니다. Claude는 HTML로 먼저 디자인 초안을 그리고, 이후 React, Swift 등 원하는 언어로 변환할 수 있습니다.

You can also prototype interactions, such as animations, actions, etc. Consider asking Claude to make sliders, knobs, etc. to tune in exactly what you're looking for.

또한 애니메이션, 액션 같은 상호작용도 프로토타이핑할 수 있습니다. 슬라이더, 노브 등을 추가해 원하는 느낌을 정밀 조정해 보라고 요청해 보세요.

프롬프트 예시 / Example prompt:

I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create an HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well.

새로운 결제 버튼을 프로토타입하고 싶습니다. 클릭하면 재생 애니메이션이 실행되고, 빠르게 보라색으로 전환되는 동작입니다. 여러 개의 슬라이더와 옵션이 있는 HTML 파일을 만들어서 애니메이션 파라미터를 자유롭게 시험해 보게 해주세요. 그리고 잘 맞는 설정값을 복사할 수 있도록 복사 버튼을 넣어 주세요.

적용 시나리오 / Use this for:

• Creating design system artifacts / 디자인 시스템의 관련 컴포넌트 자산 생성
• Adjusting components / UI 컴포넌트 세부사항을 직관적으로 미세 조정
• Visualizing component libraries / 단조로운 컴포넌트 라이브러리를 시각화
• Prototyping animations / 애니메이션 인터랙션 프로토타입 제작

• 디자인 시스템 아티팩트 제작 / 디자인 시스템 컴포넌트 자산 생성
• 컴포넌트 조정 / UI 컴포넌트의 미세한 디테일을 직관적으로 조정
• 컴포넌트 라이브러리 시각화 / 정적인 컴포넌트 목록을 시각적으로 표현
• 애니메이션 프로토타입 제작 / 인터랙티브 모션 동작을 빠르게 실험

4. 보고서, 연구 및 학습 / Reports, Research, and Learning

Claude Code is very effective at synthesizing information across multiple data sources and converting it into a report for readability. You can prompt Claude to search your Slack, your codebase, git history, or the internet and use it to generate easy to read reports.

Claude Code는 여러 데이터 소스의 정보를 통합해 가독성 높은 보고서로 바꾸는 데 탁월합니다. Slack, 코드베이스, Git 이력, 인터넷을 검색하게 한 뒤 읽기 쉬운 리포트를 만들도록 프롬프트할 수 있습니다.

You could assemble this in the form of a long HTML document, an interactive explainer or even a slideshow/deck. Ask Claude to use SVG for diagrams to help visualize it.

이런 산출물은 긴 HTML 문서, 인터랙티브 설명 페이지, 심지어 슬라이드/슬라이드 데크 형식으로도 구성할 수 있습니다. 시각화를 위해 SVG 기반 다이어그램 사용을 요청하는 것이 좋습니다.

프롬프트 예시 / Example prompt:

I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3–4 key code snippets annotated, and a "gotchas" section at the bottom. Optimize it for someone reading it once.

우리 레이트 리미터가 실제로 어떻게 동작하는지 이해가 잘 안 됩니다. 관련 코드를 읽고 단일 HTML 설명 페이지로 만들어 주세요. 토큰 버킷 흐름도를 포함하고, 핵심 코드 스니펫 3~4개에 주석을 달아 주세요. 맨 아래에는 “주의할 점(gotchas)” 섹션을 추가하고, 한 번만 읽어도 이해할 수 있도록 배치와 가독성을 최적화해 주세요.

적용 시나리오 / Use this for:

• Writing feature summaries / 복잡한 기능의 동작 원리 요약
• Generating explainers / 어렵고 난해한 개념을 쉽게 설명
• Drafting weekly status reports / 이번 주 작업 보고서를 빠르게 작성
• Creating incident reports / 명확한 장애 회고 보고서 작성
• Producing SVG illustrations, flowcharts, and technical diagrams / SVG 삽화, 흐름도, 기술 아키텍처 다이어그램을 자동으로 생성

• 기능 요약 작성 / 복잡한 기능의 동작 원리 정리
• 개념 설명서 생성 / 어려운 개념을 타인에게 쉽게 설명
• 주간 진행 보고서 작성 / 주간 보고서 빠르게 초안 작성
• 장애/사고 보고서 작성 / 직관적인 사고 복기 문서 생성
• SVG 일러스트·플로우차트·기술 다이어그램 생성 / 자동으로 시각 자료 제작

5. 커스텀 편집 인터페이스 / Custom Editing Interfaces

Sometimes it's hard to describe what you want purely in a text box. For this use case, I'll often ask Claude to build me a throwaway editor for the exact thing I'm working on: not a product, or a reusable tool, but a single HTML file, purpose-built for this one piece of data.

때로는 텍스트 상자에 원하는 요구사항을 정확히 설명하기 어렵습니다. 이런 경우 저는 Claude에게 일회성 편집기를 하나 만들어 달라고 요청합니다. 제품이나 재사용 가능한 도구가 아니라, 현재 작업 대상 데이터 하나에 맞춘 단일 HTML 파일입니다.

The trick is always to end with an export: a "copy as JSON" or "copy as prompt" button that turns whatever I did in the UI back into something I can paste into Claude Code or commit to a file. You stay in the loop, but the loop gets much tighter.

핵심은 항상 내보내기 기능으로 마무리하는 것입니다. 예를 들어 “JSON으로 복사” 혹은 “프롬프트로 복사” 버튼을 넣어 UI에서 수행한 작업을 다시 Claude Code에 붙여넣거나 파일에 커밋할 수 있게 해야 합니다. 이렇게 하면 사용자는 작업 흐름의 루프 안에 남아 있으면서도 훨씬 밀도 높은 피드백 반복이 가능합니다.

프롬프트 예시 / Example prompts:

I need to reprioritize these 30 Linear tickets. Make me an HTML file with each ticket as a draggable card across Now / Next / Later / Cut columns. Pre-sort them by your best guess. Add a "copy as Markdown" button that exports the final ordering with a one-line rationale per bucket.

30개의 Linear 티켓 우선순위를 다시 정리해야 합니다. 각 티켓을 드래그 가능한 카드로 만들고, Now / Next / Later / Cut 네 칼럼에 배치한 HTML 파일을 만들어 주세요. 가능하면 당신의 판단으로 먼저 정렬해 주세요. 마지막에 “Markdown으로 복사” 버튼을 추가해, 최종 정렬 결과를 각 버킷당 한 줄 분류 근거와 함께 내보내게 해 주세요.

Here's our feature flag config. Build a form-based editor for it, group flags by area, show dependencies between them, warn me if I enable a flag whose prerequisite is off. Add a "copy diff" button that gives me just the changed keys.

여기에 기능 플래그 설정이 있습니다. 이를 위한 폼 기반 편집기를 만들어 주세요. 기능 영역별로 플래그를 그룹화하고, 플래그 간 의존 관계를 표시해 주세요. 선행 조건이 비활성화된 상태에서 어떤 플래그를 켜면 경고가 뜨도록 해 주세요. 그리고 변경된 키만 추려 “copy diff” 버튼으로 복사할 수 있게 해 주세요.

I'm tuning this system prompt. Make a side-by-side editor: editable prompt on the left with the variable slots highlighted, three sample inputs on the right that re-render the filled template live. Add a character/token counter and a copy button.

이 시스템 프롬프트를 튜닝하고 있습니다. 좌측에는 편집 가능한 프롬프트를 두고 변수 슬롯을 강조 표시해 주세요. 우측에는 3개의 샘플 입력값을 두어 템플릿이 실시간으로 다시 렌더링되게 해 주세요. 또한 문자/토큰 카운터와 복사 버튼도 넣어 주세요.

적용 시나리오 / Use this for:

• Reordering, triaging, or bucketing anything / 어떤 항목이든 재정렬, 우선순위 분류 또는 그룹화(작업 단, 테스트 케이스, 사용자 피드백)
• Editing structured config / 구조화된 설정 편집(기능 토글, 환경 변수, 제약 조건이 있는 JSON/YAML)
• Tuning prompts and templates with live preview / 실시간 미리보기 기능을 활용해 프롬프트, 템플릿 또는 카피를 튜닝
• Curating datasets / 데이터셋 정리, 특정 데이터 행 승인/거부, 샘플 라벨링 및 선택 결과 내보내기
• Annotating documents, transcripts, or diffs / 장문 문서, 녹취록, 코드 차이에 상세 주석을 추가하고 내보내기
• Picking values painful to express in text / 텍스트만으로 설명하기 어려운 파라미터 선택: 색상 코드, 애니메이션 이징 커브(Easing Curve), Cron 스케줄 표현식, 정규식 등

• 임의 항목의 재정렬·우선순위 정렬·버킷 분류 / 티켓, 테스트케이스, 사용자 피드백 등
• 구조화된 설정 편집 / 기능 플래그, 환경 변수, 제약이 있는 JSON/YAML 편집
• 실시간 미리보기로 프롬프트/템플릿 튜닝 / 실시간 렌더링과 함께 문구·템플릿 보정
• 데이터셋 큐레이션 / 데이터셋 정리, 행 단위 승인/거절, 라벨링, 선택 항목 추출
• 문서·대본·diff 주석 처리 / 긴 문서, 전사록, 코드 차이점에 주석을 붙여 내보내기
• 텍스트로 표현하기 어려운 값 선택 / 색상 코드, 이징 커브, Cron 표현식, 정규식 등

자주 묻는 질문

These are the questions I get asked most often about using HTML with Claude Code, paired with the practical, day-to-day habits I've landed on.

Claude Code에서 HTML을 사용할 때 가장 자주 받는 질문과, 제가 실제로 적용해온 실무적 답변입니다.

이렇게 하면 더 많은 토큰이 낭비되지 않나요?

Q: Isn't it less efficient?

While Markdown often uses fewer tokens, I've found that the added expressiveness of HTML and the much higher likelihood of me reading it means I get overall better output. With the 1MM context window in Opus 4.7, the increased token usage is not really noticeable in the context window.

Markdown은 대체로 토큰을 적게 쓰는 편이지만, HTML의 표현력이 훨씬 높고 제가 실제로 읽는 비중이 커서 전체적으로는 더 나은 결과를 얻습니다. Opus 4.7의 1MM 컨텍스트 윈도우에서는 늘어나는 토큰이 실제 창 크기에서 체감될 정도로 크지 않습니다.

언제는 Markdown을 사용하나요?

Q: When do you use Markdown now?

I have honestly stopped using Markdown altogether for almost everything, but I'm probably far on the HTML maximalist side of things.

솔직히 말해, 지금은 거의 모든 용도에서 Markdown 사용을 멈췄습니다. 다만 제가 HTML 과몰입 쪽으로 한쪽으로 치우친 성향이 강한 편이라는 점은 인정합니다.

생성된 HTML 파일은 어떻게 확인하나요?

Q: How do I view the generated HTML file?

I usually open it locally in a browser (you can even ask Claude to open it for you). If I want to share a link, I just upload it to S3.

보통 로컬 브라우저에서 직접 엽니다(원하면 Claude에게 열어 달라고 요청할 수도 있습니다). 링크로 공유하고 싶을 때는 S3 같은 곳에 업로드해서 전달합니다.

HTML 생성이 Markdown보다 느리지 않나요?

Q: Doesn't it take longer to generate?

Yes! HTML can take 2-4x longer to generate than Markdown, but in my testing, the output is consistently worth the wait.

맞습니다. HTML은 Markdown보다 생성 시간이 2~4배 더 걸리는 편입니다. 다만 실험해 보니 그만한 시간을 들일 만한 결과를 꾸준히 얻을 수 있었습니다.

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

Q: What about version control?

Honestly, this is one of HTML's biggest pain points. HTML diffs are very messy in version control tools compared to clean Markdown, making code review harder.

솔직히 이 부분은 HTML의 가장 큰 단점 중 하나입니다. Markdown보다 버전 관리에서의 Diff가 훨씬 지저분해져 코드 리뷰가 더 어렵습니다.

HTML로 계획 문서를 대체하려면?

Q: Is this how you've replaced planning?

I've found that instead of having a single plan, I tend to have a few different HTML files for different parts/stages of the plan. For example, I may make an implementation plan in HTML and then do another file for exploration of UIs, and then finally make an HTML component that lists every design. I tend to keep these files around as references for the future, as well for use in verification.

단일한 계획 문서 하나를 유지하기보다, 계획의 각 파트·단계별로 서로 다른 HTML 파일을 여러 개 둡니다. 예를 들어 구현 계획용 HTML을 먼저 만들고, 다음에는 UI 탐색용 파일, 마지막으로 모든 디자인을 나열한 HTML 컴포넌트를 만듭니다. 이런 파일은 나중을 위한 참고 자료이자 검증 단계에서 재활용할 자산으로 보관합니다.

Claude가 생성한 페이지를 미적으로 보기 좋게 만들려면 어떻게 하나요?

Q: How do I get Claude to generate pages that look good?

Claude's built-in frontend design capabilities already allow it to generate fairly nice HTML pages. But if you want pages to match your company's brand, you can ask Claude to scan your codebase and generate a design system HTML file. Then you can pass that file as reference whenever you need Claude to generate other HTML pages, and it will maintain a consistent style.

Claude의 기본 프론트엔드 설계 능력만으로도 꽤 나은 HTML 페이지를 만들 수 있습니다. 하지만 회사 브랜드 톤에 맞추고 싶다면, 코드베이스를 스캔해 디자인 시스템 HTML 파일을 생성하게 해 보세요. 이후 다른 HTML 생성을 할 때 참조 파일로 전달하면 스타일 일관성을 유지할 수 있습니다.

5. 사람과 Claude의 협업 유지 / Staying in the Loop with Claude

All of the above is to say that the real reason I use HTML instead of Markdown is that it helps me feel much more in the loop with Claude. As Claude takes on more, I'd noticed I was reading plans less closely, and I wanted a way to stay engaged with its choices rather than just hand them off. HTML turned out to be exactly that. I feel more in the loop now than I ever did before.

결국 제가 HTML을 Markdown보다 선호하는 본질적인 이유는, Claude와의 작업 루프 안에 더 깊이 들어가 있을 수 있기 때문입니다. Claude가 처리하는 일이 늘어나면서, 계획서를 정독하는 비중이 줄어드는 것을 느꼈고, 단순히 작업을 넘기는 것이 아니라 결정 과정에 더 오래 참여하고 싶었습니다. HTML이 그 해결책이었습니다. 이제는 이전보다 훨씬 더 작업 흐름의 핵심에 머물러 있습니다.

*이 글의 원저자는 Anthropic Claude Code 엔지니어링 책임자인 Thariq Shihipar이며, 이 글은 개인적인 견해와 사용 선호도를 반영합니다.*

*This article was written by Thariq Shihipar, engineering lead for Claude Code at Anthropic, and expresses his personal opinions and affinity for using HTML files with Claude Code.*

*이 글은 Anthropic의 Claude Code 엔지니어링 책임자 Thariq Shihipar의 원문 번역본으로, HTML 파일 기반 Claude Code 사용에 대한 그의 개인적 견해와 선호를 담고 있습니다.*

참고 자료

• Using Claude Code: The Unreasonable Effectiveness of HTML(원문)
• 샘플 HTML 파일 저장소
• Thariq Shihipar X(Twitter) 원문 글
• Simon Willison 해설과 요약

• Claude Code: HTML의 불합리할 정도로 높은 효과성 (원문)
• 예시 HTML 파일 라이브러리
• Thariq Shihipar X(Twitter) 원문 포스트
• Simon Willison 해설 및 요약