让 Claude Code 用 HTML 而不是 Markdown 输出：为什么，以及五种用法

这是“Claude Code 开发系列”的第三篇。

这一篇解决的问题是：Claude 写给你看的东西越来越长，计划、方案、评审意见动辄几百行，你其实没在认真读。怎么办？ 原文作者 Thariq Shihipar 的做法是：让 Claude Code 输出 HTML 文件，而不是 Markdown。他说团队里越来越多的人也在这么做。

这是全系列里最容易上手的一篇：不需要任何设置，在提示词里说一句“做成一个 HTML 文件”就行。

要先说明：这篇是作者的个人做法和偏好，他自己在文末也承认是“HTML 的重度拥护者”。

Markdown 哪里不够用了

Markdown 简单、通用、好编辑，所以成了智能体和人沟通的主要格式。作者遇到的问题有三个：

长了就读不下去。 他说自己基本不会读超过一百行的 Markdown 文件，更别想让同事读。
表达不了更丰富的东西。 颜色、图表、示意图。没有别的办法时，模型只能在 Markdown 里凑合，比如用字符画图。
不好分享。 多数浏览器不能直接好好显示 Markdown，往往得作为附件发给别人。

还有一个变化：他已经很少亲手改这些文件了，要改也是让 Claude 改。Markdown“好编辑”这个最大的优点，也就没那么重要了。

HTML 好在哪

信息密度高。 除了标题和格式，HTML 还能放表格、用 CSS 表达设计、用 SVG 画插图和流程、放代码片段、做可以交互的控件。作者的说法是：Claude 能读到的信息，几乎没有哪一类是 HTML 不能高效表达的。

好读。 Claude 可以把内容组织成适合浏览的样子：标签页、插图、链接，还能适配手机屏幕。

好分享。 把 HTML 文件传上去，发一个链接就行。作者认为，别人真的去读你的方案、报告或 PR 说明的可能性会高很多。

可以双向交互。 可以让它加上滑块、旋钮来调一个设计，或者切换算法里的不同选项看效果。还可以加一个按钮，把你调好的结果复制出来，贴回 Claude Code。

Claude Code 能读到的上下文多。 这是用 Claude Code 而不是别的工具来做 HTML 的最大理由：它能读你的文件，能通过 MCP 读 Slack、Linear 这类工具，能看你的 git 历史。作者写那篇文章时，就是让 Claude Code 把他代码目录里生成过的所有 HTML 文件找出来、分类，再做成带示意图的页面。

怎么开始

不需要做什么准备。在提示词里说“做成一个 HTML 文件”就可以。

关键是想清楚你要这个文件干什么、打算怎么用它。反复用到的模式，以后可以做成一个 skill；但先从零开始提几次，对各种用法有了感觉再说。

五类用法

下面的提示词译自原文的例子，按自己的情况改。

1. 方案、计划和探索

作者现在开始做一件事时，不是写一份 Markdown 计划，而是做出一组 HTML 文件：先让 Claude 发散，做出几种方案的对比；再挑一个展开，做出界面示意；满意了再让它写实现计划。之后新开一个会话，把这些文件都交给它去实现。验证时也让负责验证的代理读这些文件。

我不确定新手引导页该往哪个方向做。生成 6 种明显不同的方案，在布局、语气和信息密度上拉开差别，
放在一个 HTML 文件里排成网格，让我能并排比较。每一种标明它做了什么取舍。

写一份详细的实现计划，做成 HTML 文件。要有界面示意、数据怎么流动，
以及我可能想检查的关键代码片段。要好读、好消化。

2. 代码评审和理解代码

代码放在 Markdown 里不好读。HTML 可以把改动、批注、流程图和模块关系都画出来。

帮我评审这个 PR：做一个 HTML 页面来讲解它。我对流式处理和背压那部分逻辑不熟，重点讲那里。
把实际的改动显示出来，在旁边加批注，按严重程度给发现的问题标上颜色，
其他有助于讲清楚的东西也加上。

适合：提 PR 时写说明、评审别人的 PR、弄懂代码里的某个主题。

3. 设计和原型

即使最终的界面不是网页，HTML 也很适合用来表达设计。Claude 可以先用 HTML 画出来，再用你的技术栈（React、Swift 等）去实现。动画和交互也可以先在这里试。

我想做一个新的结账按钮的原型：点击后播放一段动画，然后迅速变成紫色。
做一个 HTML 文件，带几个滑块和选项让我试这段动画的不同参数，
再给我一个复制按钮，把效果好的那组参数复制出来。

4. 报告、调研和学习

Claude Code 很擅长把多个来源的信息综合成一份好读的报告：你的 Slack、代码库、git 历史、网上的资料。可以做成一篇长文、一个可以交互的讲解页，或者一套幻灯片。示意图让它用 SVG 画。

我没弄懂我们的限流器到底是怎么工作的。读相关的代码，做一个 HTML 讲解页：
一张令牌桶流程的示意图，三四段关键代码加上批注，最后一节讲容易踩的坑。
按“读者只读一遍”来优化。

适合：功能总结、周报、事故报告、流程图和技术示意图。

5. 一次性的编辑界面

有些东西光靠一个文本框说不清。这时可以让 Claude 做一个用完就扔的编辑器：不是产品，不是可复用的工具，就是为眼前这份数据专门做的一个 HTML 文件。

诀窍是结尾一定要有“导出”：一个“复制为 JSON”或“复制为提示词”的按钮，把你在界面上做的操作变回能贴进 Claude Code 或提交到文件里的东西。

我要重新给这 30 张工单排优先级。做一个 HTML 文件，每张工单是一张可以拖动的卡片，
分“现在做 / 接下来 / 以后 / 不做”四列。先按你的判断排好。
加一个“复制为 Markdown”的按钮，导出最后的排序，每一列附一句理由。

这是我们的功能开关配置。给它做一个表单式的编辑器：按模块分组，显示开关之间的依赖，
我打开一个前置条件没满足的开关时要提醒我。
加一个“复制改动”的按钮，只给我改过的那些项。

适合的场景还有：整理和分类测试用例或用户反馈、调提示词并实时预览、筛选数据集、给文档或对话记录做标注，以及挑选那些用文字很难说清的值，比如颜色、缓动曲线、裁剪区域、定时表达式和正则。

常被问到的三个问题

这样不是更费 token 吗？ Markdown 确实常常更省。作者的看法是：HTML 表达力更强，他真的会去读，所以总体上得到的结果更好；在 100 万 token 的上下文窗口里，多出来的这点用量不明显。

那什么时候还用 Markdown？ 作者说他几乎所有东西都不用 Markdown 了，但也承认自己在这件事上比较极端。

这是用来取代“计划”的吗？ 不是一份计划换成一个 HTML 文件，而是按计划的不同部分和阶段做几个文件：一份实现计划，一份界面方案的探索，一份列出所有设计的页面。这些文件留着，以后当参考，验证时也用得上。

真正的理由

作者最后说，他用 HTML 的根本原因是：这样他更能跟上 Claude 在做什么。 Claude 承担的事越来越多，他发现自己读计划读得越来越不仔细；他想要的是对 Claude 做的选择保持参与，而不是一交了之。

这一点对谁都适用：格式本身不重要，重要的是你会不会真的去看。如果一份几百行的 Markdown 你不会读，那它写得再好也没有用。