MD文档 , 不是 AI Coding 的万能解法

先说清楚一件事：

用 组件.md 让 AI 生成前端页面，不是一件错的事，但它适合的场景，比很多人以为的要窄。

如果你在做一次性原型、HTML demo、或者快速探索某个交互方向，md 驱动完全没问题。跑通逻辑，验证想法，用完即弃，这是它的主场。

问题出在，当这套做法被用进正式项目里——一个需要迭代、需要多人协作、需要长期维护的产品——麻烦就开始了。

1.用 md 生成前端，正式项目里会发生什么

样式每次都不一样。AI 按 md 描述生成代码，但 md 写的是自然语言，不是精确数值。"主色按钮""圆角适中""间距舒适"——每次生成的结果都可能不同。没有 token 约束，样式一致性完全靠运气。

组件被反复重新发明。md 里描述了一个卡片、一个表格、一个弹窗，AI 每次都重新生成一份实现。项目里慢慢积累出五个长得差不多但代码完全不同的卡片组件，没有人知道该用哪个，也没有人敢删。

两套真相互相打架。工程里有一套真实组件在跑，md 里有一套描述在更新（或者没在更新）。只要有人改了组件，md 就可能过期。AI 读到的是旧规则，生成的结果和现有系统对不上，改完再同步，循环往复。

可维护性是假象。看起来有文档、有规范、有 AI 辅助，但实际上每次生成都是一次新的赌博。没有可复用的资产，没有单一事实源，只有越来越厚的 md 和越来越乱的代码目录。

2.根本问题：它制造了两套真相

组件.md 本质上是一份说明书，不是工厂。

说明书解释意图，工厂生产结果。

把按钮的视觉参数写进 md，和直接定义在 tokens.css 里——维护成本完全不是同一个量级。token 改一处，全局生效，AI 直接读到正确数值。md 改一处，AI 下次也许读到了，也许没有。

对工程师来说，token 和组件是可执行的事实。对产品经理来说，md 里的规则是可以理解的意图。对设计师来说，Design Token 是可以追踪的设计决策。

这三件事不是竞争关系，而是不同层次的表达。

问题在于把它们全部塞进 markdown，然后期待 AI 自己分清楚哪句是规则、哪句是数值、哪句是比喻。

3. MD文档真正应该站的位置

我现在把 AI Coding 的材料分成三层：

事实层。 Design Token、组件代码、图标库。这是单一事实源——颜色、字号、组件行为，答案只能有一个，必须活在代码里，不能活在描述里。

判断层。 这才是 md 的主场。写那些代码表达不了的东西：这个组件什么场景不该用、后台系统为什么不应该长得像营销官网、表单页为什么要把效率放在视觉炫技前面。这些判断 AI 需要读懂，才能做对决策。

模式层。 md 最有价值的地方。不是单个按钮怎么画，而是列表页、工作台、设置页整体怎么组织信息、排布优先级、什么时候用弹窗、什么时候用跳转。页面模式涉及架构和业务流程，用自然语言写反而最合适。

4.合理的工作流应该长这样

tokens.css            ← 颜色、间距、字号、圆角的唯一定义components/           ← Button、Table、Modal、Form 的真实实现  Button.vue  Table.vue  Modal.vue  Form.vuepatterns/             ← 列表页、详情页、工作台的页面组合方式  list-page.md        detail-page.md  dashboard.md  settings-page.mdai-rules.md           ← 告诉 AI 如何正确使用组件和规则component-usage.md    ← 集中说明关键组件怎么用

md 不是负担，而是 AI 的操作手册——告诉它怎么使用这套系统，而不是替代这套系统。

不要给每个组件都写一份 md，而是写一份 component-usage.md，集中说明关键组件怎么用。

比如里面可以写：

## Button- 优先使用 `<BaseButton />`- 不要手写原生 button 样式- 一个页面只保留一个主要操作按钮- 危险操作必须使用 danger 类型，并配合二次确认## Table- 数据列表优先使用 `<DataTable />`- 不要重新实现分页、排序、筛选- 表格字段超过 8 个时，优先考虑列配置或详情页承接- 空状态必须提供下一步操作## Modal- 不要在 Modal 里再打开复杂 Modal- 表单超过 8 项时，优先使用 Drawer 或独立页面- 删除、提交、发布类操作需要明确确认文案

最后

组件.md 生成前端这件事，在原型阶段是效率工具，在产品阶段是技术债的温床。

区别不在于 md 写得好不好，而在于你有没有一套真正可执行、可复用、可维护的底层资产。

所以我现在对 AI Coding 的判断是：

不要用 md 替代组件，而要用 md 约束 AI 正确使用组件。

AI Coding 的效率，不来自把一切都写成 markdown，而来自让 AI 接入一套真实可用的系统，然后用 md 告诉它怎么正确使用。