DESIGN.md 不是“写了就生效”：让编码 Agent 真正守住设计系统，要过 3 道门
很多团队已经开始给 Claude Code、Codex、Cursor 这类编码 Agent 配 DESIGN.md。 但“仓库里有一个设计文档”和“Agent真的按它工作”是两回事。 这批素材给了三个很实用的方向：规则写具体、显式接入、上线前校验。重新核当前官方文档后，这个方法是成立的，但有一个需要纠正的动态点：检查 Claude Code 已加载哪些 memory 文件，应以当前官方记忆
DESIGN.md 不是“写了就生效”：让编码 Agent 真正守住设计系统，要过 3 道门
很多团队已经开始给 Claude Code、Codex、Cursor 这类编码 Agent 配 DESIGN.md。
但“仓库里有一个设计文档”和“Agent真的按它工作”是两回事。
这批素材给了三个很实用的方向：规则写具体、显式接入、上线前校验。重新核当前官方文档后，这个方法是成立的，但有一个需要纠正的动态点：检查 Claude Code 已加载哪些 memory 文件，应以当前官方记忆机制为准，不能把旧帖子里的 /context 当永久命令。
Anthropic 当前文档说明 CLAUDE.md 会进入项目记忆，并支持用 @path/to/import 引入额外文件；当前文档提供的查看已加载 memory 文件入口是 /memory。
这正好说明一个更大的原则：
Context File Exists ≠ Agent Loaded It。
1. 第一扇门：规则必须“可执行”
“现代、简洁、高端、有呼吸感”是给人看的方向感，不是给 Agent 的约束。
Agent真正能稳定执行的是：
- color token；
- spacing scale；
- typography；
- radius；
- component state；
- responsive breakpoint；
- keyboard/focus；
- aria/contrast；
- forbidden pattern；
- screenshot acceptance。
例如，不要写：
> 卡片要高级一点。
而写：
> Card使用8px radius；默认padding 20px；移动端16px；shadow只允许level-1；interactive card必须有hover/focus；正文对比度达到项目指定标准。
抽象审美可以留在顶部，但底下必须有机器可验证规则。
2. 第二扇门：进入上下文
设计文件放在根目录，不意味着任何 Agent 都会自动读取。
对于 Claude Code，当前官方机制可以通过 CLAUDE.md 中的 @DESIGN.md 方式引入，之后用当前 memory 查看机制确认。
其他 Agent 也一样。
需要一个通用 Context Contract：
File → Import Mechanism → Scope → Load Verification → Conflict Priority → Version。
尤其当项目同时有：
CLAUDE.md
AGENTS.md
DESIGN.md
CONTRIBUTING.md
docs/
如果没有冲突优先级，Agent可能读取了，却不知道谁覆盖谁。
3. 第三扇门：设计系统要能 lint / diff / screenshot QA
Google 的 DESIGN.md 项目当前提供 CLI，可以 lint 文档，也可以比较两个 DESIGN.md 的差异。
这比“我觉得规则写得挺完整”更好。
但 lint 只能检查规范结构，不会自动证明实际页面符合设计。
最终仍要有三层：
Spec Lint
设计规则是不是结构完整。Implementation Diff
组件/token有没有偏离规范。Visual Acceptance
真实页面在桌面/移动端、长文本、空状态、错误态、键盘导航下是否合格。4. 一个容易忽略的 Windows 问题
当前 Google DESIGN.md 项目仍处于较早期阶段。Windows 下通过 npm 全局命令调用时，曾有命令解析兼容问题，项目文档提供了 designmd 这类兼容调用方式。
这类问题提醒我们：
Tool Command Drift / OS Compatibility 必须进入教程。
不能因为原帖给了一条命令，就把它当五年有效的固定接口。
5. DESIGN.md 最值得产品化的不是“模板”，而是 Agent Design Contract
我会把它抽象成七层：
- Visual Intent
- Design Tokens
- Component Contract
- Responsive Contract
- Accessibility Contract
- Forbidden Patterns
- Acceptance Evidence
然后再加：
Context Import； Version； Diff； Visual QA； Human Design Gate。
这样它就不只是“让AI更懂设计”的Markdown文件，而是一份真正的交付合同。
6. 这和传统 Design System 的差别
传统设计系统重点是给设计师和工程师共享。
Agent时代多了一层：
规则必须能被机器读取； 冲突必须有优先级； 变更必须可比较； 输出必须可验收； Agent不能用“差不多”替代视觉标准。
所以真正的价值不是多写一份文档，而是把审美意图变成：
可读 → 可执行 → 可检查 → 可回归。
7. 商业机会
这个方向可以直接并入现有 Agent Output UX Contract / AI MVP Build Loop。
面向小团队的付费服务不是“送你一个 DESIGN.md模板”，而是：
- 从现有网站反推设计规则；
- 清理冲突 token；
- 建组件契约；
- 接 Agent context；
- 做 lint/diff；
- 做页面视觉回归；
- 建 PR acceptance checklist。
如果交付后只是“Agent少问几句”，价值不大。
V3 要验证的是：
UI返工次数是否下降？PR review时间是否下降？视觉偏差是否减少？
Stop Rule
如果 DESIGN.md： 写得很长； Agent也加载了； 但真实页面仍需要大量人工逐像素修；
那就不要继续往文档里塞形容词。
应该回到：规则是否可测、组件是否复用、验收是否自动/半自动。
设计文档不是提示词。
它应该是一份 Agent 真的无法含糊过去的合同。