Why use HTML?为什么使用 HTML？

A few things make HTML a better fit than Markdown for the kind of work I'm now doing with Claude Code, including tasks that require or entail: 有几件事使得 HTML 比 Markdown 更适合我现在使用 Claude Code 的工作，包括需要或涉及的任务：

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:与 Markdown 相比，HTML 能传达更丰富的信息。它当然可以做标题和格式等简单的文档结构，但它也可以表示各种其他信息，例如：

• Tabular data using tables使用表格呈现表格数据
• Design data with CSS使用 CSS 设计数据
• Illustrations with SVG使用 SVG 绘制插图
• Code snippets with script tags使用 script 标签嵌入代码片段
• Interactions using HTML elements with javascript + CSS使用 HTML 元素配合 JavaScript + CSS 实现交互
• Workflows using SVG and HTML使用 SVG 和 HTML 构建工作流
• Spatial data using absolute positions and canvases 使用绝对定位和画布表示空间数据
• Images using image tags使用 image 标签插入图像

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 图表，或者我最喜欢的，用 Unicode 字符估计颜色。

‍

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 可以在视觉上组织结构，使其通过标签、插图和链接便于导航。它甚至可以实现移动端响应式，以便根据不同的设备形态呈现不同的阅读方式。

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 文件相对难以共享，因为大多数浏览器并不能原生良好渲染它们。通常需要将它们作为附件发送邮件或消息。

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 格式，实际被阅读的概率会大大提升。

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.在需要时，这可以为你正在处理的特定问题创建独立的编辑环境。

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 Code 生成 HTML 文件而不是 Claude.ai 或 Claude Design 的最大原因之一是 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 历史获取额外上下文。

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.值得注意的一点是：让 Claude 生成这样的 HTML 并不需要太多操作。你只需提示它“生成一个 HTML 文件”或“生成一个 HTML 成果”。关键是明确你希望该成果实现什么以及如何使用。随着时间推移，你可以围绕常见模式构建技能，但从零开始提示是了解其在不同用例中如何工作的好方法。

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. You can also follow along with a GitHub gallery of these use cases, here.为了让这个方法更具体，下面列出了一些我认为使用 HTML 文件比 Markdown 更合适的示例场景。你也可以在 GitHub 上的画廊中查看这些用例，点此。

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 深入问题提供了丰富的画布。当我开始处理一个问题时，我倾向于创建一系列 HTML 文件，而不是简单的 Markdown 计划。例如，我可能先让 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.在验证阶段，我也会让验证代理读取这些文件，它将拥有更广泛的上下文来判断所需内容。

‍

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.我不确定该如何设计 onboarding 界面。生成 6 种截然不同的方案——在布局、语气和密度上各有变化——并以网格形式放在同一个 HTML 文件中，以便我并排比较。为每个方案标注其权衡取舍。
• Create a thorough implementation plan in a 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一次性实验多种视觉设计

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 我们可以渲染差异、注释、流程图和模块。使用 HTML 来理解代理编写的代码、审查代码或向审阅者解释 PR。

‍

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 成果。我对流媒体/背压逻辑不太熟悉，请重点关注该部分。渲染实际的 diff，加入行内边距注释，按严重程度对发现进行颜色标记，并加入其他必要信息以清晰传达概念。

Use this for: 

• Creating a PR创建 PR
• Reviewing a PR审查 PR
• Understanding a topic in code理解代码中的主题

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 在设计方面极具表现力，即使最终产出不是 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.你还可以原型化交互，例如动画、动作等。考虑让 Claude 制作滑块、旋钮等，以精准调校你想要的效果。

‍

Example prompt: 

I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a 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调整组件
• Visualizing component libraries可视化组件库
• Prototyping  animations原型化动画

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 在跨多个数据源综合信息并转化为易读报告方面非常高效。你可以提示 Claude 搜索你的 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 文档、交互式说明或幻灯片/演示文稿。让 Claude 使用 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 段关键代码片段，以及底部的“注意事项”章节。针对一次性阅读的用户进行优化。

Use this for:

• Writing feature summarizations编写功能概述
• Generating explainers生成解释文档
• Drafting weekly status reports 起草每周状态报告
• Creating incident reports 创建事故报告
• Producing SVG illustrations, flowcharts, and technical diagrams,生成 SVG 插图、流程图和技术图示

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 票。为我生成一个 HTML 文件，将每张票作为可拖拽卡片放在 Now / Next / Later / Cut 四列中。按你的最佳猜测预先排序。添加一个“复制为 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.这是我们的功能标志配置。为其构建基于表单的编辑器，按区域分组标志，显示它们之间的依赖关系，如果启用了前置标志关闭的标志则给出警告。添加一个“复制差异”按钮，仅输出已更改的键。
•  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.我正在调优这个系统提示。制作一个并排编辑器：左侧为可编辑提示并高亮变量槽，右侧提供三个示例输入，实时渲染填充后的模板。加入字符/令牌计数器和复制按钮。

Use this for:

• Reordering, triaging, or bucketing anything (tickets, test cases, feedback)重新排序、分流或分桶任何内容（票据、测试用例、反馈）
• Editing structured config (feature flags, env vars, JSON/YAML with constraints)编辑结构化配置（功能标志、环境变量、带约束的 JSON/YAML）
• Tuning prompts, templates, or copy with live preview调优提示、模板或文案并实时预览
• Curating datasets — approve/reject rows, tag examples, export the selection策划数据集——批准/拒绝行，标记示例，导出所选内容
• Annotating a document, transcript, or diff and exporting the annotations为文档、转录或 diff 加注并导出注释
• Picking values that are painful to express in text: colors, easing curves, crop regions, cron schedules, regexes挑选难以用文字表达的值：颜色、缓动曲线、裁剪区域、cron 表达式、正则

Frequently asked questions常见问题

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 的问题，以及我形成的实用日常习惯：

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 通常使用更少的 token，但我发现 HTML 的表达力更强，加上我更可能阅读它，整体输出质量更好。使用 Opus 4.7 的 1MM 上下文窗口时，额外的 token 使用在窗口中几乎不明显。

When do you use Markdown for now?现在你什么时候会使用 Markdown？

I have honestly stopped using Markdown altogether for almost everything, but I’m probably far on the HTML maximalist side of things.说实话，我几乎已经不再使用 Markdown，几乎是 HTML 的极端拥护者。

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 a 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 组件列出所有设计。我会保留这些文件以供将来参考，也用于验证。

Staying in the loop with Claude与 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 正好满足了这一需求。现在我比以往任何时候都更有参与感。

Get started with Claude Code.开始使用 Claude Code。

This article was written by Thariq Shihipar, member of technical staff, and expresses his personal opinions – and affinity – for using HTML files with Claude Code. 本文由技术员工 Thariq Shihipar 撰写，表达了他个人对在 Claude Code 中使用 HTML 文件的观点和偏好。

‍