使用 Claude Code：HTML 不合常理的高效
Claude Code 团队成员如何以及为什么使用 HTML，而不是 Markdown，来生成更丰富、更易读、也更容易分享的输出。
Markdown 已经成为 Agent 与人类沟通时使用的主流文件格式。它简单、可移植，具备一些富文本能力，也容易编辑。Claude 甚至已经非常擅长在 Markdown 文件里用 ASCII 画图。
但随着 Agent 变得越来越强，我发现 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 表达工作流
• 用绝对定位和 canvas 表达空间数据
• 用 image 标签展示图片
在我看来，只要是 Claude 能读取的信息，几乎都可以用 HTML 高效表达。这让 HTML 成为一种非常高效的方式：模型可以用它向你传达深入信息，你也可以用它来审阅。
我发现，如果不能这样做，模型在 Markdown 里可能会采用一些效率更低的方式，比如 ASCII 图，或者我最喜欢的，用 unicode 字符来估算颜色。
视觉清晰度和阅读便利性
随着 Claude 能处理更复杂的工作，它也能写出越来越长的规格说明和计划。我发现自己其实很少会真的读完超过 100 行的 Markdown 文件，更不用说让组织里的其他人去读了。
但 HTML 文档读起来容易得多，因为 Claude 可以用视觉方式组织结构，让它非常适合通过标签页、插图和链接来导航。它甚至可以做成移动端响应式，这样你可以根据不同设备形态用不同方式阅读。
易于分享
Markdown 文件并不太容易分享，因为大多数浏览器并不能很好地原生渲染它们。你通常不得不把它们作为附件加到邮件或消息里。
只要你上传 HTML 文件，就可以很轻松地分享链接。同事可以在任何他们想打开的地方查看，并方便地引用它。
如果你的规格说明、报告或 PR 说明是 HTML，别人真正阅读它的概率会高很多。
双向交互
HTML 还可以让你与文档交互；例如，你可能想让它添加滑块或旋钮来调整某个设计，或者让你调节算法中的不同选项看看会发生什么。你也可以让它提供一个功能，把这些改动复制成提示词，再粘回 Claude Code。
在有用的时候，这可以让你为正在处理的具体问题创建一个专门的编辑环境。
数据摄取
使用 Claude Code 生成 HTML 文件，而不是使用 Claude.ai 或 Claude Design，一个最大的原因是 Claude Code 能摄取大量上下文。例如，在写这篇文章时，我让 Claude Code 读取我的代码文件夹，找出我生成过的所有 HTML 文件，对它们进行分组和分类，然后生成一个 HTML 文件，用图表表示每种类型。你在本文中看到的图表就是直接由这个过程产生的。
除了文件系统，Claude Code 还可以通过你的 MCP（比如 Slack、Linear 等）、你的网页浏览器（配合 Chrome 中的 Claude），以及你的 git 历史来查找更多上下文。
开始使用
有一点值得注意：你不需要做太多事，就能让 Claude 生成这样的 HTML。你可以直接提示它“制作一个 HTML 文件”或“制作一个 HTML artifact”。关键是你要知道希望这个 artifact 做什么，以及你可能如何使用它。随着时间推移，围绕反复出现的模式构建一个 skill 可能会有意义，但一开始从零写提示词，是了解它在不同使用场景中如何工作的好方法。
使用场景
为了让这种方法更具体，下面是一些我认为使用 HTML 文件比 Markdown 更合适的示例场景。你也可以在这里跟着一个 GitHub 示例库一起查看这些用例。
规格说明、规划和探索
HTML 是一个丰富的画布，可以让 Claude 深入研究问题。当我开始处理一个问题时，我期待生成一组 HTML 文件，而不是一个简单的 Markdown 计划。例如，我可能会先让 Claude Code 进行头脑风暴，并创建几个不同选项的探索版本。然后我会让它进一步扩展其中一个，也许生成一些 mockup 或类型接口示例。最后，当我觉得方向不错时，会让它写一份实现计划。当我对计划满意后，我会创建一个新会话，并把所有这些文件传进去让它实现。
在验证时，我也会让验证 Agent 读取这些文件，这样它就会对需求有更完整的上下文。
示例提示词：
• 我不确定 onboarding screen 应该往哪个方向做。生成 6 种明显不同的方案，改变布局、语气和信息密度，并把它们放到一个 HTML 文件的网格里，这样我可以并排比较。给每个方案标注它所做的取舍。
• 创建一份详细的 HTML 实现计划，务必包含一些 mockup，展示数据流，并加入我可能想审阅的重要代码片段。让它易读、易理解。
适合用于：
• 探索某个代码实现的其他方式
• 一次性实验多个视觉设计
代码审查和理解
代码在 Markdown 文件里可能很难阅读，但使用 HTML 时，我们可以渲染 diff、注释、流程图和模块。可以用 HTML 理解 Agent 写出的代码、审查代码，或向审查你代码的人解释一个 PR。
示例提示词：
帮我通过创建一个 HTML artifact 来审查这个 PR。我对 streaming/backpressure 逻辑不太熟，所以请重点关注这一点。渲染真实 diff，并加入行内边注释，按严重程度给发现的问题上色，再添加任何有助于讲清概念的内容。
• 创建一个 PR
• 审查一个 PR
• 理解代码中的某个主题
设计和原型
Claude Design 基于 HTML，因为 HTML 在设计表达上极其强大，即使你的最终界面并不是 HTML。Claude 可以先用 HTML 草拟一个设计，然后再用你选择的语言来实现，比如 React、Swift 等。
你也可以制作交互原型，例如动画、动作等。可以考虑让 Claude 制作滑块、旋钮等，用来精确调出你想要的效果。
我想为一个新的结账按钮做原型，点击时它会播放一个动画，然后快速变成紫色。创建一个 HTML 文件，里面有几个滑块和选项，让我尝试这个动画的不同参数，并给我一个复制按钮，用来复制效果好的参数。
• 创建设计系统 artifact
• 调整组件
• 可视化组件库
• 制作动画原型
报告、研究和学习
Claude Code 非常擅长综合多个数据源中的信息，并把它转换成易读的报告。你可以提示 Claude 搜索你的 Slack、代码库、git 历史或互联网，并用这些信息生成容易阅读的报告。
你可以把它组织成长篇 HTML 文档、交互式讲解页面，甚至幻灯片/演示文稿。可以让 Claude 使用 SVG 绘制图表，帮助可视化。
我不理解我们的 rate limiter 实际上是怎么工作的。阅读相关代码，然后生成一个单页 HTML 讲解：包含 token-bucket 流程图、3 到 4 个带注释的关键代码片段，以及底部的“易踩坑”部分。请针对只读一遍的人优化阅读体验。
• 编写功能总结
• 生成讲解材料
• 起草每周状态报告
• 创建事故报告
• 生成 SVG 插图、流程图和技术图表，
自定义编辑界面
有时候，单靠文本框很难描述你想要什么。对于这个场景，我经常会让 Claude 为我正在处理的具体事情构建一个一次性编辑器：它不是产品，也不是可复用工具，而是一个专门为这一份数据定制的单个 HTML 文件。
关键技巧是最后一定要有导出功能：比如“copy as JSON”或“copy as 提示词”按钮，把你在 UI 里做的事情转换成可以粘贴回 Claude Code 或提交到文件里的内容。你仍然参与在循环里，但这个循环会紧密得多。
• 我需要重新排列这 30 个 Linear tickets 的优先级。给我做一个 HTML 文件，把每个 ticket 做成可拖拽卡片，放在 Now / Next / Later / Cut 四列中。请先按你的最佳判断预排序。添加一个“copy as Markdown”按钮，导出最终排序，并为每个分组附上一句话理由。
• 这是我们的 feature flag config。为它构建一个基于表单的编辑器，按区域对 flag 分组，展示它们之间的依赖关系，如果我启用了一个前置条件关闭的 flag，请提醒我。添加一个“copy diff”按钮，只输出变更过的 key。
• 我正在调优这个 system 提示词。做一个左右并排的编辑器：左侧是可编辑 提示词，并高亮变量占位符；右侧有三个示例输入，可以实时重新渲染填充后的模板。添加字符/token 计数器和复制按钮。
• 重新排序、分诊或分组任何内容（tickets、测试用例、反馈）
• 编辑结构化配置（feature flags、env vars、带约束的 JSON/YAML）
• 调优 提示词s、模板或文案，并提供实时预览
• 整理数据集：批准/拒绝行、给示例打标签、导出选择结果
• 标注文档、转录文本或 diff，并导出标注
• 选择那些用文字表达很痛苦的值：颜色、缓动曲线、裁剪区域、cron schedules、regexes
常见问题
下面是我最常被问到的关于在 Claude Code 中使用 HTML 的问题，以及我在日常实践中总结出的实用习惯：
这样不是效率更低吗？
虽然 Markdown 通常使用更少的 token，但我发现 HTML 增加的表达能力，以及我实际阅读它的概率大幅提高，意味着总体上我能得到更好的输出。借助 Opus 4.7 的 1MM 上下文窗口，增加的 token 使用量在上下文窗口里并不明显。
你现在什么时候使用 Markdown？
坦白说，几乎所有事情我都已经不再使用 Markdown 了，但我可能属于非常偏 HTML 最大化使用的那一类人。
这就是你替代规划的方式吗？
我发现自己不再只有一个单独的计划，而是倾向于为计划的不同部分/阶段准备几个不同的 HTML 文件。例如，我可能用 HTML 做一份实现计划，然后再做一个 UI 探索文件，最后再做一个列出所有设计的 HTML 组件。我也倾向于把这些文件保留下来，作为未来参考，也用于验证。
与 Claude 保持在循环中
上面所有内容其实都是在说明：我使用 HTML 而不是 Markdown 的真正原因，是它让我感觉自己更深地参与在与 Claude 的协作循环里。随着 Claude 承担更多工作，我注意到自己读计划越来越不仔细，而我想要一种方式，能持续参与它的选择，而不是简单把任务交出去。HTML 结果正好做到了这一点。现在我比以往任何时候都更有参与感。
开始使用 Claude Code。
本文由 technical staff 成员 Thariq Shihipar 撰写，表达的是他个人对在 Claude Code 中使用 HTML 文件的看法，以及偏爱。