Claude Code 团队成员为何以及如何使用 HTML 替代 Markdown，以生成更丰富、更易读且便于分享的输出内容。
- 分类Claude Code
- 产品Claude Code
- 日期2026 年 5 月 20 日
- 阅读时间5分钟
- https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html
Markdown 已成为智能体与人类沟通时使用的主流文件格式。它简单、可移植，具备一定的富文本能力，且易于编辑。Claude 甚至已经相当擅长在 Markdown 文件中使用 ASCII 字符绘制图表。
但随着智能体变得越来越强大，我发现 Markdown 逐渐成为一种限制越来越多的格式。具体来说，我觉得阅读超过一百行的 Markdown 文件很困难；我希望用 Claude 生成更丰富的可视化效果、色彩和图表；我还希望能够更轻松地分享这些输出内容。
此外，我现在越来越少亲自编辑这些文件，而是将它们作为规范和参考文件来使用。当我确实需要编辑时，通常也是让 Claude 来代劳，这反而消除了 Markdown 的一大优势。
因此，我开始倾向于使用 HTML 而非 Markdown 作为输出格式，并且越来越多地看到 Claude Code 团队的其他成员也在采用这种方式。在这篇文章中，我将分享我们团队为何以及如何使用 HTML 来生成更丰富、更易读的 Claude Code 输出。如果你想跟着实践，也可以开始将这些 HTML 文件模板用于常见的用例。
为什么使用 HTML？
有几个原因使得 HTML 比 Markdown 更适合我现在用 Claude Code 所做的工作，包括那些需要或涉及以下方面的任务：
信息密度
与 Markdown 相比，HTML 可以传达更丰富的信息。当然，它能实现标题和格式等简单的文档结构，但它还能表示各种其他信息，例如：
- 使用表格呈现的表格数据
- 使用 CSS 呈现的设计数据
- 使用 SVG 呈现的插图
- 使用 script 标签呈现的代码片段
- 使用 HTML 元素结合 JavaScript 和 CSS 实现的交互
- 使用 SVG 和 HTML 呈现的工作流程
- 使用绝对定位和画布呈现的空间数据
- 使用图片标签呈现的图像
在我看来，几乎没有任何 Claude 能读取的信息，是你无法用 HTML 高效呈现的。这使得 HTML 成为模型向你传达深度信息、以及你对其进行审阅的一种极为高效的方式。
我发现，如果无法做到这一点，模型可能会在 Markdown 中采用更低效的方式，比如 ASCII 图表，或者我最喜欢的——用 Unicode 字符来估算颜色。
视觉清晰度与阅读便捷性
随着 Claude 能够处理更复杂的工作，它也能编写越来越庞大的规格说明和计划。我发现，我实际上很少会去阅读超过 100 行的 Markdown 文件，而且我肯定无法让组织里的其他人去阅读它。
但 HTML 文档更容易阅读，因为 Claude 可以在视觉上组织结构，使其非常适合通过标签页、插图和链接进行导航。它甚至可以做到移动端响应式，让你根据不同的设备形态以不同方式阅读。
易于分享
Markdown 文件相当难以分享，因为大多数浏览器无法很好地原生渲染它们。你通常需要将它们作为附件添加到电子邮件或消息中。
只要你上传了 HTML 文件，就可以轻松分享链接。你的同事可以在任何地方打开它，并轻松地引用。
如果使用 HTML 格式，有人实际阅读你的规格说明、报告或 PR 描述的可能性会高得多。
双向交互
HTML 还可以让你与文档进行交互；例如，你可能希望它添加滑块或旋钮来调整设计，或者允许你调整算法中的不同选项以观察效果。你还可以让它允许你将这些更改复制到提示词中，再粘贴回 Claude Code。
在有用的情况下，这可以让你为你正在处理的特定问题创建独立的编辑环境。
数据导入
使用 Claude Code 而非 Claude.ai 或 Claude Design 制作 HTML 文件的最大原因之一，在于 Claude Code 能够摄入大量上下文。例如，在撰写本文时，我让 Claude Code 读取我的代码文件夹，找出我生成的所有 HTML 文件，对其进行分组和分类，然后制作一个包含各类别示意图的 HTML 文件。你在本文中看到的图表正是由此直接生成的。
除了文件系统，Claude Code 还可以通过你的 MCP（如 Slack、Linear 等）、你的网页浏览器（配合 Chrome 中的 Claude）以及你的 git 历史记录来查找额外的上下文。
快速上手
有一点值得注意：要让 Claude 生成这样的 HTML，你不需要做太多准备工作。你只需直接提示它“制作一个 HTML 文件”或“制作一个 HTML 制品”。关键在于你要清楚这个制品需要实现什么功能，以及你将如何使用它。随着时间的推移，针对重复出现的模式构建一个技能可能是有意义的，但一开始从零开始提示是了解它在不同用例下如何工作的好方法。
使用场景
为了让这种方法更具体，下面列举了一些我认为使用 HTML 文件比 Markdown 更合适的示例场景。你也可以在 GitHub 上查看这些用例的图库，链接在此。
规格说明、规划与探索
HTML 是 Claude 深入探究问题的丰富画布。当我开始处理一个问题时，我期望制作一个 HTML 文件网络，而不是一个简单的 Markdown 计划。例如，我可能会先让 Claude Code 进行头脑风暴，创建一些探索不同选项的内容。然后我会要求它更深入地展开其中一个方向，也许制作一些界面类型的模型或示例。最后，当我感觉良好时，我会让它编写一个实施计划。当我对计划满意后，我会创建一个新的会话，并将所有这些文件传递给它来实施。
在验证时，我也会让验证代理读取这些文件，这样它就能对所需内容有更广泛的了解。
示例提示词：
- 我不太确定引导页该往哪个方向设计。请生成六种截然不同的方案——在布局、风格和信息密度上有所变化——并将它们以网格形式放在一个 HTML 文件中，方便我并排对比。为每个方案标注其权衡取舍。
- 请在一个 HTML 文件中创建一份详尽的实施计划，务必包含一些模拟图，展示数据流，并添加我可能需要审阅的重要代码片段。要使其易于阅读和理解。
用于以下场景：
- 探索代码实现的其他方式
- 同时尝试多种视觉设计方案
代码审查与理解
代码在 Markdown 文件中可能难以阅读，但借助 HTML，我们可以渲染差异对比、注释、流程图和模块。使用 HTML 来理解智能体编写的代码、审查代码，或向审查你代码的人解释一个 PR。
示例提示词：
请帮我审查这个 PR，创建一个描述它的 HTML 制品。我对流式/背压逻辑不太熟悉，所以请重点讲解这部分。渲染实际的差异对比，并在页边距添加内联注释，按严重程度对发现的问题进行颜色编码，以及任何有助于清晰传达概念的内容。
用于以下场景：
- 创建 PR
- 审查 PR
- 理解代码中的某个主题
设计与原型
Claude Design 基于 HTML，因为即使你的最终界面不是 HTML，HTML 在设计方面也具有极强的表现力。Claude 可以用 HTML 勾勒出设计草图，然后用你选择的语言（如 React、Swift 等）来实现。
你还可以制作交互原型，例如动画、动作等。可以考虑让 Claude 制作滑块、旋钮等控件，来精确调整你想要的参数。
示例提示词：
我想制作一个新的结账按钮原型，点击时它会播放一个动画，然后快速变为紫色。创建一个 HTML 文件，包含多个滑块和选项，让我可以尝试这个动画的不同效果，并提供一个复制按钮，用来复制效果最佳的参数。
用于以下场景：
- 创建设计系统制品
- 调整组件
- 可视化组件库
- 制作动画原型
报告、研究与学习
Claude Code 在跨多个数据源综合信息并将其转化为可读报告方面非常高效。你可以提示 Claude 搜索你的 Slack、代码库、Git 历史记录或互联网，并利用这些信息生成易于阅读的报告。
你可以将其整理成一份长 HTML 文档、一个交互式讲解页面，甚至是一个幻灯片/演示文稿。让 Claude 使用 SVG 制作图表来帮助可视化。
示例提示词：
我不理解我们的速率限制器实际是如何工作的。请阅读相关代码并生成一个单页 HTML 讲解页面：包含令牌桶流程的图表、3-4 段带注释的关键代码片段，以及底部的一个"注意事项"部分。优化为适合一次性阅读。
适用于：
- 编写功能总结
- 生成讲解页面
- 起草周报
- 创建事故报告
- 制作 SVG 插图、流程图和技术图表
自定义编辑界面
有时很难仅通过文本框来描述你想要的东西。针对这种情况，我经常让 Claude 为我正在处理的具体任务构建一个一次性的编辑器：不是产品，也不是可复用的工具，而是一个专为这一份数据量身定制的单页 HTML 文件。
诀窍始终是加上一个导出功能：一个"复制为 JSON"或"复制为提示词"按钮，将我在 UI 中所做的操作转换回可以粘贴到 Claude Code 或提交到文件中的内容。你始终保持在循环中，但循环变得更加紧凑。
示例提示词：
- 我需要重新排列这 30 个 Linear 工单的优先级。请为我制作一个 HTML 文件，将每个工单作为可拖拽卡片，分布在"现在/下一步/稍后/放弃"列中。按你的最佳判断预先排序。添加一个"复制为 Markdown"按钮，导出最终排序结果，并为每个分组附上一行理由说明。
- 这是我们的功能开关配置。请为其构建一个基于表单的编辑器，按区域对开关进行分组，显示它们之间的依赖关系，如果我启用了一个其前置条件处于关闭状态的开关，请发出警告。添加一个"复制差异"按钮，只输出发生变化的键。
- 我正在调试这个系统提示词。做一个并排编辑器：左侧是可编辑的提示词，变量插槽高亮显示；右侧是三个示例输入，实时渲染填充后的模板。添加一个字符/模型 token 计数器和一个复制按钮。
用于以下场景：
- 对任何内容进行重新排序、分类或分桶（工单、测试用例、反馈）
- 编辑结构化配置（功能开关、环境变量、带约束的 JSON/YAML）
- 调试提示词、模板或文案，并实时预览
- 整理数据集——批准/拒绝数据行、标记示例、导出所选内容
- 对文档、转录文本或差异对比进行标注，并导出标注结果
- 选取那些难以用文字表达的值：颜色、缓动曲线、裁剪区域、cron 调度表达式、正则表达式
常见问题
以下是我在使用 HTML 与 Claude Code 配合时最常被问到的问题，以及我在日常实践中总结出的实用习惯：
这样效率不是更低吗？
虽然 Markdown 通常使用的模型 token 更少，但我发现 HTML 更强的表现力，加上我阅读它的可能性高得多，意味着我最终能得到更好的输出。在 Opus 4.7 的 100 万上下文窗口下，增加的 token 用量在上下文窗口中几乎察觉不到。
那你现在什么时候还用 Markdown？
老实说，我现在几乎完全不再用 Markdown 了，不过我可能属于 HTML 最大化使用的那一类人。
这就是你替代规划的方式吗？
我发现，与其制定一个单一的规划，我更倾向于为规划的不同部分/阶段准备几个不同的 HTML 文件。例如，我可能会用 HTML 做一个实现计划，然后另建一个文件用于探索用户界面，最后再做一个 HTML 组件来列出所有设计方案。我通常会保留这些文件，作为将来参考以及验证时使用。
与 Claude 保持同步
以上所有内容都是为了说明，我使用 HTML 而非 Markdown 的真正原因，在于它能让我感觉与 Claude 的联系更加紧密。随着 Claude 承担的任务越来越多，我注意到自己阅读计划时不如以前仔细了，而我想要一种方式，能够持续参与它的决策过程，而不是简单地把任务交出去。HTML 恰好满足了这一需求。现在，我感觉自己比以往任何时候都更融入其中。
开始使用 Claude Code。
本文由技术团队成员 Thariq Shihipar 撰写，表达了他个人对在 Claude Code 中使用 HTML 文件的看法与偏好。
借助 Claude 改变您组织的运作方式。
How and why members of the Claude Code team use HTML instead of Markdown to produce richer, more readable, and easily shareable outputs.
- Category
- ProductClaude Code
- DateMay 20, 2026
- Reading time5min
- https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html
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.
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.
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.
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. If you'd like to follow along, you can start using these HTML file templates for common use cases, too.
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, including tasks that require or entail:
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:
- 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
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.
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.
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.
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.
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.
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.
The chance of someone actually reading your spec, report, or PR writeup is much higher if it’s in 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.
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.
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.
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.
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.
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.
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.
- 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.
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.
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.
Use this for:
- Creating a PR
- Reviewing a PR
- Understanding a topic in code
Design and prototypes
Claude Design is based on HTML because HTMLis 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.
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 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.
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..
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.
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.
Use this for:
- Writing feature summarizations
- Generating explainers
- Drafting weekly status reports
- Creating incident reports
- Producing SVG illustrations, flowcharts, and technical diagrams,
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.
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.
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.
- 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)
- 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
- Picking values that are painful to express in text: colors, easing curves, crop regions, cron schedules, regexes
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:
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.
When do you use Markdown for now?
I have honestly stopped using Markdown altogether for almost everything, but I’m probably far on the HTML maximalist side of things.
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.
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."
Get started with 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.