别再让AI写Markdown了：一个CLAUDE.md规则让产出从没人看到被转发到董事会
一句话说清楚
一个简单的CLAUDEMD规则，把你所有AI产出的默认格式从Markdown换成HTML，效果立刻天差地别。
Marco Kotrotsos 做了实测：同一个内容的每日简报，用Markdown生成时只有40%的早晨会打开，换成HTML后每天必看。客户报告从「存了归档」变成「被转发到董事会议案里」。
同样的AI、同样的提示词，换了输出格式，结果天差地别。
这不是玄学，是人类行为学。
为什么Markdown是错的
Markdown的设计初衷是：开发者能在编辑器里舒服地读。它的语法简洁、纯文本、Git友好，适合在GitHub上展示README，适合在终端里浏览，适合被版本控制。
但问题在于——AI产出的东西大部分不是给开发者读的。
你让AI生成一份客户报告、一条项目状态更新、一个每日简报、一份复盘总结，这些东西的受众是：
- 客户（在手机上快速扫一眼）
- 老板（在Slack里打开）
- 同事（在浏览器里翻一下）
- 未来的自己（在某个周二早晨打开看看）
这些人不会打开一个Markdown渲染器。他们不会在终端里运行 cat 命令。他们不会去理解 ## 和 ### 的区别。
大多数情况下，Markdown文件在磁盘上躺了一周，然后就被删除了——从未被打开过。
HTML为什么赢
HTML和Markdown的区别不在于「哪个更容易写」，而在于哪个更容易读。
| 维度 | Markdown | HTML |
|---|---|---|
| 打开方式 | 需要渲染器/编辑器 | 浏览器直接打开 |
| 视觉呈现 | 纯文本+少量标记 | 设计好的卡片页面 |
| 分享便捷度 | 需要说明「你先渲染一下」 | 截图/链接直接发 |
| 感知价值 | 像是草稿 | 像专业人士做的 |
| 打印/归档 | 需要转换 | 自包含，直接可用 |
HTML单个文件、内联所有CSS、自包含，保存、邮件、粘贴到Slack、归档到Notion，全部零依赖。打开就是一张设计好的视觉卡片。
实测数据：同一个内容，不同的命运
作者做了三个场景的实测：
1. 每日简报
- Markdown版：40%的早晨会打开
- HTML版：每天早上必看
- 同一个内容、同一个Claude、同一个prompt。只是格式从
.md变成.html。
2. 客户报告
- Markdown版：被存了，被归档了
- HTML版：被转发到公司内部，被引用到董事会的议案材料里
- 「HTML版本因为看起来像值得认真对待的文档，获得了更多的注意力。」
3. 项目状态面板
- Markdown版：一大段文字，重启项目后就不会再看
- HTML版：每个项目一个卡片，颜色编码健康状态，始终开着一个标签页
- 「HTML版本保持了一目了然的特性。」
三个场景的共同点：当产出的内容是为人类消费设计的，渲染过的版本比原始文本获得更多的注意力。
CLAUDEMD规则：十分钟搞定
核心操作很简单——在你的 CLAUDE.md 里加一段规则（无论全局还是项目级别）：
## Output format
For any artifact intended for human consumption (reports, briefings, summaries,
plans, retros, status updates, memos, decks):
- Default to a single self-contained HTML file with inline CSS
- Use semantic HTML (h1, h2, sections) and embedded styles
- Visual style: clean typography, generous whitespace, restrained color use
- Always include a print-friendly stylesheet (@media print)
- Light Mode is the default.
- File extension .html, save in artifacts/ alongside the markdown source
For reference material that will only be edited (specs, configs, READMEs,
project notes): keep markdown as the primary format.
When unsure: ask "is this for someone to read or someone to edit?"
Read = HTML. Edit = markdown.
这段规则的灵魂在最后一句："这东西是给人读的还是给人改的？"
- 给人读的（报告、简报、总结、计划）→ HTML
- 给人改的（README、API文档、项目笔记）→ Markdown
三个实用标准
1. 单文件零依赖
单个HTML文件，所有CSS内联在 <style> 标签里，所有SVG图表内联。不要外链字体、不要CDN、不要JavaScript（除非产物本身是交互式的）。
读者可以保存文件、邮件发送、粘贴到Slack、丢进Notion页面、归档用于合规检查，所有操作都不会出问题。
2. 始终包含打印样式
@media print {
body { background: none; }
.card { break-inside: avoid; }
/* 页面边距调整 */
}
作者发现大约30%的高管会打印AI生成的报告。打印布局比你想象的重要得多。
3. 克制设计
Claude有一种「加一百个图标和渐变背景」的冲动。要抑制它。
- 最多两个强调色
- 充足的留白
- 无衬线正文字体
- 看起来像一个细心的人类设计师做的，而不是Tailwind游乐场
把这些约束写在 CLAUDE.md 里，Claude会严格执行。
Markdown仍然赢的场景
这篇文章不是说「永远别用Markdown」。以下三个场景我仍然用Markdown：
1. 代码仓库内的文档 README、API规范、架构文档。这些由人类编辑、由GitHub等平台渲染。Markdown是正确格式。
2. 可编辑的草稿 文章草稿、进行中的规范、需要几周时间修改的文档。切换到Markdown的边际成本很低，编辑体验更好。
3. 给未来AI的笔记 CLAUDE.md、skill文件、agent prompt。AI解析Markdown比HTML更干净，结构足够清晰。
更大的趋势
「渲染输出」这个洞察不是Claude Code特有的。它在多个层面同时发生：
- 协议层：MCP Apps让工具返回UI组件而不是文本墙
- 产品层：Claude Design让视觉产物直接被渲染展示
- 工作流层：你的Claude Code生成的HTML而不是Markdown
人类花了几十年被训练成「忽略纯文本、注意设计过的界面」。AI继承了这个不对称。实验室正在协议和产品层面追赶，你的本地工作流也应该跟上。
说人话的总结
人就是会忽略纯文本、关注设计过的界面，这是人性。AI不能改变人性，AI应该适应人性。
一个CLAUDE.md规则，十分钟改完。从此你生成的AI内容不再躺在磁盘里吃灰，而是真正被打开、被阅读、被转发。
判断标准：这东西是给人读的还是给人改的？ 读 = HTML，改 = Markdown。
原文：Writing HTML For Documentation Instead of Markdown is a Game-Changer，作者 Marco Kotrotsos。