用 HTML 替代 Markdown：Claude Code 团队第一手实践

*Using Claude Code: The Unreasonable Effectiveness of HTML*

作者：Thariq Shihipar（Anthropic Claude Code 工程负责人）| 英中对照版

Markdown has become the dominant file format used by agents to communicate with humans. It's simple, portable, has some rich text capability and is easy to edit. Claude has even gotten surprisingly good at using ASCII to make diagrams inside of Markdown files.

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.

但随着 AI 智能体变得越来越强大，我开始觉得 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 输出。

一、为什么用 HTML？ / Why Use HTML?

A few things make HTML a better fit than Markdown for the kind of work I'm now doing with Claude Code.

以下几点让 HTML 比 Markdown 更适合我现在使用 Claude Code 所做的工作。

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 结合绘制工作流图表
• 用绝对定位与 Canvas 展示空间分布数据
• 用 <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.

我发现，如果无法使用 HTML，模型往往会在 Markdown 里做些效率低下的替代，比如硬用 ASCII 字符拼图表，或者——我最哭笑不得的——用 Unicode 字符来生硬模拟颜色色块。

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 文件其实颇为麻烦，因为大多数浏览器无法直接良好地渲染它们，通常只能以附件形式硬塞进邮件或即时消息里。

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.

如果你的需求文档、分析报告或代码审查说明是 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 在页面上加几个滑块或旋钮，用来直观调整设计效果，或者微调算法参数看看结果如何变化。你甚至可以让它加一个按钮，把微调后的参数一键复制为提示词，直接粘贴回 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 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 任务看板等。它还能结合浏览器、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 Artifact」就行。真正的关键在于：你要清楚自己希望这个制品能做什么，以及你会如何使用它。也许随着时间推移，你会总结出一套可复用的技能模板，但就目前而言，我强烈建议从最简单的提示词开始，慢慢摸索它在不同场景下的用法。

三、使用场景 / 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.

为了让这套方法更加具体，以下是我认为使用 HTML 比 Markdown 更合适的几类核心场景。

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 进行头脑风暴，探索几种不同的实现方案；接着，深入展开其中一个，画些界面草图或写几段核心代码片段；最后，当方向清晰了，才让它写出详细的实施计划。等我对计划满意后，开启一个新会话，把这些 HTML 文件全部喂给它，正式开始敲代码。

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.

在验证环节，我也会让负责检查的 AI 智能体读取这些 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 / 并行探索多种视觉设计方案

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 时向评审人解释你的思路。

提示词示例 / 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，即接收方处理不过来时向发送方发出减速反馈的机制) 不太熟悉，请重点剖析这部分。请渲染出真实的代码差异，并在旁边加上行内注释，根据严重程度对问题进行颜色编码，还可以加上任何有助于传达概念的视觉图表。

适用场景 / Use this for:

• Creating a PR / 创建 PR 的说明文档
• Reviewing a PR / 审查同事或 AI 提交的 PR
• Understanding a topic in code / 快速理解代码库中的某个复杂主题

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.

你还可以用它来制作交互原型，比如动画效果或用户操作链路。不妨让 Claude 加上滑块和旋钮，这样你就能亲自动手，把细节微调到你心目中的完美状态。

提示词示例 / 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 / 制作动画交互原型

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 极其擅长整合海量的多源数据，并将它们提炼成可读性极强的报告。你可以让 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.

我一直搞不懂我们的限流器 (Rate Limiter) 到底是怎么工作的。请阅读相关代码，并为我生成一个单页的 HTML 讲解文档：包含一个令牌桶机制 (Token-Bucket) 的数据流向图、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 插图、流程图和技术架构图

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 任务单的优先级。请给我做一个 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.

这里是我们的功能开关 (Feature Flag) 配置文件。请为它生成一个基于表单的编辑器，按功能模块对开关进行合理分组，展示它们之间的依赖关系；如果我打开了一个开关但它的前置依赖还处于关闭状态，请弹窗警告我。最后加一个「复制差异」的按钮，只导出我修改过的键值对。

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.

我正在调优这个系统提示词 (System Prompt)。请做一个左右对照的编辑器：左边是可编辑的提示词模板，变量槽要高亮显示；右边放 3 个示例输入源，当我修改左边的模板时，右边要能实时渲染出填入变量后的最终效果。界面上还要有字符和 Token 的计数器，以及一个一键复制按钮。

适用场景 / 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 定时表达式、正则表达式等

四、常见问题 / 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.

以下是我在安利这套做法时被问得最多的几个问题，以及我日常摸索出来的实践答案。

Q: Isn't it less efficient?

Q：这样不会浪费更多 Token 吗？

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 高达 100 万 Token 的上下文窗口里，多花的这点 Token 几乎可以忽略不计。

Q: When do you use Markdown now?

Q：你现在什么时候还会用 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 极端主义者」的道路上走得太远了。

Q: How do I view the generated HTML file?

Q：怎么查看生成的 HTML 文件？

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）上就行。

Q: Doesn't it take longer to generate?

Q：生成 HTML 不是比 Markdown 慢吗？

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?

Q：那版本控制怎么办？

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，HTML 文件在版本控制工具里的差异对比 (Diff) 非常杂乱，代码审查起来比较头疼。

Q: Is this how you've replaced planning?

Q：这就是你替代计划文档的方式吗？

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，最后再做一个列出所有设计方案的 HTML 组件。这些文件我会长期保留，作为未来的参考，也用于验证环节。

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

Q：怎么让 Claude 生成的页面符合我的审美？

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 页面了。但如果你想让页面完全契合公司的品牌风格，可以让 Claude 扫描你的代码库，生成一个专属的「设计系统 HTML 文件」。之后，把这个文件作为参考资料丢给 Claude，它在生成其他 HTML 页面时就能保持高度一致的风格。

五、保持人机协同 / 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 的根本原因在于：它让我真切地感觉到，自己依然深度参与在与 Claude 协作的循环之中。随着 Claude 承担越来越多的工作，我曾发现自己越来越不认真读那些计划文档了——我想找到一种方式，让自己能真正参与到它的决策过程中，而不只是把任务交出去了事。HTML 正是这个答案。现在，我感觉自己比以往任何时候都更紧密地参与其中。

*本文原作者为 Thariq Shihipar（Anthropic Claude Code 工程负责人），文章代表其个人观点与使用偏好。*

*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.*

参考来源

• Using Claude Code: The Unreasonable Effectiveness of HTML（原文）
• 示例 HTML 文件库
• Thariq Shihipar X（Twitter）原帖
• Simon Willison 解读与摘要