④ YAML 契约：设计意图的接口定义，编译即规则-阿里云开发者社区

如果你让AI生成一个"删除账户"按钮，它很可能给你一个蓝色实心按钮，用户一点，账户没了。这不是AI故意使坏，而是约束显化设计规矩在从人传到机器的过程中，层层丢失了。

前面三篇文章，我们一步一步解决了这个问题：

① 语义令牌表，先把"严重""Critical""致命"这些人话，翻译成机器能看懂的离散级别（就像给颜色编了色号）。

① 语义字典，把这些编了号的级别，统一收进一本"机器字典"里注册管理。不是谁想填什么就填什么，契约里的每个值必须先在这本字典里查得到，查不到的机器直接报错。

② 语义域，再定义"什么时候用什么级别"。同样是红色，告警场景用"致命"，通知场景用"提示"，场景错了，级别就对不上。

③ 约束显化（把规矩形式化到代码里），论证了为什么要形式化：以前设计规矩写在文档里，AI看不见；现在必须写成代码格式，AI生成前就能读到。

但形式化之后，一个新问题出现了：

就算团队决定写YAML契约规则文件，里面的每个值也是凭感觉编的。颜色级别填什么？场景填什么？这些值是设计师拍脑袋写的，还是查出来的？如果每个人填得都不一样，那规则文件本质上还是"文档换皮"，机器仍然不知道对不对。

当语义规范体系与YAML 契约格式已经定义了"怎么写"之后，YAML契约被机器读取、编译、执行时的真实形态，不是设计师看到的YAML文本，而是机器消费链路中的4种可执行格式。

一句话：规则文件不是"自由写作文"，而是"查字典填表格"。

1. 问题：规矩形式化为代码里了，机器怎么读？

行业现状中，设计规范以三种形态存在：自然语言文档供人阅读、设计稿供人查看、代码注释供人理解。这三种形态对机器都是不可执行的，机器读不懂"错误状态分四级"这句话，读不懂Figma里的红色背景条，读不懂代码里的 // 注释。

这导致三个系统性问题：

规范是"死的"：设计师更新了规范，发在语雀文档里，前端可能看漏，AI工具完全不可见。规范更新后，下游没有任何自动同步机制；
契约是"散的"：同一个"删除账户"的约束，设计师写在PRD里，前端写在代码注释里，AI工程师写在Prompt里，三份约束各自为政，版本不同步，语义互相矛盾；
验证是"人眼的"：走查靠设计师截图圈问题，覆盖率20%，剩下80%的语义错误上线后才被用户投诉。机器没有"查规矩"的能力，只能靠人眼逐页核对。

6个漂移模式 中的 ERR-001错误状态后果差异未分级、BND-001边界动作权利差异未区分等，根因都是"规矩写在文档里，机器读不到"。语义令牌表定义了 status.critical，语义字典注册了它的唯一含义，语义域限定了它的使用范围，但如果没有YAML契约把这些定义编译成机器可执行的格式，令牌、字典、域都只是"纸面上的正确"。

2. 为什么自然语言守不住：规矩不可执行

设计规范文档用自然语言描述约束："致命错误用红色脉冲，限流用黄色时钟，删除按钮必须二次确认"。但自然语言对机器是不可执行的：

AI生成工具读不懂"必须二次确认"，它的训练语料里只有按钮的样式参数，没有"二次确认"的行为约束；
前端工程师看到的是代码注释 // 删除按钮要二次确认，但注释不参与编译，不会被校验，漏掉也不会报错；
CI流水线只能校验代码语法和样式合规，无法校验"这个红色按钮是否匹配了正确的语义级别"；
验收走查依赖人的主观判断，"感觉这个红色不对"无法转化为可复现的机器规则。

语义令牌表已经把"红色"编码为 status.critical，语义字典已经注册了它的唯一含义。但如果没有YAML契约作为"接口定义"，令牌和字典仍然是"定义层"的资产，无法进入"执行层"。YAML契约的作用，就是把"定义层的语义资产"翻译成"执行层的机器规则"，让机器可以读取、编译、校验、拦截。

3. 设计思路：契约是接口，编译即规则

本文的设计思路是三个递进命题：

契约是接口定义：YAML契约不是"设计规范的另一种写法"，而是"设计意图的机器接口"。定义了"机器在生成界面时，必须遵守什么、禁止做什么、违反后怎么处理"；
编译即规则：一份YAML契约被机器读取后，不是"被看懂"，而是被编译为4种可执行的机器格式，Prompt 前缀给AI编程工具、JSON Schema给结构校验器、Checklist给设计师走查、CI规则给自动化流水线。同一组语义约束，在不同工具链中以不同格式执行同一规则；
机器拦截现场：当AI试图生成违规内容时，机器不是"提示建议"，而是"直接阻断"，返回错误码、给出修正建议、阻止代码合并。契约不是文档，是机器执行的拦截规则。

3.1 契约不是"另一种文档格式"

以前设计规范写在语雀/Confluence 里，更新后 @ 全员通知。现在YAML契约放在Git仓库里，改一次，编译管线自动把变更同步到所有消费方。

对比：

	自然语言规范	YAML 契约
存储位置	语雀/Confluence 文档	Git 仓库里的 .yaml 文件
版本管理	手动记录，版本混乱	Git 提交历史，Diff 可追溯
变更通知	@全员，人可能看漏	Git Diff 自动触发影响面分析
机器可读	不可读，AI 工具不可见	可读，编译管线直接消费
校验能力	人眼走查，覆盖率 20%	机器自动校验，覆盖率 100%
违反处理	事后发现，人工修正	编译前置阻断，自动返回错误

为什么这样做：把规范从"给人看的文档"变成"给机器执行的代码"。

3.2 一份契约，四种机器形态

设计师写一份YAML契约，机器自动把它编译成四种东西，给四种不同的工具用。

编译链路：

设计师写 YAML 契约 → 编译管线读取 → 输出4种格式：

Prompt 前缀 → 注入 Claude Code / Cursor 上下文
JSON Schema → 供 CI 流水线校验组件 Props
Checklist → 供设计师走查时逐项核对
CI 规则 → 供 GitHub Actions / ESLint 自动拦截

为什么这样做：设计师只写一次，四种消费方自动拿到自己需要的东西。不用设计师给工程师写一遍、给运维写一遍、给测试写一遍。

3.3 机器拦截现场：违规即阻断

以前AI生成违规内容，走查时才发现，人工修正。现在机器在生成前即校验，违规直接阻断，返回错误码和修正建议。

拦截流程：

AI 生成器输出内容 → 编译管线加载YAML契约 → 四层校验：

语法推演：JSON 结构是否完整？
语义推演：语义令牌引用是否正确？
安全推演：是否违反不可变边界？
美感推演：文案长度、信息密度是否合规？
→ 任一校验失败 → 返回错误码 + 修正建议 → 阻断合并
→ 全部通过 → 输出合规内容 → 允许合并

为什么这样做：把"事后走查"变成"事前拦截"。错误在生成阶段就无法成立，不会流入生产环境。

3.4 契约引用字典，不自创语义

YAML契约中的 semantic_domain、semantic_tokens 等字段，必须引用语义字典中已注册的定义，不可自创。字典没有的，先走字典变更流程注册，再引用。

查表路径：

YAML 契约加载 → 编译管线解析 → 逐条核对引用：

semantic_domain 是否在字典覆盖层目录中？
semantic_tokens 是否在字典语义绑定中？
跨层引用是否违反跨层禁止规则？
→ 非法引用 → 返回 dictionary-reference-not-found → 阻断
→ 合法引用 → 继续编译 → 输出 4 种格式

为什么这样做：防止"契约自创语义"。所有语义必须在字典中先注册、后引用，确保组织级语义一致性。

3.5 四条思路的依赖关系

依赖关系：语义令牌表（离散值）→ 语义字典（注册表）→ 语义域（覆盖层）→ YAML 契约（接口定义）→ 编译管线（执行层）→ 四种机器形态（消费层）

4. 本文的核心命题

"**形式化为代码的规矩**，在机器世界里长什么样"必须翻译成可验证的框架设计。本文回答三个命题：

命题	验证标准
契约可被机器编译	同一份YAML能被编译为Prompt前缀 / JSON Schema / Checklist / CI规则四种格式，且四种格式执行同一语义规则
契约可被机器校验	机器能在生成前置阶段（编译期 / Lint期 / 生成期）自动校验契约合规性，违规即阻断
契约可被机器消费	四种消费方（AI编程工具 / 结构校验器 / 设计师 / CI流水线）能无歧义地消费编译产物，无需人工翻译

一、调整前：四个角色的真实反馈

在没有YAML契约之前，设计意图的传递处于"人传人"状态。用各角色自己的话说：

设计师的真实反馈："规范写在语雀里，前端说没看到，AI工程师说没空看。"

"错误状态分四级"供人阅读，但前端在写代码时不会打开语雀查文档，AI工程师在写Prompt时也不会翻阅设计规范。规范更新后，@ 全员通知，但消息淹没在群里，没人记得看。规范是"死的"，它存在，但不被执行。

前端的真实反馈："代码注释里写了'要二次确认'，但注释不参与编译，漏掉也不会报错。"

// 删除按钮要二次确认，这是一条给人类阅读的提醒，不是给机器执行的规则。CI流水线不会检查"这个按钮有没有二次确认"，代码审查时也可能看漏。注释是"散的"，它存在，但不可校验。

AI工程师的真实反馈："Prompt里写了一大段设计规范，但AI还是把删除按钮做成了蓝色实心。"

AI工程师在Prompt里手动粘贴设计规范，但 Prompt 长度有限，规范写不全；不同工程师贴的规范版本不同，有的贴v1.0，有的贴v1.2；AI对自然语言规范的理解是概率性的，"必须二次确认"可能被理解为"建议二次确认"。Prompt是"软的"，它存在，但不可强制执行。

DesignOps 的真实反馈："规范更新了，怎么知道哪些产品没改？只能一个个去问。"

规范从v1.0升级到v1.1，DesignOps需要 @ 10个前端负责人，开3场同步会，2周后走查发现3个产品没改对。规范同步靠人肉广播，遗漏率指数增长。

汇总成一张表：

工具 / 环节	界面层呈现状态	缺失什么
设计规范文档	供人阅读，机器不可见	机器可执行的接口定义
代码注释	供人理解，不参与编译	机器可校验的规则
AI Prompt	自然语言描述，概率性理解	机器可强制执行的约束
规范同步	人肉广播，遗漏率高	自动同步、Diff可追溯的机制

四条反馈指向同一个根因：设计意图没有"机器接口"。它要么飘在文档里、靠人阅读，要么写在注释里、靠人理解，要么贴在Prompt里、靠概率执行，机器拿不到、读不懂、执行不了。

二、把意图形式化为机器可校验的契约

OpenAPI/Swagger主张接口即契约，前后端依赖同一份机器可消费的契约文件协作。这与我的YAML契约逻辑一致： 设计意图本身即是机器可消费的契约文件，AI按契约生成界面，CI按契约校验输出 。 Protobuf/gRPC将接口定义直接代码化，由Git原生管理版本。我的YAML契约管线同理，它相当于 “界面语义的.proto”，被编译成Prompt/JSON Schema/Checklist/CI等不同产物，供不同工具链消费 。

GraphQL将类型定义为契约，编译期即可拦截错误。这与我的“四层推演机制”异曲同工，语义错误在生成前置阶段就被拦截，不流入生产。

工业界虽有类似尝试（如W3C DTCG定义了机器可读的Design Tokens），但我是在其之上扩展了语义约束层。行业现状往往只是“换名”（如color-red-500改名color-danger），缺乏行为约束与机器拦截能力。这恰恰反证了YAML契约的核心价值：它不只是换个名字，而是将“必须做什么、禁止做什么、违规怎么处理”固化为机器可执行的规则。

三、关键设计：查字典写约定书

3.1 契约是什么

YAML契约是设计意图的机器接口：它定义了"在某个语义域的边界内，某个组件必须表达什么语义、禁止做什么、违反后怎么处理"。契约不定义新的语义，语义在语义字典中注册；契约只引用字典中的已定义项，把引用组合成"场景级的约束实例"。

3.2 完整示例：ERR-001 契约的机器消费链路

以 ERR-001（错误状态后果差异未分级）的契约为例，展示从YAML文本到四种机器形态的完整编译链路。

YAML契约原文（设计师写的）：

intent_id: "ERR-001"
semantic_domain: "transactional"
description: "错误状态语义分级"

semantic_tokens:
  error_severity:
    fatal:
      description: "系统级故障，对话上下文可能丢失"
      visual_mapping:
        color_token: "status.critical"
        motion_token: "pulse.red.urgent"
        icon_token: "alert.octagon"
      user_action:
        - label: "刷新页面"
          action: "refresh"
        - label: "导出历史"
          action: "export_history"
      llm_constraints:
        - "必须明确告知用户对话上下文可能已丢失"
        - "禁止仅显示'出错了'等模糊文案"
        - "必须提供恢复路径"

    transient:
      description: "网络抖动，系统可自动恢复"
      visual_mapping:
        color_token: "status.neutral"
        motion_token: "spinner"
        icon_token: "loader"
      user_action:
        - label: "等待自动恢复"
          action: "wait"
      llm_constraints:
        - "必须显示自动重试进度"
        - "禁止使用红色背景"

    retryable:
      description: "用户可自助恢复的频率限制"
      visual_mapping:
        color_token: "status.warning"
        motion_token: "none"
        icon_token: "clock"
      user_action:
        - label: "等待倒计时"
          action: "wait_countdown"
        - label: "升级套餐"
          action: "upgrade"
      llm_constraints:
        - "必须显示剩余等待时间"
        - "必须提供升级路径"

    degraded:
      description: "部分功能可用，可继续生成"
      visual_mapping:
        color_token: "status.info"
        motion_token: "none"
        icon_token: "continue"
      user_action:
        - label: "继续生成"
          action: "continue"
      llm_constraints:
        - "必须说明哪些功能仍然可用"

【演示环境：编译管线：从唯一事实来源到四种机器形态】

3.3 机器形态 1：Prompt前缀（给AI编程工具）

编译产物：机器把YAML契约编译成一段Prompt前缀，自动注入到 Claude Code / Cursor 的上下文。

Prompt前缀文本（机器编译产出）：

# 设计意图约束（由体验架构师定义，版本 v1.0.0）
在生成任何错误状态界面时，必须遵守以下语义分级：

【致命错误 fatal】
- 视觉：红色脉冲 + 八边形警告图标
- 行为：必须提供"刷新页面"和"导出历史"两个用户行动
- 文案：必须明确告知"对话上下文可能已丢失"
- 禁止：仅显示"出错了"等模糊文案

【网络抖动 transient】
- 视觉：灰色加载动画 + 旋转图标
- 行为：显示自动重试进度
- 禁止：使用红色背景（避免情绪过载）

【限流 retryable】
- 视觉：黄色提示 + 时钟图标
- 行为：显示剩余等待时间 + 提供升级路径
- 禁止：使用红色（避免用户恐慌）

【降级 degraded】
- 视觉：蓝色提示 + 继续图标
- 行为：说明哪些功能仍然可用
- 提供："继续生成"和"简化问题重试"两个选项

参考意图契约：intent/ERR-001.yaml

3.4 机器形态 2：JSON Schema（给结构校验器）

编译产物：机器把YAML契约编译成JSON Schema，供CI流水线校验组件Props。

JSON Schema片段（机器编译产出）：

{
   
  "$id": "intent/ERR-001.schema.json",
  "title": "错误状态语义分级校验",
  "type": "object",
  "required": ["error_severity", "user_action", "recovery_path"],
  "properties": {
   
    "error_severity": {
   
      "type": "string",
      "enum": ["fatal", "transient", "retryable", "degraded"],
      "description": "错误级别必须在字典预定义列表中"
    },
    "user_action": {
   
      "type": "array",
      "minItems": 1,
      "description": "必须提供至少一个用户行动"
    },
    "recovery_path": {
   
      "type": "string",
      "description": "fatal 级别必须提供恢复路径"
    }
  },
  "if": {
   
    "properties": {
    "error_severity": {
    "const": "fatal" } }
  },
  "then": {
   
    "required": ["recovery_path"],
    "properties": {
   
      "color_token": {
    "const": "status.critical" },
      "motion_token": {
    "const": "pulse.red.urgent" }
    }
  }
}

3.5 机器形态 3：Checklist（给设计师走查）

编译产物：机器把YAML契约编译成可打印的走查清单。

Checklist表格（机器编译产物）：

检查项	合格标准	引用契约
错误状态是否有颜色区分	不能全是红色	ERR-001 § semantic_tokens.error_severity
fatal 级别是否提供恢复路径	必须有"刷新页面"或"导出历史"	ERR-001 § fatal.user_action
transient 级别是否使用红色	禁止使用红色背景	ERR-001 § transient.llm_constraints[1]
retryable 级别是否显示倒计时	必须显示剩余等待时间	ERR-001 § retryable.llm_constraints[0]
degraded 级别是否说明可用功能	必须说明哪些功能仍然可用	ERR-001 § degraded.llm_constraints[0]

3.6 机器形态 4：CI规则（给自动化流水线）

编译产物：机器把YAML契约编译成 GitHub Actions / ESLint 规则。

CI规则片段（机器编译产物）：

# .github/workflows/semantic-check.yml
name: 语义一致性校验
on: [pull_request]
jobs:
  semantic-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: 加载语义契约
        run: |
          intent-schema-compiler load intent/ERR-001.yaml
      - name: 四层推演校验
        run: |
          intent-schema-compiler validate             --syntax             --semantic             --safety             --aesthetic
      - name: 违规即阻断
        if: failure()
        run: |
          echo "语义校验失败，PR 无法合并"
          exit 1

3.7 机器拦截现场：当AI试图生成违规内容

场景：AI工程师让 Claude Code 生成一个限流提示。

未注入契约时：

AI输出："请求过于频繁，系统出现严重错误"（红色背景）
结果：用户恐慌性刷新，其实等30秒就好
问题：AI把 retryable 级别做成了 fatal 级别的视觉

注入契约后：

机器先查 ERR-001.yaml → 匹配到 retryable 级别
机器拦截：llm_constraints 禁止用"严重"描述限流，禁止用红色背景
机器返回修正建议："请使用黄色提示 + 时钟图标 + 倒计时文案"
AI重新生成："请求过于频繁，请在42秒后重试"（黄色提示 + 倒计时）

拦截日志：

[语义校验] 开始推演...
[语法推演] ✓ 通过 - JSON 结构完整
[语义推演] ✗ 阻断 - error_severity 匹配为 retryable，但视觉映射为 status.critical（红色）
  期望：status.warning（黄色）
  契约引用：ERR-001.yaml § retryable.visual_mapping.color_token
[安全推演] ✗ 阻断 - llm_constraints 违反："禁止使用红色背景"
  契约引用：ERR-001.yaml § transient.llm_constraints[1]
[修正建议] 请将视觉映射改为 status.warning（黄色时钟 + 倒计时）
[编译结果] 阻断 ✕ - PR 无法合并

3.8 依赖关系

四、架构层概念：设计背景

契约是接口，不是实现。 YAML契约只定义"必须做什么、禁止做什么"，不定义"怎么实现"。具体实现由前端框架、AI工具、设计系统各自决定，契约只约束语义，不约束技术选型。

编译管线是翻译器。编译管线读取YAML契约，查询语义字典，展开语义令牌，输出四种机器格式。它是"定义层"到"执行层"的翻译器，把设计师的意图翻译成机器可执行的规则。

四种形态是消费面。 Prompt前缀给AI工程师用，JSON Schema给前端用，Checklist给设计师用，CI规则给DevOps用。同一组语义约束，在不同角色面前呈现为不同的"使用界面"。

在全景中的位置。 YAML契约位于建设层的中游（接口层）：语义字典（上游·元规则）→ YAML契约（中游·接口）→ 编译管线（下游·执行）→ 四种机器形态（消费层）。契约不确定，编译管线没有输入，四种形态无法生成。

面向不同读者群时，YAML契约有两套叫法：设计意图的接口定义 ≈ 机器可执行的契约；编译即规则 ≈ 契约被机器消费时的形态。两套术语指向同一份YAML文件。

五、这些坑怎么被解掉

回到开头的四条真实反馈，看契约就位后它们各自的解法路径。

踩过的坑 1："规范写在语雀里，前端说没看到，AI工程师说没空看"

症状复盘：规范更新后，@ 全员通知，但消息淹没在群里，没人记得看。规范是"死的"。
根因：规范以自然语言文档形态存在，机器不可见，无法自动同步。
关联机制：④ YAML 契约（编译管线）+ ① 语义字典（版本治理）
解法路径：规范写成YAML契约，放在Git仓库里。设计师提交变更 → Git Diff自动触发影响面分析 → 编译管线重新编译四种格式 → 所有消费方自动更新。前端和 AI 工程师不需要"看文档"，他们使用的Prompt前缀和 JSON Schema自动跟着更新。
验证方式：规范从v1.0升级到v1.1，下游四种消费格式在5分钟内同步更新，无需人工通知。

踩过的坑 2："代码注释里写了'要二次确认'，但注释不参与编译"

症状复盘：// 删除按钮要二次确认，注释是给人看的，机器不校验，漏掉也不会报错。
根因：约束以注释形态存在，不可执行、不可校验。
关联机制：④ YAML 契约（JSON Schema 编译产物）+ 字典引用的机器防线
解法路径：约束写成YAML契约，编译为JSON Schema。前端组件的Props必须匹配Schema，缺少二次确认即被CI阻断，PR无法合并。
验证方式：前端提交代码时，CI自动校验组件Props是否符合契约，违规即阻断，无需人工走查。

踩过的坑 3："Prompt里写了一大段设计规范，但AI还是把删除按钮做成了蓝色实心"

症状复盘：AI工程师在Prompt里手动粘贴规范，但规范写不全、版本不同、理解概率性。
根因：Prompt是自然语言约束，不可强制执行，理解是概率性的。
关联机制：④ YAML 契约（Prompt 前缀编译产物）+ 前端与AI工程师
解法路径：契约编译为Prompt前缀，自动注入AI上下文。AI生成时先加载约束，再生成内容，约束不是"建议"，是"前置条件"。
验证方式：同一Prompt，注入契约前AI生成蓝色实心按钮；注入契约后AI生成红色空心按钮 + 二次确认。

踩过的坑 4："规范更新了，怎么知道哪些产品没改？只能一个个去问"

症状复盘：DesignOps人肉广播，2周后走查发现3个产品没改对。
根因：规范同步没有自动机制，依赖人工跟踪。
关联机制：④ YAML 契约（Git 版本管理）+ DesignOps
解法路径：YAML契约放在Git仓库里，版本管理、Diff追溯、影响面分析都是Git的原生能力。DesignOps提交变更后，Git Diff自动显示影响了哪些契约、哪些消费格式、哪些产品。
验证方式：规范变更后，影响面分析报告在10分钟内自动生成，列出所有受影响的产品和文件。

六、调整后：工具界面层的呈现状态

工具 / 环节	调整前	调整后
设计规范	语雀文档，供人阅读	YAML契约，机器可执行；Git版本管理，Diff可追溯
代码注释	// 注释，不参与编译	JSON Schema，CI自动校验，违规即阻断
AI Prompt	自然语言描述，概率性理解	Prompt前缀，自动注入，约束前置
规范同步	人肉广播，遗漏率高	Git Diff自动触发，影响面分析自动生成
验收走查	人眼逐页核对，覆盖率20%	Checklist逐项核对 + CI自动拦截，覆盖率100%
违规处理	事后发现，人工修正	编译前置阻断，自动返回错误码和修正建议

七、一句话总结（给不同角色）

给设计师：

"你以前写'错误状态分四级'在语雀文档里，前端可能看漏。现在你写一份YAML契约，机器自动把它变成 Prompt前缀、JSON Schema、Checklist、CI规则，四种人自动拿到自己需要的东西，不用你发四遍通知。"

给前端：

"你不需要在代码注释里写'要二次确认'，注释不参与编译。现在契约编译成JSON Schema，你的组件Props必须符合Schema，缺少二次确认CI直接阻断，PR合不进去。"

给 AI 工程师：

"你不需要在Prompt里手动粘贴设计规范，规范写不全、版本还乱。现在契约自动编译成Prompt前缀，注入你的AI上下文，AI生成前先加载约束，不会再把删除按钮做成蓝色实心。"

给 DesignOps：

"你不需要@全员开会同步规范，改一次YAML契约，Git Diff自动告诉你影响了哪些产品、哪些文件。规范同步从2周降到5分钟。"

给管理层：

"以前规范是'死的'，写在文档里，机器读不到。现在规范是'活的'，写成YAML，机器自动编译、自动校验、自动同步。语义一致性从'人盯'变成'机查'，返工率从30%降到5%。"

边界声明

YAML契约不定义新的语义（那是语义字典的职责），不约束视觉值的具体色值（那是 Design Token 层的职责），也不约束"契约被不被正确引用"（消费纪律在角色侧，见角色专题 ①｜设计师与产品经理）。当前量化收益均为数据模型推演，待生产数据验证。

1920

④ YAML 契约：设计意图的接口定义，编译即规则

1. 问题：规矩形式化为代码里了，机器怎么读？

2. 为什么自然语言守不住：规矩不可执行

3. 设计思路：契约是接口，编译即规则

3.1 契约不是"另一种文档格式"

3.2 一份契约，四种机器形态

3.3 机器拦截现场：违规即阻断

3.4 契约引用字典，不自创语义

3.5 四条思路的依赖关系

4. 本文的核心命题

一、调整前：四个角色的真实反馈

二、把意图形式化为机器可校验的契约

三、关键设计：查字典写约定书

3.1 契约是什么

3.2 完整示例：ERR-001 契约的机器消费链路

3.3 机器形态 1：Prompt前缀（给AI编程工具）

3.4 机器形态 2：JSON Schema（给结构校验器）

3.5 机器形态 3：Checklist（给设计师走查）

3.6 机器形态 4：CI规则（给自动化流水线）

3.7 机器拦截现场：当AI试图生成违规内容

场景：AI工程师让 Claude Code 生成一个限流提示。

3.8 依赖关系

四、架构层概念：设计背景

五、这些坑怎么被解掉

踩过的坑 1："规范写在语雀里，前端说没看到，AI工程师说没空看"

踩过的坑 2："代码注释里写了'要二次确认'，但注释不参与编译"

踩过的坑 3："Prompt里写了一大段设计规范，但AI还是把删除按钮做成了蓝色实心"

踩过的坑 4："规范更新了，怎么知道哪些产品没改？只能一个个去问"

六、调整后：工具界面层的呈现状态

七、一句话总结（给不同角色）

边界声明

云原生

热门文章

最新文章

相关电子书

④ YAML 契约：设计意图的接口定义，编译即规则

1. 问题：规矩形式化**为代码里**了，机器怎么读？

2. 为什么自然语言守不住：规矩不可执行

3. 设计思路：契约是接口，编译即规则

3.1 契约不是"另一种文档格式"

3.2 一份契约，四种机器形态

3.3 机器拦截现场：违规即阻断

3.4 契约引用字典，不自创语义

3.5 四条思路的依赖关系

4. 本文的核心命题

一、调整前：四个角色的真实反馈

二、把意图形式化为机器可校验的契约

三、关键设计：查字典写约定书

3.1 契约是什么

3.2 完整示例：ERR-001 契约的机器消费链路

3.3 机器形态 1：Prompt前缀（给AI编程工具）

3.4 机器形态 2：JSON Schema（给结构校验器）

3.5 机器形态 3：Checklist（给设计师走查）

3.6 机器形态 4：CI规则（给自动化流水线）

3.7 机器拦截现场：当AI试图生成违规内容

场景：AI工程师让 Claude Code 生成一个限流提示。

3.8 依赖关系

四、架构层概念：设计背景

五、这些坑怎么被解掉

踩过的坑 1："规范写在语雀里，前端说没看到，AI工程师说没空看"

踩过的坑 2："代码注释里写了'要二次确认'，但注释不参与编译"

踩过的坑 3："Prompt里写了一大段设计规范，但AI还是把删除按钮做成了蓝色实心"

踩过的坑 4："规范更新了，怎么知道哪些产品没改？只能一个个去问"

六、调整后：工具界面层的呈现状态

七、一句话总结（给不同角色）

边界声明

云原生

热门文章

最新文章

相关电子书

1. 问题：规矩形式化为代码里了，机器怎么读？