过去十年，Markdown 一直是技术文档的默认答案。但在 Claude Code、Cursor 这类 AI 编程工具普及之后，一个变化开始出现：越来越多工程师，开始主动把文档从 Markdown 改回 HTML。原因不是 HTML 更先进，而是当 AI 开始深度参与文档生成、修改和重构之后，Markdown 最核心的优势，正在快速缩水。这并不意味着「Markdown 已过时了」。更准确地说，是它最适合的场景，正在发生变化。这个判断并不只是社区里的零散讨论。今年 5 月，Claude Code 团队工程师 Thariq 分享了自己的实际工作流：在长期使用 Claude 协作编写文档、规格说明和代码评审报告之后，他发现自己几乎已经不再使用 Markdown。他也强调，这更像一种偏激进的个人实践，而不是行业共识。但背后的逻辑，确实值得所有正在使用 AI 编程工具的人认真看一眼。
Markdown 遇到了什么问题
不是 Markdown 本身出了问题，是使用方式变了。Thariq 提到，他的团队里超过 100 行的 Markdown 文件，几乎没人愿意完整读完。Markdown 的设计前提是：人来写，人来读，纯文本适合版本控制。但当文档开始变长，嵌套加深，表格增多，读起来的体验和 HTML 渲染之间的落差越来越大。Markdown 最大的优势是什么？好写、好改、人能直接编辑。但如果你和 Claude 协作，大部分文档是 Claude 生成、Claude 修改，你只是在看和确认，那这个优势就不成立了。你已经不在"编辑"这个环节里了。Markdown 的优势，本质上建立在人类亲自编辑文档这件事上。一旦 AI 接管了编辑环节，这个优势就空了。
Markdown 没有颜色、没有真正的交互、没有 SVG、没有响应式布局。当模型想表达一个复杂的对比、一个流程图、一个参数调节界面，它只能用 ASCII 字符硬凑。这不是模型的问题，是容器的问题。
HTML 能做什么
并排展示 6 种设计方案，带原型图和实施计划。Markdown 只能列编号，HTML 可以做网格对比、加颜色、加链接跳转。团队开会时直接打开浏览器看，不需要再转换格式。渲染 diff、行内注释、按严重程度着色。比纯文本的 PR comment 清晰很多，尤其是需要解释跨文件逻辑的时候。Claude 生成一个带滑块的交互页面，你直接调参数看效果，调完把参数值传回给 Claude 继续迭代。这个闭环在 Markdown 里根本做不了。综合 git 历史、MCP 数据源、浏览器抓取结果，生成带 SVG 可视化的周报或事故报告。拖拽排序的工单、可以开关的功能配置、实时预览的 prompt 调试界面。本质上是让 Claude 给你做了一个轻量级的内部工具。分享方式：上传到 S3 生成链接，或者本地浏览器直接打开。不需要安装任何东西。
要说实话的地方
| |
|---|
| |
| |
| 需要额外给 Claude 明确的样式要求，否则生成质量参差不齐 |
关于 Token 消耗：Thariq 的判断是在 1M 上下文窗口下额外消耗"几乎感受不到"。但这取决于你的使用频率和对 API 成本的敏感度，如果调用量大，这笔账值得单独算一下。版本控制是他自己承认的最大缺点。如果你的工作流里 Git diff 很重要，这个成本是真实的，不要轻描淡写。
我的判断
这不是"Markdown 要被淘汰"的信号，是一个更具体的提示：当你的文档主要由 AI 生成、AI 修改，而不是人手写的时候，格式选择的逻辑就变了。需要被其他工具解析的场景（README、文档站、API 文档）你在用 Claude Code、Cursor 生成长文档、报告、规格说明文档要分享给团队，希望直接打开就能看，不依赖编辑器渲染
下一步可以做什么
下次让 Claude 出一份技术方案时，在 prompt 里加一句"用 HTML 格式输出，支持在浏览器直接打开，注意样式整洁可读"如果你的场景涉及频繁 Git 提交，先评估版本控制的代价再决定要不要换格式本身不是重点，重点是：当 AI 深度参与你的写作和编辑流程时，原来那套默认选择值不值得重新审视一遍。
如果觉得文章对你有帮助，记得点。赞。转。发。收。藏喔！链接也船长，进 Hermes和 OpenClaw 小龙虾交流群！也可以免费加入我的星球，围观学习 AI、IP 自媒体、副业等。
夜雨聆风
