Atlassian DESIGN.md Performance Analysis

Atlassian 实测 DESIGN.md：为什么 Atlassian 认为它不如 MCP 和 Skills，却依然值得用 ？ 为了解决 AI 生成的界面普遍呈现同质化 (俗称 AI Slop/AI 味)，Atlassian 设计系统团队构建了面向 AI 的“上下文引擎”：ADS MCP server、Agent Skills，底层是一套同时服务人和 Agent 的结构化内容模型。 后来他们实测了 DESIGN.md 方案，从驱动 MCP 和 Skills 的同一条结构化内容管线自动生成 DESIGN.md，并通过两个实际场景进行测试，得出了企业应用中很实战的结论。 atlassian.com/blog/ai-at-wor… # 场景一：一次性原型 —— 表现良好 测试场景是 Team '26 大会主题演讲的现场 demo：用 Figma Make 基于 Teamwork Graph 生成自定义仪表盘，要求一次成型、且不能依赖内部 MCP 服务。 结果：DESIGN.md 把生成物从通用“slop”变成了可辨识的 Atlassian 风格，颜色、间距、形状、字体和层级都符合系统预期。作者认为这类高层指引特别适合去定制 Tailwind、Shadcn 这类通用库、从零生成 UI。 # 场景二：生产代码库 —— 明显劣于 MCP 与 Skills 生产环境的特点是：已有 token 和组件库，有严格的 lint 与类型检查。 在这种环境下，用 DESIGN.md 作为唯一设计上下文完成一个简单的登录页任务，表现最差： · 无上下文：设计系统上下文覆盖约 5%，平均 4.20M tokens，6 分 19 秒，43 轮 · ADS MCP：约 80% 覆盖，3.75M tokens，5 分 1 秒，35.1 轮 —— 最优 · ADS Skill：约 80% 覆盖，4.43M tokens，5 分 23 秒，36 轮 · DESIGN.md：仅约 30% 覆盖，7.21M tokens，6 分 46 秒，45.3 轮 关键结论：DESIGN.md 比 MCP 多消耗约 92% 的 token，耗时更长，且运行间 token 消耗方差约为 2.7 倍。值得注意的是，DESIGN.md 甚至比“完全没有上下文”还差。 # 三个结构性局限 局限 1：上下文一次性全量加载，而非按需获取 MCP 可以通过 ads_plan 等工具调用只拉取某个组件的指引；上百个图标、大量语义 token 只在需要时进入上下文。Skills 粒度稍粗，但也拆成了多个小文件。DESIGN.md 则是每次全部加载：起步成本更高、响应更慢，上下文更早被截断，进而损害准确度。 局限 2：文件必须精简，精简即丢失 Atlassian 供 MCP/Skills 按需读取的指引约 2.5 MB；而 DESIGN.md 压缩到 80 KB（约 19,800 tokens，去掉 frontmatter 约 10,700），这已经比社区常见样例大。为此他们砍掉了 50 多个组件的大部分用法指引、大幅精简基础指引、删除低频 token。后果是：Agent 要么产出不准确，要么自己去翻组件源码找缺失的用法说明，这正是实测中 token 暴涨的原因之一。 局限 3：它暴露的是设计系统的“内部实现”，会诱导重复造轮子 DESIGN.md 本质是用散文把设计系统重新描述一遍，目的是让人能从零重建一份。在成熟的生产环境里，这不仅多余，还可能制造技术债。Agent 读到按钮的 backgroundColor、textColor、borderColor 规格后，倾向于自己重新实现一个按钮；而正确做法应是 import Button from '@ atlaskit/button' 后直接使用 <Button appearance="primary" spacing="compact" />。 共享组件的价值在于单点修改、全局生效，以及更易审查维护。DESIGN.md 有意不包含代码层面的使用指引，实测中它确实更频繁地重造组件、轮次波动也最大。 Atlassian 的对策：MCP 与 Skills 扎根于技术底座，是“如何使用现有系统的说明书”而非“如何重建系统的图纸”；再配合 lint 规则，零 token 成本地对人和 Agent 一视同仁地强制代码规范，形成正向反馈。 # DESIGN.md 真正适合的场景 Atlassian 并未否定这个格式，只是划清了它的适用边界。共同点是：现有设计系统的产出物不可用或不实用的环境。 · 高层艺术方向：若团队从未文档化视觉气质与感觉，DESIGN.md 的散文部分是有价值的产物；但 frontmatter 部分与代码库重复。 · 陌生环境的快速原型：早期概念探索或试用新工具时，无需配置整套技术栈，也不用组件约束拖累模型。 · 与设计工具的互操作：一些 AI 工具通过定制预制组件来拼装 UI，DESIGN.md 的抽象层级恰好匹配。 · 客户主题化的自适应 UI：产品若要动态生成报表、图表、仪表盘，DESIGN.md 让客户能描述自己的品牌，使 AI 输出“像客户的品牌而非你的”。可以想象为管理员或品牌团队上传到工作工具中的一个选项。 # 开放共享与对标准的反馈 Atlassian 在 atlassian. design/DESIGN.md 公开了自己的文件，态度是“宁愿参与塑造标准，而非被动响应”。他们的文件与当前标准有小幅偏离：加入了渲染组件所需的非标准属性；因标准尚不支持主题切换，单独发布了暗色模式版本。相关反馈已提交 GitHub，部分建议已被规范采纳。 一句话概括 Atlassian 立场：DESIGN.md 是设计系统的可移植“快照”格式，不是更丰富的设计系统工具链的替代品。 · 如果你的 Agent 支持 MCP 或 Skills，用它们能以更低成本获得更好结果。 · 如果需要跨平台可移植、客户主题化、早期概念原型，一份结构良好的 DESIGN.md 是显著进步。 💬 0 🔄 0 ❤️ 0 👀 102 ⚡