为什么选择HTML？

在我使用Claude Code进行工作时，HTML相比Markdown有几个显著优势，尤其适用于以下需求：

信息密度

HTML能传达比Markdown更丰富的信息。除了基本的文档结构如标题和格式外，它还能表达多种信息类型，例如：

• 使用表格展示数据
• 利用CSS进行设计
• 用SVG绘制插图
• 通过script标签展示代码片段
• 结合JavaScript和CSS实现交互
• 使用SVG和HTML描述工作流程
• 通过绝对定位和画布表达空间数据
• 使用img标签插入图片

我认为，几乎没有Claude无法读取且不能用HTML高效表达的信息类型。这使得HTML成为模型向你传递深度信息并方便你审阅的高效方式。

如果不能使用HTML，模型往往会用Markdown做一些效率较低的表达，比如ASCII图表，或者用Unicode字符估算颜色。

视觉清晰度与易读性

随着Claude处理更复杂的任务，它能生成越来越长的规格和计划。我发现自己通常不会认真阅读超过100行的Markdown文件，也很难让团队其他成员去读。

而HTML文档更易阅读，因为Claude可以通过标签页、插图和链接将结构视觉化，方便导航。它还能响应不同设备，适配手机或桌面阅读体验。

便于分享

Markdown文件不易分享，因为大多数浏览器无法原生良好渲染它们，通常需要作为附件发送。

只要上传HTML文件，就能轻松分享链接，团队成员可以随时打开并方便引用。

HTML格式大大提高了别人真正阅读你的规格、报告或PR说明的可能性。

双向交互

HTML还能让你与文档互动，比如添加滑块或旋钮来调整设计参数，或者调节算法选项，观察效果变化。你还可以复制这些调整，粘贴回Claude Code继续使用。

这让你能为具体问题创建定制化的编辑环境。

数据摄取能力

使用Claude Code生成HTML文件的最大优势之一是它能摄取大量上下文信息。例如，写这篇文章时，我让Claude Code扫描我的代码文件夹，找出所有生成的HTML文件，分类整理后生成一个包含各类示意图的HTML文件。文中图示即源于此。

除了文件系统，Claude Code还能通过MCP（如Slack、Linear等）、浏览器（Chrome中的Claude）和git历史获取更多上下文。

入门指南

值得一提的是，你无需复杂操作即可让Claude生成HTML，只需提示它“生成HTML文件”或“制作HTML工件”即可。关键是明确你希望工件实现的功能及用途。随着使用深入，你可以围绕常用模式建立技能，但从零开始尝试是了解其多样用例的好方法。

典型用例

为使方法更具体，以下是一些我认为HTML比Markdown更合适的用例示例，详细内容可见示例用例页面及GitHub示例库。

规格、规划与探索

HTML为Claude深入问题提供了丰富画布。开始时，我不会只写简单Markdown计划，而是构建一系列HTML文件。例如，先让Claude Code头脑风暴多种方案，制作探索文件；再深入某个方案，做界面原型或示例；最后写实施计划。满意后，新建会话导入这些文件进行实现。

验证时，我也会让验证代理读取这些文件，获得更全面的上下文。

示例提示：

• “我不确定入职界面方向。生成6个截然不同的方案，布局、风格和信息密度各异，做成单个HTML文件的网格，方便我并排比较。标注每个方案的权衡点。”
• “制作详细实施计划HTML文件，包含原型、数据流和关键代码片段，确保易读易消化。”

适用场景：

• 探索多种代码实现方式
• 同时试验多种视觉设计

代码审查与理解

Markdown中代码难以阅读，但HTML能渲染差异、注释、流程图和模块。用HTML理解代理写的代码、审查代码或向他人解释PR非常有效。

示例提示：

• “帮我审查这个PR，生成描述它的HTML工件。我对流控逻辑不熟，重点关注这部分。渲染实际diff，内联边注，按严重程度着色，尽可能清晰表达概念。”

适用场景：

• 创建PR
• 审查PR
• 理解代码主题

设计与原型

Claude Design基于HTML，因为HTML在设计表达上极具表现力，即使最终界面不是HTML。Claude可用HTML绘制设计草图，再转成React、Swift等语言代码。

还能原型交互，如动画、动作等。可让Claude制作滑块、旋钮，精准调节设计。

示例提示：

• “我想原型一个新的结账按钮，点击时播放动画，快速变紫。做一个HTML文件，带多个滑块和选项让我调节动画，附带复制按钮复制参数。”

适用场景：

• 创建设计系统工件
• 调整组件
• 可视化组件库
• 原型动画

报告、研究与学习

Claude Code擅长整合多数据源信息，生成易读报告。你可以让它搜索Slack、代码库、git历史或互联网，生成长HTML文档、交互式说明或幻灯片。

建议用SVG绘制图表，帮助可视化。

示例提示：

• “我不理解我们的速率限制器工作原理。阅读相关代码，生成单页HTML说明：令牌桶流程图，3-4个关键代码片段注释，底部‘注意事项’。优化为一次阅读即可理解。”

适用场景：

• 功能总结
• 说明文档
• 周报草稿
• 事件报告
• SVG插图、流程图、技术图表

定制编辑界面

有时纯文本框难以描述需求，我会让Claude为当前任务构建一次性编辑器：非产品、非通用工具，而是针对单条数据的HTML文件。

关键是要有导出功能，如“复制为JSON”或“复制为提示”，将UI操作结果转成可粘贴回Claude Code或提交的内容。这样你始终掌控流程，且效率更高。

示例提示：

• “我需要重新排序这30个Linear工单。做个HTML文件，每个工单做成可拖拽卡片，分布在‘现在/接下来/以后/删除’四列。先按你判断预排序。加个‘复制为Markdown’按钮，导出最终排序和每列简短理由。”
• “这是我们的功能开关配置。做个基于表单的编辑器，按区域分组，显示依赖关系，启用开关时若前置条件未满足给警告。加个‘复制差异’按钮，只导出修改项。”
• “我在调试系统提示。做个左右并排编辑器：左侧可编辑提示，变量槽高亮；右侧三个示例输入，实时渲染填充模板。加字符/令牌计数和复制按钮。”

适用场景：

• 重新排序、分类（工单、测试用例、反馈）
• 编辑结构化配置（功能开关、环境变量、JSON/YAML）
• 调试提示、模板，实时预览
• 筛选数据集，审批、标注、导出
• 注释文档、转录或diff并导出
• 选择难以用文本表达的值（颜色、缓动曲线、裁剪区域、定时任务、正则表达式）

常见问题

以下是我最常被问及的关于用HTML配合Claude Code的疑问及我的实践经验：

效率会不会降低？

虽然Markdown通常用词更少，但HTML的表达力更强且我更愿意阅读，整体输出质量更高。Opus 4.7的百万令牌上下文窗口让额外词数影响不大。

现在还用Markdown吗？

坦白说，我几乎不再用Markdown，可能是HTML的极端拥护者。

这就是你替代传统规划的方式吗？

我发现不止一个计划文件，而是多个HTML文件对应不同阶段或部分。例如一个实施计划文件，一个UI探索文件，最后一个设计组件列表文件。我会保留这些文件作为未来参考和验证用。

与Claude保持紧密协作

总结来说，我用HTML而非Markdown，主要是因为它让我更紧密地参与Claude的工作。随着Claude承担更多任务，我发现自己阅读计划的频率下降，想要一种方式保持对其决策的参与感，而非简单交付。HTML正好满足了这一需求，让我比以往任何时候都更“在圈内”。

开始使用Claude Code。

本文作者Thariq Shihipar为技术团队成员，文中观点为其个人见解，表达了他对使用HTML文件配合Claude Code的喜爱。