7字段YAML契约模板：把设计规范变成机器可执行的规则

设计规范人传人，对机器却是死条文。本文拆解一套7字段YAML契约模板，将语义规则写成机器可校验、可编译的接口，并给出从验收、起草到编译分发的完整操作流程。看它如何让AI生成工具、CI流水线真正执行设计约束，而非依赖人的记性。

设计规范的问题在于人传人：语雀文档、代码注释、Prompt里的规矩，对机器都是死的。《YAML契约》留言区有位读者把这个判断说得很准，”真正难的不是格式，而是让团队接受查字典填表格”。

这个模板正面接住这个难题：用7个字段，把一条语义规则写成机器可校验、可编译、可追踪的契约。它不是文档，是接口，编译之后，它会变成AI生成工具的Prompt前缀、前端的JSON Schema、设计师的走查Checklist、流水线的CI规则。

规则不再靠谁的记性，也不再靠谁今天有没有看群。

一、模板本体

7个字段全部冻结：字段名、含义、顺序不要动。机器靠它们做格式校验和编译。

二、逐字段：起草要点 + 评审要点

这份模板有双重用途：起草时它是规范，评审时它是尺子，同一把尺子，量自己也量别人。

三个字段各带一层展开：

version，版本信任是校验规则的地基：当前版本由 Git 作为权威时钟、审批链作为人工共识来定义，不靠管理员手动点发布（版本信任机制的三假设论证，见《契约的机器防线》）。

semantic_tokens，注册纪律分两种状态（draft机制来自《语义字典》）：

“字典里查不到就先随手写一个”，是这个体系最危险的苗头。

mmutable_boundaries，机器是”合规即正确”，人是”意图即正确”：笼统要求”必须有确认”，机器会字面满足、语义偏离。《把1条”绝对不能”翻译成机器规则》里”按钮文案不能为『确认』”那个细节，堵的就是这个缝。

三、完整示例：ERR-001 错误分级契约

对应漂移模式 ERR-001（后果差异未分级）：LLM生成告警/错误文案时，Critical被同义词降级为”严重”（漂移现场见《字段层差异》）。

评审这条契约时，三个硬要求对应核查：格式（7字段完整）、语义（四个令牌均 registered，无自创）、证据（关联模式卡片ERR-001后果差异未分级及其快照证据链）。

四、框架设计背景：

YAML契约不是一份格式更好的规范文档，而是 把设计规范写成代码格式（Schema-As-Code） 框架里”设计意图的接口定义”。要理解为什么必须是7个字段、为什么评审要恒定执行同一把尺子，需要先看到它在整条流水线中的位置。

4.1 三阶段全景

把设计规范写成代码格式（Schema-As-Code）不是一套理论，是一条可执行的三阶段流水线（Semantic Pipeline）：

4.2 契约横跨三个阶段

• Guard 阶段：契约从诊断来。设计师提交的6字段快照，经三层判定归档为模式卡片，模式卡片就是契约的出生证明，没有模式背书的契约是想象需求。
• Contract 阶段：契约是唯一的”源”。四种编译产物全部由它派生、禁止手改；契约升级即触发重编译，下游四处同步换版。手改契约是唯一的规则变更入口。
• Verify 阶段：契约是被验证的对象。消费追踪挂在契约版本上（谁在消费、沉默了没有），对抗用例的断言与契约条款同源生成，验证的所有读数，最终都回答”这份契约写得对不对”。

4.3 回到开篇的问题

为什么文档约束不了AI？ 因为自然语言规范对机器不可执行：AI生成工具不读语雀文档，CI不拦文档条款，版本改了无人对账。约束只有落地为代码形态、进入生成链路，才真正存在（从”文档约束”到”工程资产”的完整论证，见《约束显化》）。

为什么是7个字段？ 它们是”一条规则能被机器执行”的最小完备集，标识、意图、版本、域、范围、语义定义、边界，少一个，编译产物就有一类无法生成；多一个，就属于执行细节而非接口定义。

为什么评审这么严格？ 因为契约是编译的源：源头宽一寸，四种产物就歪一丈。退回不是拒绝，是翻译能力的第一道把关。

五、操作流程：一条契约从原料到规则生效

先看人机分工的总图。这条流程不是”你多了一套表格要填”，而是”机器自动跑编译和分发，你只在语义判断点上出手”：

Step 1：验收，上游快照过三条硬要求

不满足就退回，退回时说明缺什么。这个动作本身就在训练组织内的翻译能力。

Step 2：起草，把模式卡片翻译成7字段

先查字典，再写契约：所有 semantic_tokens 必须引用字典已注册项（《语义令牌表》）；需要的令牌还没注册，先走draft通道注册，再回来起草。

无工具时：用文本编辑器手写YAML，人工对照自检清单校验。

Step 3：提交，机器自动跑前置校验

编译前置校验5项机器安检（机制见《编译前置校验》）：全部通过 → 自动入库；任何一项失败 → 阻断并返回具体错误项，你回到对应字段修正。正常流程不需要人盯，人只在异常时介入。

Step 4：评审，语义保真的人工确认

机器能管结构、语法和交叉比对，但这条规则”对不对”，要人签字：它是否真实对应模式卡片里的漂移证据？边界条款是否可判定？诊断结论的签字权在人，不在机器。

Step 5：编译分发，机器自动跑，产物到四方

一句取舍请守住：标准恒定，消费侧不适靠修订规则细节吸收，不靠放松标准。

Step 6：抽样与追踪，确认翻译没有失真

编译之后有一个动作不能省：从已确认的契约里抽一个语义点，到四种格式里各找一处表达，核对严格程度是否一致（方法见《对1个语义点做四格式抽样》）。最隐蔽的分叉是措辞弱化，Checklist把”禁止”写成了”建议”。看到分叉就写成反馈，否则下次编译原样产出。

追踪侧：消费点接入强制登记、加载自动上报，注册表的第一死因是变成死文件（双重闭环的设计见《契约消费追踪双重闭环验证》）。沉默规则由机器标记，归因由人做：是没分发到，还是规则本身有问题。

关键认知：翻译能力属于工作流节点，不属于岗位。组织初期，验收、起草、评审、抽样可能都是你一个人完成的，同一个人走完所有节点，但节点之间的输入输出契约一个不少。这不是效率问题，是标准问题（完整论述见《编译工作流中的上下游要求》）。

六、你在体系里的位置：翻译能力的承担节点

你是评审者，也是生产者：上游的快照由你验收，契约由你起草或评审，编译产物由你抽样确认。组织里唯一同时看见上游输入和下游消费的人，就是你。

这个位置不属于某个编制，它由三类动作定义：

你的上游：设计师、产品经理、任何发现问题的人，他们交6字段快照，你按三条硬要求验收。

你的下游：AI工程师、前端工程师、设计师/DesignOps、前端团队，他们消费四种编译产物，反馈回流到你这里。

你的核心动作只有四个：验收 → 起草/评审 → 抽样 → 归因。

七、交付标准与自检

评审通过不等于规则生效。一条规则的完整生命周期是：被发现 → 被翻译 → 被评审 → 被编译 → 被消费 → 被证明一直在工作。 你负责的是中间三段，但验收标准是最后一段。

提交评审前自检清单（7条，全勾再走）：

1. 7 个字段完整，字段名与冻结模板一致
2. intent_id 全局唯一且可读
3. semantic_tokens 全部来自字典已注册项（draft 项带 status/review_date）
4. immutable_boundaries 每条都可机器判定，无”尽量/建议”类措辞
5. 关联至少 1 个真实产品实例或模式卡片证据链
6. 版本号遵守版本纪律
7. 一个契约只管一个语义域

评审他人提交的契约时，同一张清单，标准的及格线由你恒定执行，不因起草人是谁而改变。

八、最小可行：一个人的翻译闭环

翻译能力的生长只改”谁在节点上”，不改”节点的及格线”。

九、常见误会

“7个字段会不会表达不了复杂规则？”

表达不了的时候，先怀疑是契约粒度错了：一个契约只管一个语义域、一条漂移模式。拆成多条，而不是塞满一条。粒度错的契约比字段少更危险。

“字典里还没有我要引用的令牌，先写进去行不行？”

不行，这是三条硬要求里的语义硬要求。正确姿势：先把令牌注册进字典（试点用 draft 状态 + review_date），再来起草契约。字典永远可以晚于场景半步，但引用纪律不能破。

“边界写严了，下游抱怨阻断太多怎么办？”

先核对两件事：拦截分级用对了吗（该 WARN 的别 BLOCK）？约束可执行吗？都确认之后，记住那句取舍，标准恒定，消费侧不适靠修订规则细节吸收，不靠放松标准。治理的信用，恰恰建立在这种不舒服上。

“我评审通过就算规则生效了吗？”

不是。评审通过只走到”规则被正确翻译”，它还要被编译、被消费、被追踪。消费率长期为零的契约是沉睡规则，标准再严，没人消费等于没写。

结语

契约入库、编译跑通、四种产物分发的那个瞬间，规则就开始自己上班了，不靠记性，不靠群公告，不靠谁的自觉。

但”自己上班”有个前提：有人恒定执行及格线。起草时的每一组自问，评审时的每一条核查，都是在给这套自动运转的系统上发条。你守住的不是一份模板，是这套体系治理信用的来源。

规则流向的下一站，由下游角色接住：前端挂载产物、DesignOps运营追踪，他们的视角，在各自的角色专题里。而再往后，是这套体系在真实组织里的完整证明。

模板字段为冻结 v1.0.0。第一条契约评审通过的那天，值得记录，那是”规则自己上班”的第一天。

本文由 @魏雯 Akir 原创发布于人人都是产品经理。未经作者许可，禁止转载

题图来自Unsplash，基于CC0协议