使用 Claude Code：HTML 出人意料的有效性

中文精读

原文约 2,273 词 · 20 节

1. 开篇与作者信息

   • 文章属于 Claude Code 使用系列，主题是团队成员如何以及为什么用 HTML 而不是 Markdown 来产出更丰富、更易读、更易分享的结果。
   • 作者 Thariq Shihipar，发布于 2026 年 5 月 20 日，阅读时长约 9 分钟。
   • Markdown 已成为智能体与人沟通的主流格式：简单、可移植、有一定富文本能力、易于编辑，Claude 甚至擅长在 Markdown 里用 ASCII 画图。

2. 为什么转向 HTML

   • 随着智能体能力增强，作者觉得 Markdown 越来越受限：超过一百行的 Markdown 文件难以阅读，无法做丰富的可视化、颜色和图表，也不便分享。
   • 作者越来越不亲自编辑这些文件，而是把它们当作规格（spec）和参考资料；需要改时通常让 Claude 去改，因此 Markdown 最大的优势之一被抵消。
   • 于是作者开始偏好 HTML 作为输出格式，并观察到 Claude Code 团队其他成员也在这样做；文中提供了常见用例的 HTML 文件模板供读者使用。

3. 为什么用 HTML？

   • 本节给出总述：对于作者现在用 Claude Code 做的、需要或涉及特定类型信息的工作，HTML 比 Markdown 更合适。
   • 后续几节分别从信息密度、视觉清晰度与易读性、易分享、双向交互、数据摄取几个方面展开理由。

4. 信息密度

   • HTML 能承载远比 Markdown 丰富的信息：除标题和格式等基本文档结构外，还能表达表格数据、CSS 设计信息、SVG 插图、script 标签中的代码片段等。
   • 还可以表达交互（HTML 元素加 JavaScript 与 CSS）、工作流（SVG 加 HTML）、空间数据（绝对定位与 canvas）、图片（image 标签）。
   • 作者认为几乎不存在 Claude 能读到而 HTML 无法高效呈现的信息集，这对模型传达深度信息和用户审阅都高效。
   • 若做不到这些，模型在 Markdown 里会采取低效做法，比如 ASCII 图，或用 Unicode 字符估算颜色。

5. 视觉清晰与易读

   • Claude 能处理更复杂的工作，也就会写出越来越长的规格和计划；作者发现自己实际不会读超过一百行的 Markdown 文件，也无法让组织里其他人去读。
   • HTML 文档更易读，因为 Claude 可以用标签页、插图、链接做视觉化的结构组织，便于导航。
   • HTML 还能做移动端自适应，让读者按设备形态以不同方式阅读。

6. 易于分享

   • Markdown 文件较难分享，因为多数浏览器不能良好地原生渲染，常需作为邮件或消息的附件。
   • HTML 文件上传后即可方便地分享链接，同事可在任意地方打开并轻松引用。
   • 作者认为，规格、报告或 PR 说明若以 HTML 形式呈现，被真正读到的概率会高得多。

7. 双向交互

   • HTML 还能让人与文档交互，例如让 Claude 加上滑块或旋钮来调节设计，或调整算法中的不同选项以观察结果。
   • 也可以让它支持把这些改动复制成提示词（prompt），再粘贴回 Claude Code。
   • 在有需要时，这能为手头的具体问题创建独立的编辑环境。

8. 数据摄取

   • 用 Claude Code 而不是 Claude.ai 或 Claude Design 生成 HTML 的最大理由之一，是 Claude Code 能摄取大量上下文。
   • 文中举例：写这篇文章时，作者让 Claude Code 读他的代码文件夹，找出所有生成的 HTML 文件，分类整理，再生成一个用图表表示每种类型的 HTML 文件；文中图表即由此而来。
   • 除文件系统外，Claude Code 还能通过 MCP（如 Slack、Linear 等）、浏览器（Claude in Chrome）以及 git 历史获取额外上下文。

9. 入门

   • 不需要做多少事就能让 Claude 生成这类 HTML：直接提示它“make an HTML file”或“make an HTML artifact”即可。
   • 关键是清楚希望这个产物做什么、自己会如何使用它。
   • 随着时间推移，为反复出现的模式构建 skill 是合理的，但从零开始提示是熟悉其在不同用例中表现的好办法。

10. 用例

    • 本节引出具体示例：列出了作者认为用 HTML 文件比 Markdown 更合理的若干用例。
    • 可配合这些用例的网站画廊以及 GitHub 上的用例库一并查看。

11. 规格、计划与探索

    • 作者把 HTML 当作 Claude 深入问题的丰富画布；处理一个问题时，他不做简单的 Markdown 计划，而是预期形成一组网状排布的 HTML 文件。
    • 流程示例：先让 Claude Code 头脑风暴并生成多个方案探索，再让它深入其中一个、做出界面原型或示例，最后写好实施计划。
    • 对计划满意后，开一个新会话并把所有这些文件传进去让其实施；验证时也让验证智能体读取这些文件，从而获得更广的上下文。
    • 示例提示包括：为 onboarding 页面生成 6 个布局、语气、密度各异的方案并排放在一个 HTML 网格里并标注各自取舍；或生成含原型、数据流、关键代码片段的易读实施计划。
    • 适用于：探索某功能的其他实现方式、同时试验多个视觉设计。

12. 代码审查与理解

    • 代码在 Markdown 里难读；用 HTML 可以渲染 diff、批注、流程图和模块。
    • 用途：理解智能体写的代码、审查代码，以及向审阅你代码的人解释一个 PR。
    • 示例提示：让 Claude 生成描述该 PR 的 HTML 产物，重点讲自己不熟悉的流式/背压逻辑，渲染真实 diff 并加页边（行旁）内联批注（inline margin annotations），按严重程度给发现着色，以及任何有助于讲清概念的其他内容。
    • 适用于：创建 PR、审查 PR、理解代码中的某个主题。

13. 设计与原型

    • Claude Design 基于 HTML，因为 HTML 在设计上表达力极强，即使最终载体不是 HTML；Claude 可先用 HTML 勾出设计，再用 React、Swift 等目标语言实现。
    • 也可以给交互做原型，如动画、动作等；可让 Claude 做滑块、旋钮来精确调出想要的效果。
    • 示例提示：为新的结账按钮做原型，点击后播放动画并快速变紫，生成带多个滑块与选项的 HTML 文件，并提供复制参数的按钮。
    • 适用于：创建设计系统产物、调整组件、可视化组件库、为动画做原型。

14. 报告、研究与学习

    • Claude Code 很擅长跨多个数据源综合信息并转化为易读报告；可让它搜索 Slack、代码库、git 历史或互联网。
    • 形式可以是长 HTML 文档、交互式讲解页，甚至幻灯片；可让它用 SVG 画图辅助可视化。
    • 示例提示：读相关代码并输出单页 HTML 讲解，含令牌桶流程示意图、3–4 个带注释的关键代码片段和底部的“坑”章节，面向只读一次的读者优化。
    • 适用于：写功能总结、生成讲解材料、起草周报、写事故报告、制作 SVG 插图、流程图和技术图示。

15. 自定义编辑界面

    • 有些东西很难只用文本框描述，作者常让 Claude 为手头这一件事构建一次性编辑器：不是产品也不是可复用工具，而是针对这一份数据定制的单个 HTML 文件。
    • 诀窍是最后一定要有导出：一个“copy as JSON”或“copy as prompt”按钮，把界面里的操作转回可粘贴进 Claude Code 或提交到文件的内容，从而保持人在回路且回路更紧。
    • 三个示例提示：把 30 个 Linear 工单做成可拖拽卡片分入 Now/Next/Later/Cut 四列并导出带理由的 Markdown 排序；为特性开关配置做表单编辑器，按区域分组、显示依赖、前置未开时告警并导出改动 diff；为系统提示词做左右对照编辑器，高亮变量槽、三个样例输入实时渲染，并带字符/令牌计数与复制按钮。
    • 适用于：重排、分诊或分桶事项；编辑受约束的结构化配置；带实时预览调提示词/模板/文案；整理数据集（批准/拒绝、打标签、导出选择）；给文档、转录或 diff 加注释并导出；挑选难以用文字表达的取值，如颜色、缓动曲线、裁剪区域、cron 计划、正则。

16. 常见问题

    • 本节收集作者最常被问到的关于用 HTML 搭配 Claude Code 的问题，并给出他在日常实践中的习惯做法。
    • 后续几节分别回答效率、是否还用 Markdown、以及是否以此替代规划三个问题。

17. 这样不是更低效吗？

    • Markdown 通常用的 token 更少，但作者认为 HTML 额外的表达力以及自己更愿意去读，使整体产出更好。
    • 在 Opus 4.7 的 1M 上下文窗口下，增加的 token 用量在上下文里并不明显。

18. 现在什么时候还用 Markdown？

    • 作者表示几乎对所有场景都已完全停用 Markdown。
    • 他自称大概属于 HTML 极端派那一端。

19. 这是你替代规划的方式吗？

    • 作者的做法不是只有一份计划，而是为计划的不同部分/阶段准备若干不同的 HTML 文件。
    • 例如先做 HTML 实施计划，再做一份 UI 探索文件，最后做一个列出所有设计的 HTML 组件。
    • 这些文件会被保留下来，作为日后的参考资料，也用于验证。

20. 与 Claude 保持同频

    • 作者用 HTML 而不用 Markdown 的真正原因，是它让他在与 Claude 协作时更有“在回路中”（in the loop）的感觉。
    • 随着 Claude 承担更多工作，他注意到自己读计划不再那么仔细，因此想要一种方式保持对其选择的参与，而不是直接交出去。
    • HTML 正好满足这一点，作者称自己现在比以往任何时候都更在同频状态。
    • 文末注明该文由技术团队成员 Thariq Shihipar 撰写，表达的是他个人对用 HTML 搭配 Claude Code 的观点与偏好。