夜雨聆风上周 Claude Code 群里又吵起来了。
起因很简单：有人把一份技术 spec 存成了带完整 Tailwind 样式的 HTML，被同事喷"炫技"。喷回去的话也不好听——"用 Markdown 只是因为还没真正用过 Claude Code"。
吵了 200 楼。没人赢。但两边都在输——输的是 tokens、编辑效率、还有未来能搜到这些文档的概率。
其实这个问题根本不用吵。每次你让 Claude 产出一份文档，只需要问三个问题。三个问题回答完，格式自己就定了。
三个问题
Claude 产出的每一份文档，只有三个属性值得关心：
- 1. 谁读——人类？Claude（未来的某个 session）？还是两者都读？
- 2. 改多少次——写完就扔，还是反复修改？
- 3. 活多久——一天？一个季度？还是永久留存？
每个问题都会自动投票给 MD 或 HTML。三票一致，答案直接出来。出现分歧，就用混合方案。
就是这样。下面拆开讲。
第一个问题：谁真正会读这份东西？
Claude 回读自己产出的频率，远超大多数人的想象。
一份文档如果在未来的 session 里会被重新摄入——被项目索引抓取、被 RAG 管道切块、被另一个 agent 在写代码前当 spec 读——HTML 就是毒药。
拿一份真实文档算一下。800 个词，6 个小节，几个代码块：
- • Markdown：约 1100 tokens
- • HTML（带内联样式、class、一个小 SVG）：约 3200 tokens
三倍。乘以项目里 30 份参考文件——60K tokens 没了。而且是每次重新摄入都烧一遍。
更恶心的是检索质量。Claude Projects、Cursor 索引、Continue、LangChain 的 loader，切 HTML 的效果都比切 MD 差得多。标记语言稀释了语义信号，嵌入向量更模糊，同一份内容在检索相关性上直接掉 15-25%。
所以：这份文档是给 Claude 未来继续读的参考材料？MD，没有任何例外。一次性给人类看的交付物？HTML 可以上桌。
第二个问题：这东西要改多少次？
Claude 改 MD 跟改 HTML，完全是两种行为。
改 Markdown 里的一句话：5 行 diff。找到那行，替换，搞定。
改带样式的 HTML 里同一句话：40 到 100 行 diff。Claude 会"顺手整理"周围的标记——class 名悄悄变了，间距 token 换了，SVG 被重新输出但坐标微妙地偏移了几像素。你肉眼看不出来任何问题。但底层全在漂。
5 到 10 轮迭代之后，同一个 HTML 文件里共存着三套间距系统、四套配色方案。外观一切正常。代码层面已经烂了。
这个现象有个名字：标记漂移（markup drift）。它真正危险的地方在于——你只有把 V1 和 V8 diff 一遍，才发现文件里有一半的变更跟你的实际内容修改毫无关系。
经验法则：超过两三次修改的文档，MD 或混合。HTML 是发布格式，不是迭代格式。MDX 和 Markdoc 能缓解，但不能根治。
第三个问题：这东西要活多久？
做两个测试。
grep 测试：六个月后，你能在项目里跑 grep -r "定价" 找到这份文档吗？MD 能。HTML 里你搜的是 <h2>定价</h2>，实际存的是 <h2 class="section-title" data-anchor="pricing">定价方案</h2>。文档在那，但你找不到。
可存活测试：三年后打开这个 HTML。Tailwind CDN 链接还有效吗？Lucide 图标库 API 改了吗？Chart.js 大版本升级了吗？2015 年的 Markdown 文件现在双击还能看。2015 年带三个 CDN 引用的 HTML？大概率白屏。
所以：短暂展示用的、写完就扔的、demo 性质的——HTML 随便用。要被检索、被索引、要比你活得更久的——MD。
几个真实场景，直接对号入座
团队产品 spec：人类 + Claude 都要反复读，每周都在改，要活几个月。→ MD，每次都是，没有例外。
Slack 周报：人看一次就翻篇，写一次不修改，活一周。→ 如果版式真的有信息增量，HTML 可以上。 否则 MD 省你 20 分钟。
Pull Request 描述：人看、GitHub 渲染、Claude 在 code review 时读，写完不动，但被索引一辈子。→ MD。 GitHub 原生渲染，可 diff，永远能被搜到。
设计评审用的动画原型：人看、在会议上、会后即弃、活一小时。→ HTML，不用纠结。
系统架构文档：所有人都读，包括未来的 Claude，随系统演进持续修改，要活很多年。→ MD 做唯一事实来源，HTML 按需生成——比如给 CTO 看的高管版、给工程师看的完整版、给新人看的培训版。
最后这个，才是真正有价值的地方。
一份 MD 源，按需出多份 HTML
做得最好的团队是这么干的：
用一份 Markdown 维护权威版本。不同受众需要时，用不同的 system prompt 从同一个 MD 生成对应的 HTML。
一套 architecture.md，自动产出：
- • 高管视图：一页纸，顶层视图，零术语
- • 工程视图：完整文档 + 交互式 SVG 架构图
- • 新人培训包：同样内容加上内嵌问答和进度条
HTML 是派生产物。源文件一改，三个 HTML 全部重新生成。MD 保持可审查、可索引、可 grep 的全部优势。HTML 负责把所有展示重活干了。
搭这个不需要什么基础设施。一个十行脚本就够了——把你的 MD 喂给 Claude 三次，每次换一个 system prompt。不绑定任何工具。不对任何格式做承诺。
真正的收益是：你不需要做取舍了。MD 管长期能力，HTML 管表现力。事实来源永远是纯文本。
搞懂这点的团队基本不提这事儿——因为说出来显得太简单了。但它不简单。绝大多数团队在多个格式之间手动拷贝内容，三个星期之内各个版本就已经各说各话了。
一个 30 秒的可逆性测试
决定用 HTML 之前，只问自己一件事：
如果我现在就必须把它转回干净的 Markdown，一次 prompt 能搞定吗？
搞不定？说明你把内容写死在了标记语言里。这是巨大的红色警报。内容应该永远能从格式中干干净净地提取出来。当它们分不开的那一天，这份文档就进入了不可维护的死亡螺旋。
这个直觉检查，30 秒内能抓住 90% 的格式选择错误。
什么时候可以打破规则
只有三种情况：
- 1. 销售落地页或对外一页纸——视觉本身就是内容的一部分
- 2. 真正的一次性产物——你确定永远不会再碰
- 3. 交互式原型——交互行为就是交付物本身
最后
别再有格式立场了。开始问三个问题。让文档自己告诉你它想做什么格式。
你的团队产出的大多数文档，就是该用 Markdown。少数该用 HTML。一个权威源可以同时出两种。
在 Twitter 上为 MD vs HTML 站队的人，花在纠结格式上的时间，是那些建了个 30 秒决策流程然后继续干活的人的两倍。
格式是工具。它应该让你感觉不到它的存在。当你在为它争吵的时候，就已经在浪费时间了。
