本文翻译自 Thariq 在 X 上发布的文章：Using Claude Code: The Unreasonable Effectiveness of HTML。本文完全由有道龙虾翻译和发布。
Markdown 已经成为智能体与我们沟通时最主流的文件格式。它简单、可移植，有一定的富文本能力，也很容易让你编辑。Claude 甚至已经非常擅长在 Markdown 文件里用 ASCII 画图。
但随着智能体变得越来越强，我开始觉得 Markdown 变成了一种限制性格式。超过一百行的 Markdown 文件对我来说就很难读。我想要更丰富的可视化、颜色和图表，而且希望它们能轻松分享。
我也越来越少亲自编辑这些文件，而是把它们当作规格说明、参考文件、头脑风暴结果等来使用。即便我确实要修改，通常也是让 Claude 去改，这就削弱了 Markdown 最大的优势之一。
我已经开始更偏好用 HTML 作为输出格式，而不是 Markdown。我也越来越常看到 Claude Code 团队的其他人这么做。下面是原因。
如果你想先看一些例子，可以看这里：html-effectiveness，但记得回来继续读为什么。
为什么是 HTML？
信息密度
相比 Markdown，HTML 能传达丰富得多的信息。它当然可以表达简单的文档结构，比如标题和格式，但它还可以表示各种其它信息，例如：
- 用表格表示表格数据
- 用 CSS 表示设计数据
- 用 SVG 表示插图
- 用 script 标签表示代码片段
- 用 HTML 元素、JavaScript 和 CSS 表示交互
- 用 SVG 和 HTML 表示工作流
- 用绝对定位和 canvas 表示空间数据
- 用 image 标签表示图片
我甚至会说，几乎没有 Claude 能读懂、但你无法用 HTML 相对高效表达的信息集合。这让 HTML 成为模型向你传达深度信息、并让你审阅这些信息的一种非常高效的方式。
我发现，如果不能这么做，模型可能会在 Markdown 里做一些低效的事，比如 ASCII 图，或者我最喜欢的，用 Unicode 字符估算颜色，就像 Claude Code 的截图里那样。
视觉清晰度与易读性
随着 Claude 能做越来越复杂的工作，它也会写越来越大的规格说明和计划。实际使用中，我发现自己通常不会认真读超过 100 行的 Markdown 文件，更别说让组织里的其他人去读了。
但 HTML 文档读起来容易得多。Claude 可以用最适合浏览的方式，在视觉上组织结构，比如标签页、插图、链接等。它甚至可以做成移动端响应式，这样你能根据不同设备用不同方式阅读。
易于分享
Markdown 文件其实很难分享，因为大多数浏览器并不能很好地原生渲染它们。你通常不得不把它们作为邮件或消息附件发送。
而 HTML 只要上传文件，比如上传到 S3，就可以很容易地分享链接。同事可以在任何地方打开并引用它。
如果你的规格说明、报告或 PR 说明是 HTML，别人真正去读的概率会高得多。
双向交互
HTML 可以让你与文档交互。比如，你可能想让它添加滑块或旋钮，用来调整设计，或者让你微调算法中的不同选项并观察会发生什么。你也可以让它提供一个按钮，把这些改动复制成 prompt，再粘回 Claude Code。
可以阅读我关于 playgrounds 的文章，看看这种双向交互的例子：https://x.com/trq212/status/2017024445244924382
数据摄取
为什么要用 Claude Code 来生成 HTML 文件，而不是 ClaudeAI 或 Claude Design？其中一个最大原因是 Claude Code 可以摄取大量上下文。
比如，在写这篇文章时，我让 Claude Code 阅读我的代码文件夹，找出所有我生成过的 HTML 文件，对它们分组和分类，然后生成一个 HTML 文件，用图表表示每一种类型。你在这篇文章中看到的图表就是直接由这个过程产生的。
除了文件系统，Claude Code 还可以通过 MCP 获取更多上下文，比如 Slack、Linear 等；也可以通过你的浏览器、git 历史等获取上下文。
它让人开心
用 Claude 制作 HTML 文档更有趣，也让我感觉自己更参与、更投入到创作过程中。仅凭这一点就足够了。
如何开始
我有点担心人们读完这篇文章后，会把它做成一个 /html skill 或类似东西。虽然那可能有些价值，但我想强调，你其实不需要做太多。你只要让它“做一个 HTML 文件”或“做一个 HTML artifact”就可以了。
关键在于，你要知道你希望这个 artifact 做什么，以及你会如何使用它。随着时间推移，你也许会做一个 skill，但现在我建议先从零开始提示，熟悉它在不同场景里的用法。
使用场景
为了更具体，我做过很多不同用途的 HTML 文件。你可以在这里查看全部：html-effectiveness。下面是概览。
规格说明、计划与探索
HTML 是 Claude 深入问题的一张丰富画布。当我开始处理一个问题时，我期待的不是一个简单的 Markdown 计划，而是一组 HTML 文件。
比如，我可能先让 Claude Code 头脑风暴，并创建几个不同选项的探索稿。然后我会让它进一步展开其中一个，也许做一些 mockup 或代码片段。最后，当我觉得方向不错时，我会让它写一份实现计划。当我对计划满意后，我会创建一个新会话，并把所有这些文件传进去让它实现。
验证时，我也会让验证智能体读取这些文件，这样它会对需求有更广泛的上下文。
示例 prompt：
我不确定 onboarding screen 应该走什么方向。生成 6 种明显不同的方法，改变布局、语气和信息密度，并把它们放在一个 HTML 文件的网格里，这样我可以并排比较。给每一种标注它做出的权衡。
创建一个完整的 HTML 实现计划，务必包含一些 mockup，展示数据流，并加入我可能需要审阅的重要代码片段。让它易读、易消化。
可用于：
- 探索代码中实现某件事的其它方式
- 探索多种视觉设计
代码审查与理解
代码在 Markdown 文件里可能很难读。但用 HTML，我们可以渲染 diff、注释、流程图、模块等。你可以用它来理解智能体写出的代码，做代码审查，或者向审 PR 的人解释一个 PR。
我发现这通常比默认的 GitHub diff 视图效果更好。我现在每个 PR 都会附上一个 HTML code explainer。
示例 prompt：
帮我审查这个 PR，创建一个 HTML artifact 来描述它。我对 streaming/backpressure 逻辑不太熟，所以重点关注那里。渲染实际 diff，并加上行内边注，按严重程度给发现的问题着色，并加入任何有助于表达概念的内容。
可用于：
- 创建 PR
- 审查 PR
- 理解代码中的某个主题
设计与原型
Claude Design 基于 HTML，因为 HTML 在设计表达上极其强大，即使你的最终界面并不是 HTML。Claude 可以先用 HTML 草拟一个设计，然后再用你选择的语言实现，比如 React、Swift 等。
你也可以原型化交互，比如动画、动作等。可以考虑让 Claude 制作滑块、旋钮等，让你精细调节出想要的效果。
示例 prompt：
我想原型化一个新的 checkout 按钮，点击时它会播放动画，然后快速变成紫色。创建一个 HTML 文件，里面有几个滑块和选项，让我尝试这个动画的不同方案，并给我一个复制按钮，用来复制效果不错的参数。
可用于：
- 创建设计系统 artifact
- 调整组件
- 可视化组件库
- 原型化有趣的动画
报告、研究与学习
Claude Code 非常擅长综合多个数据源的信息，并把它们转换成可读性很高的报告。你可以提示 Claude 搜索你的 Slack、代码库、git 历史、互联网等，并用它为自己、领导或团队生成极易阅读的报告。
你可以把它做成一篇长 HTML 文档、一个交互式解释器，甚至是一套幻灯片或 deck。可以让 Claude 使用 SVG 图表来帮助可视化。
比如，我写 prompt caching 相关文章时，就让 Claude 读取 git 历史后，为我准备了一份深入的 HTML 研究文件，解释我们对 prompt caching 所做的所有修改。
示例 prompt：
我不理解我们的 rate limiter 实际上是怎么工作的。阅读相关代码，生成一个单页 HTML 解释器：包含 token-bucket 流程图、3 到 4 段关键代码片段及注释，并在底部加入“注意事项”部分。为只读一遍的人优化。
可用于：
- 总结某个功能如何工作
- 向我解释一个概念
- 给老板的每周状态报告
- 给领导的事故报告
- SVG 插图、流程图、技术图表等
自定义编辑界面
有时候，很难只靠文本框描述你想要什么。在这种情况下，我会让 Claude 为当前正在处理的具体事情构建一个一次性编辑器。它不是产品，也不是可复用工具，而是一个单独的 HTML 文件，专门为这一份数据服务。
关键总是以导出结束：一个“复制为 JSON”或“复制为 prompt”的按钮，把我在 UI 中所做的操作转换成可以粘回 Claude Code 的内容。
示例 prompt：
我需要重新排列这 30 个 Linear ticket 的优先级。给我做一个 HTML 文件，把每个 ticket 做成可拖拽卡片，放到 Now / Next / Later / Cut 四列中。先按你的最佳判断预排序。加一个“复制为 markdown”按钮，导出最终排序，并为每个分组提供一句理由。
这是我们的 feature flag 配置。为它构建一个表单式编辑器，按区域对 flag 分组，显示它们之间的依赖关系，如果我启用了某个前置条件关闭的 flag，就发出警告。加一个“复制 diff”按钮，只输出变更过的 key。
我正在调这个 system prompt。做一个并排编辑器：左侧是可编辑 prompt，并高亮变量槽；右侧是三个示例输入，可以实时重新渲染填充后的模板。加上字符/token 计数器和复制按钮。
可用于：
- 重新排序、分诊或分类任何东西，比如 ticket、测试用例、反馈
- 编辑结构化配置，比如 feature flag、环境变量、有约束的 JSON/YAML
- 调整 prompt、模板或文案并实时预览
- 筛选数据集、批准/拒绝行、打标签、导出选择
- 标注文档、转录稿或 diff，并导出注释
- 选择那些很难用文本表达的值，比如颜色、缓动曲线、裁剪区域、cron 计划、正则表达式
常见问题
我一直在向很多人介绍我如何转向 HTML，也看到了一些重复的问题。
这不是 token 效率更低吗？
虽然 Markdown 通常使用更少 token，但我发现 HTML 增加的表达能力，以及我更有可能去读它，意味着整体输出效果更好。对于 Opus 4.7 的 1M 上下文窗口来说，增加的 token 使用量在上下文窗口里其实不太明显。
现在你什么时候还用 Markdown？
老实说，我几乎已经不再用 Markdown 做任何事情了，但我可能是 HTML 极端主义者那一边。
我怎么查看 HTML 文件？
我通常直接在本地浏览器里打开它（你可以让 Claude 帮你打开），如果想分享链接，也可以上传到 S3。
这不会比生成 Markdown 更慢吗？
确实会更慢！HTML 可能比 Markdown 慢 2 到 4 倍，但我觉得结果是值得的。
版本控制怎么办？
老实说，这是 HTML 最大的缺点之一。相比 Markdown，HTML diff 很吵，也很难审查。
怎么让 Claude 符合我的审美，或者不要做得很丑？
frontend design plugin 可以帮助 Claude 做出好看的 HTML 文件。但如果要匹配你自己公司的风格，你可以让 Claude 读取你的代码库，创建一个单独的设计系统 HTML 文件。之后你可以把这个设计系统文件作为其它 HTML 文件的参考。
保持参与感
以上所有内容归根结底是：我认为我使用 HTML 的真正原因，是它让我在使用 Claude 时更有参与感。我曾经开始担心，因为我已经不再深入阅读计划，所以我只能放任 Claude 自己做选择。
但我很高兴地说，使用 HTML 后，我反而比以往任何时候都更有参与感。希望你也一样。