你还在用 Markdown写AI文档?这个工程师已经全换成 HTML 了

过去十年，Markdown 一直是技术文档的默认答案。

但在 Claude Code、Cursor 这类 AI 编程工具普及之后，一个变化开始出现：

越来越多工程师，开始主动把文档从 Markdown 改回 HTML。

原因不是 HTML 更先进，而是当 AI 开始深度参与文档生成、修改和重构之后，Markdown 最核心的优势，正在快速缩水。

这并不意味着「Markdown 已过时了」。更准确地说，是它最适合的场景，正在发生变化。

这个判断并不只是社区里的零散讨论。今年 5 月，Claude Code 团队工程师 Thariq 分享了自己的实际工作流：在长期使用 Claude 协作编写文档、规格说明和代码评审报告之后，他发现自己几乎已经不再使用 Markdown。

他也强调，这更像一种偏激进的个人实践，而不是行业共识。但背后的逻辑，确实值得所有正在使用 AI 编程工具的人认真看一眼。

Markdown 遇到了什么问题

不是 Markdown 本身出了问题，是使用方式变了。

第一，超过 100 行就难读了。

Thariq 提到，他的团队里超过 100 行的 Markdown 文件，几乎没人愿意完整读完。Markdown 的设计前提是：人来写，人来读，纯文本适合版本控制。但当文档开始变长，嵌套加深，表格增多，读起来的体验和 HTML 渲染之间的落差越来越大。

第二，AI 已经在替你编辑了。

Markdown 最大的优势是什么？好写、好改、人能直接编辑。但如果你和 Claude 协作，大部分文档是 Claude 生成、Claude 修改，你只是在看和确认，那这个优势就不成立了。你已经不在"编辑"这个环节里了。

Markdown 的优势，本质上建立在人类亲自编辑文档这件事上。一旦 AI 接管了编辑环节，这个优势就空了。

第三，表达能力到顶了。

Markdown 没有颜色、没有真正的交互、没有 SVG、没有响应式布局。当模型想表达一个复杂的对比、一个流程图、一个参数调节界面，它只能用 ASCII 字符硬凑。这不是模型的问题，是容器的问题。

HTML 能做什么

Thariq 列了 5 类他现在实际在用的场景：

① 规格说明和方案探索

并排展示 6 种设计方案，带原型图和实施计划。Markdown 只能列编号，HTML 可以做网格对比、加颜色、加链接跳转。团队开会时直接打开浏览器看，不需要再转换格式。

② 代码评审报告

渲染 diff、行内注释、按严重程度着色。比纯文本的 PR comment 清晰很多，尤其是需要解释跨文件逻辑的时候。

③ 设计原型

Claude 生成一个带滑块的交互页面，你直接调参数看效果，调完把参数值传回给 Claude 继续迭代。这个闭环在 Markdown 里根本做不了。

④ 研究和报告

综合 git 历史、MCP 数据源、浏览器抓取结果，生成带 SVG 可视化的周报或事故报告。

⑤ 自定义编辑界面

拖拽排序的工单、可以开关的功能配置、实时预览的 prompt 调试界面。本质上是让 Claude 给你做了一个轻量级的内部工具。

分享方式：上传到 S3 生成链接，或者本地浏览器直接打开。不需要安装任何东西。

要说实话的地方

这条路不是没有代价。

优点	代价
表达能力强得多	生成速度慢 2-4 倍，Token 消耗更多
分享方便，阅读体验好	版本控制很麻烦，diff 混乱，代码评审难
可以做真正的交互	需要额外给 Claude 明确的样式要求，否则生成质量参差不齐

关于 Token 消耗：Thariq 的判断是在 1M 上下文窗口下额外消耗"几乎感受不到"。但这取决于你的使用频率和对 API 成本的敏感度，如果调用量大，这笔账值得单独算一下。

版本控制是他自己承认的最大缺点。如果你的工作流里 Git diff 很重要，这个成本是真实的，不要轻描淡写。

我的判断

这不是"Markdown 要被淘汰"的信号，是一个更具体的提示：当你的文档主要由 AI 生成、AI 修改，而不是人手写的时候，格式选择的逻辑就变了。

Markdown 适合的场景依然存在：

你自己手写、频繁 Git 提交的场景

需要被其他工具解析的场景（README、文档站、API 文档）

轻量协作、不需要复杂视觉呈现的场景

HTML 更值得考虑的场景：

你在用 Claude Code、Cursor 生成长文档、报告、规格说明

需要并排对比方案，或者展示流程图

文档要分享给团队，希望直接打开就能看，不依赖编辑器渲染

不需要全部切换，也不需要现在就做决定。

下一步可以做什么

下次让 Claude 出一份技术方案时，在 prompt 里加一句"用 HTML 格式输出，支持在浏览器直接打开，注意样式整洁可读"

对比一下可读性和信息密度，感受差异

如果你的场景涉及频繁 Git 提交，先评估版本控制的代价再决定要不要换

格式本身不是重点，重点是：当 AI 深度参与你的写作和编辑流程时，原来那套默认选择值不值得重新审视一遍。

好了，今天的分享就到此结束，咱们下回见。

如果觉得文章对你有帮助，记得点。赞。转。发。收。藏喔！

链接也船长，进 Hermes和 OpenClaw 小龙虾交流群！

也可以免费加入我的星球，围观学习 AI、IP 自媒体、副业等。