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

- 原标题：Using Claude Code: The unreasonable effectiveness of HTML
- 类型：博客
- 来源：Claude Code 团队博客
- 发布时间：2026-05-20
- 首次精选：2026-10-28 16:25
- 分级：值得看
- 学习层级：入门
- 主题：[claude-code-ecosystem](<https://oplearnx.com/md/topics/claude-code-ecosystem.md>)（第 2 位）、[creative-coding-design](<https://oplearnx.com/md/topics/creative-coding-design.md>)（第 3 位）
- 原文链接：[https://claude.dev/blog/using-claude-code-the-unreasonable-effectiveness-of-html](<https://claude.dev/blog/using-claude-code-the-unreasonable-effectiveness-of-html>)
- 本站页面：[https://oplearnx.com/resources/pk\_f1ea10ecc51a](<https://oplearnx.com/resources/pk_f1ea10ecc51a>)

## 摘要

Claude Code 团队成员 Thariq Shihipar 撰写的使用心得，讨论团队成员为何以及如何用 HTML 而非 Markdown 产出更丰富、更易读、便于分享的结果。文中提到 Markdown 虽已成为智能体与人类交流的主流格式，但随智能体能力增强，在生成长文档、可视化、颜色和图表方面显得受限。文章包含缘起、入门、用例和常见问题等部分。

## 中文精读

### 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 的观点与偏好。

---
来源：LearnMap · 学径（https://oplearnx.com）