Thariq: Using Claude Code: The Unreasonable Effectiveness of HTML
Markdown 已成为智能体（agent）与我们沟通时占主导地位的文件格式。它简单、可移植，具备一定的富文本能力，且易于编辑。Claude 甚至已经相当擅长在 Markdown 文件中使用 ASCII 绘制图表。
但随着智能体变得越来越强大，我感到 Markdown 已成为一种受限的格式。我发现自己很难阅读超过一百行的 Markdown 文件。我想要更丰富的可视化效果、色彩和图表，并且希望能轻松分享它们。
我也越来越不亲自编辑这些文件，而是将它们用作规格说明、参考文件、头脑风暴输出等。当我确实需要编辑时，我通常会让 Claude 来编辑，这就削弱了 Markdown 最大的一个优势。
我开始更偏爱 HTML 作为输出格式，而不是 Markdown，并且越来越多地看到 Claude Code 团队中的其他人也在使用它。以下就是原因。
（如果你想先看一些示例，可以在这里看到一大堆：https://thariqs.github.io/html-effectiveness ，不过记得回来看更多关于”为什么”的内容。）
为什么选择 HTML？
信息密度
与 Markdown 相比，HTML 能够传达更丰富得多的信息。它当然可以做简单的文档结构，如标题和格式，但它还能表示各种其他信息，例如：
- 使用表格表示表格数据
- 使用 CSS 表示设计数据
- 使用 SVG 表示插图
- 使用 script 标签表示代码片段
- 使用 HTML 元素配合 JavaScript + CSS 实现交互
- 使用 SVG 和 HTML 表示工作流
- 使用绝对定位和画布表示空间数据
- 使用 image 标签表示图片
我甚至可以说，几乎没有 Claude 能读取的信息集是你无法用 HTML 高效表示的。这使它成为模型向你传达深度信息、以及你进行审阅的高效方式。
我发现，在无法实现这一点的情况下，模型可能会在 Markdown 中做一些效率更低的事情，比如 ASCII 图表，或者我最喜欢的——用 Unicode 字符来估算颜色，就像这张来自 Claude Code 的截图所示。
Claude Code 尝试在 Markdown 中显示颜色
视觉清晰度与易读性
随着 Claude 能够完成更复杂的工作，它也在编写越来越大的规格说明和计划。实际上，我发现自己往往不会真正去阅读超过 100 行的 Markdown 文件，而且我肯定也无法让组织中的其他人去阅读它。
但 HTML 文档要容易阅读得多。Claude 可以组织视觉结构，使其非常适合通过标签页、插图、链接等方式导航。它甚至可以是移动响应式的，让你可以根据设备尺寸以不同方式阅读。
易于分享
Markdown 文件相当难以分享，因为大多数浏览器不能很好地原生渲染它们。你通常需要将它们作为附件添加到邮件或消息中。
使用 HTML，只要你上传文件（例如到 S3），你就可以轻松分享链接。你的同事可以在任何他们想打开的地方打开它，并轻松引用。
如果你的规格说明、报告或 PR 文档是 HTML 格式的，别人真正阅读它的可能性要高得多。
双向交互
HTML 可以让你与文档交互。例如，你可能希望让它添加滑块或旋钮来调整设计，或者允许你调整算法中的不同选项来看看会发生什么。你也可以让它允许你复制这些更改，粘贴到提示词中再发回给 Claude Code。
阅读我关于”游乐场”（playgrounds）的帖子，了解更多这种双向交互的示例：https://x.com/trq212/status/2017024445244924382
数据摄取
为什么要用 Claude Code 来制作 HTML 文件，而不是 Claude AI 或 Claude Design 呢？最大的原因之一是 Claude Code 能够摄取的所有上下文。
例如，在写这篇文章时，我让 Claude Code 浏览我的代码文件夹，找出我生成的所有 HTML 文件，对它们进行分组和分类，然后制作一个 HTML 文件，用图表来表示每种类型。你在本文中看到的图表就是这一过程的直接结果。
除了文件系统，Claude Code 还可以利用你的 MCP（如 Slack、Linear 等）、你的网页浏览器（通过 Chrome 中的 Claude）、你的 git 历史等找到额外的上下文。
它令人愉悦
用 Claude 制作 HTML 文档更有趣，让我感觉更投入、更有参与感，而这本身就足够了。
如何开始
我有点担心人们读完这篇文章后会把它变成一个 /html 技能之类的。虽然这可能有一定价值，但我想强调的是，你不需要做太多就能让 Claude 做到这一点。你可以直接要求它”制作一个 HTML 文件”或”制作一个 HTML 产物”（artifact）。
诀窍在于知道你想让这个产物做什么，以及你可能如何使用它。随着时间的推移，你可能会制作一个技能，但目前我建议从零开始提示，以便掌握如何在不同情况下使用它。
使用场景
为了让这更具体，我为不同的使用场景制作了许多不同的 HTML 文件。你可以在这里查看所有内容：https://thariqs.github.io/html-effectiveness/ ，但这里是一个概览。
规格说明、规划与探索
HTML 是 Claude 深入问题的丰富画布。当我开始处理一个问题时，我期望的不是一个简单的 Markdown 计划，而是一系列相互关联的 HTML 文件。例如，我可能会先让 Claude Code 进行头脑风暴，创建不同选项的探索。然后我会让它深入扩展其中一个，也许制作模型或代码片段。最后，当我感觉良好时，我会让它写一个实施计划。当我对计划满意时，我会创建一个新的会话，把所有这些文件传给它来实施。
在验证时，我也会让验证智能体阅读这些文件，它将拥有更广泛的所需上下文。
示例提示词：
-
我不确定该把引导页做成什么方向。生成 6 种截然不同的方案——在布局、语调和密度上有所变化——并将它们并排排列在一个 HTML 文件的网格中，以便我可以比较。为每个方案标注它所做出的权衡。
-
创建一个详尽的实施计划，保存为 HTML 文件，务必制作一些模型图，展示数据流，并添加我可能想审阅的重要代码片段。让它易于阅读和消化。
使用场景：
- 探索代码中实现某功能的其他方式
- 探索多种视觉设计
代码审查与理解
代码在 Markdown 文件中可能难以阅读。但使用 HTML，我们可以渲染 diff、注释、流程图、模块图等。用这种方式来理解智能体编写的代码、获取代码审查，或向审查你代码的人解释一个 PR。我发现这通常比默认的 GitHub diff 视图效果更好，我现在每个 PR 都会附上一个 HTML 代码解释器。
示例提示词：
帮我审查这个 PR，创建一个 HTML 产物来描述它。我对流式处理/背压逻辑不太熟悉，所以请重点关注这部分。渲染实际的 diff，并添加行内边距注释，按严重程度对发现的问题进行颜色编码，以及任何其他有助于清晰传达概念的内容。
使用场景：
- 创建 PR
- 审查 PR
- 理解代码中的某个主题
设计与原型
Claude Design 基于 HTML，因为 HTML 在设计方面极具表现力，即使你的最终界面不是 HTML。Claude 可以用 HTML 勾勒出设计，然后用你选择的语言编写，无论是 React、Swift 等。
你也可以原型化交互，如动画、动作等。考虑让 Claude 制作滑块、旋钮等，以便精确调整你想要的效果。
示例提示词：
我想原型化一个新的结账按钮，点击时播放动画，然后快速变成紫色。创建一个 HTML 文件，包含几个滑块和选项，让我可以尝试这个动画的不同参数，给我一个复制按钮，复制效果好的参数。
用于：
- 创建设计系统产物
- 调整组件
- 可视化组件库
- 原型化令人愉悦的动画
报告、研究与学习
Claude Code 非常擅长综合多个数据源的信息，并将其转换为易于阅读的报告。你可以提示 Claude 搜索你的 Slack、代码库、git 历史、互联网等，并用它为你自己、领导层、你的团队等生成极具可读性的报告。
你可以把它组装成一份长 HTML 文档、一个交互式解释器，甚至一个幻灯片/演示文稿。让 Claude 使用 SVG 图表来帮助可视化。
例如，在我的关于提示词缓存的帖子中，我让 Claude 在阅读 git 历史后，准备了一份关于我们所有提示词缓存更改的深度研究文件，保存为 HTML。
示例提示词：
我不明白我们的速率限制器实际上是如何工作的。阅读相关代码，生成一个单独的 HTML 解释页面：令牌桶流程的图表、3-4 个带注释的关键代码片段，以及底部的”陷阱”部分。为只读一次的人优化。
用于：
- 总结某个功能的工作原理
- 向我解释一个概念
- 每周向你的老板汇报状态
- 向你的领导层提交事故报告
- SVG 插图、流程图、技术图表等
自定义编辑界面
有时很难在文本框中纯粹用文字描述你想要什么。在这种情况下，我会让 Claude 为我构建一个一次性的编辑器，专门用于我正在处理的特定事物。不是一个产品，也不是一个可复用的工具，而是一个单独的 HTML 文件，为这一份数据量身定制。
诀窍在于始终以导出结束：一个”复制为 JSON”或”复制为提示词”按钮，将我在 UI 中所做的任何操作转换回可以粘贴到 Claude Code 中的内容。
示例提示词：
-
我需要重新确定这 30 个 Linear 工单的优先级。给我做一个 HTML 文件，每个工单是一张可拖动的卡片，横跨”现在”/“下一步”/“稍后”/“砍掉”几列。按你的最佳猜测预先排序。添加一个”复制为 Markdown”按钮，导出最终的排序，每个桶附带一行理由。
-
这是我们的功能开关配置。为它构建一个基于表单的编辑器，按区域分组开关，显示它们之间的依赖关系，如果我启用了一个前置条件未开启的开关就警告我。添加一个”复制 diff”按钮，只给我变更的键。
-
我正在调整这个系统提示词。制作一个并排编辑器：左侧是可编辑的提示词，变量槽位高亮显示，右侧是三个示例输入，实时重新渲染填充后的模板。添加字符/令牌计数器和一个复制按钮。
用于：
- 重新排序、分类或分桶任何内容（工单、测试用例、反馈）
- 编辑结构化配置（功能开关、环境变量、带约束的 JSON/YAML）
- 调整提示词、模板或文案，并实时预览
- 策划数据集、批准/拒绝行、标记示例、导出选择
- 注释文档、转录文本或 diff，并导出注释
- 选择在文本中难以表达的值：颜色、缓动曲线、裁剪区域、cron 表达式、正则表达式
常见问题
我已经向很多人讲述了我如何转向 HTML，看到了一些重复的问题。
这不是更消耗令牌吗？
虽然 Markdown 通常使用更少的令牌，但我发现 HTML 增加的表达力，以及我更可能阅读它的事实，意味着我获得了整体上更好的输出。在 Opus 4.7 的 1M 上下文窗口下，增加的令牌使用量实际上在上下文窗口中并不明显。
现在你还在什么时候使用 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 时，我感觉比以往任何时候都更加参与其中。我希望你也有同样的感受。