用途与定位
YAML Jazz 是 MOOLLM 中处理结构化数据的一种约定方式，资料将其描述为「YAML 是乐谱。LLM 是爵士乐手。注释是灵魂。」它同时是 MOOLLM schemapedia 中的一个 schema 插件：mechanism id 为 yaml-jazz，family 为 notation，profile 为 skills/schema/schemas/mechanisms/yaml-jazz/MECHANISM.yml。资料明确说明它不跟 JSON Schema 竞争，而是在同一棵 YAML 树上叠加人工编写的含义（注释、视角）。
主要理念
资料列出若干条核心原则：
- 注释很重要：注释是给 LLM 读的指令、约束和上下文，LLM 会读取并据此行动。示例中包括
# CRITICAL: Do not modify without user approval、# TODO: migrate to new format after v2 launch这类注释。 - 结构即语义：缩进、顺序、分组都承载含义。例如用列表位置表示优先级（first = most important）。
- 在约束内即兴：面对不完整数据时，LLM 可以推断合理默认值，并标注不确定性（如
# default, unconfirmed）。 - 模式是建议：模式是起点而非牢笼。
面向注释编程（COP）
资料提出 Comment Oriented Programming（COP）概念：注释是与解析后的值树并列的一等表面，承载实例特定的代码与数据、需要保留的约束、树变化时应用的转换，以及过程性钩子，并随文件一起移动。YAML Jazz 是让 COP 在 YAML 源上变得明确的 MOOLLM 约定。资料指出仅用于交换的产物（如 JSON）没有 COP 通道，注释无法单独通过它们往返。
从 YAML 规范到领域方言
资料区分了几层：
- 规范层：YAML 由 YAML 语言规范定义（1.1 与 1.2 均在现实中存在）。解析器在树上达成一致；许多解析器在加载为对象时会丢弃注释。YAML Jazz 把源文件视为人类与 LLM 的权威：保留文本、保留
#行，并在机器必须改写文件时优先选择能往返保留注释的工具。 - 工具层：Kubernetes、Compose、GitHub Actions、MOOLLM skills 等，键与形状由产品固定，Jazz 是在这个盒子里做注释的方式。
- 项目层：命名、必需键、
*.schema.yml钩子，在注释中记录某个值为何存在。
资料提到团队间的差异（引号风格、折叠标量、显式 null）遵循 Postel 原则：读取时宽松接受，写入时保持一致。
注释形式
资料区分两种一等语义、跨度不同的注释：
- 整行
#（包括连续的多行#块）：用于理由、叙述、警告、历史、完整示例、多句说明。 - 行尾
#：字段局部注解，用于单位、注意事项、意图、快速护栏。
资料指出只看解析树的机器会错过两者，而阅读文件的 LLM 与人类不会。当注释针对整棵子树时使用块式；当评论绑定单个键时使用行尾式。
以示例作文档
资料提出 YAML Jazz 支持「以示例作文档」，类似 programming by example，实例本身就是课程。单个文件可以展示：合法形状及其背后的故事（为何用这些键、删掉会怎样失败）、注释中的反例或「不要」的行、以及变更字段旁的 before/after 或迁移说明。数据保持可执行或可移植，注释承载讲解。资料同时说明，在需要规范性 schema 时，这不能替代外部规范，应配合 schema（schemapedia）使用；但对 MOOLLM 与人机协作而言，带注释的 YAML 往往就是权威解释。
平行副本与文档视角
相同的 YAML 结构（相同键与值）可以出现在多个文件或多个受追踪版本中，每个副本携带不同的注释集，各自优化一个视角，例如：校验与转换（类型、强制转换、不变量、往返会破坏什么）、使用与度量（延迟、成本、SLO、谁调用谁）、历史（何时变更、谁决定、工单或提交指针）、意图（产品目标、取舍、为何不选显而易见的替代方案）。
资料指出没有哪个注释块需要同时承载所有视角，那样常带来噪音与合并痛苦。按文件或文档分支拆分能让每条阅读路径更短。实践中可行的约定包括：兄弟文件（如 deploy.intent.yml / deploy.validation.yml，同树不同注释，若漂移有风险则用测试或代码生成同步值）、顶层段落横幅（如 # lens: metrics），以及把历史交给 git blame，除非审计需要内联出处。资料提到可参考 examples/lens-intent.yml 与 examples/lens-validation.yml 构成的最小配对。
爵士隐喻
资料以爵士乐作比：乐谱对应 schema/模板，和弦进行对应必需字段，即兴对应 LLM 解释，灵魂对应注释，乐团对应多智能体，标准曲对应协议约定。「Start with jazz, end with standards.」资料还玩了一个双关：jazz standards 是每个乐手都熟悉的经典曲目，而软件标准是模式稳定后固化下来的可复用结构。资料并提到「YAML」听上去像爵士拟声，呼应 The Edsels 1957 年的 doo-wop 经典「Rama Lama Ding Dong」。
适用场景与何时使用
资料列出：配置文件（注释解释为什么而非仅仅是什么）、状态文件（注解追踪历史与意图）、数据交换（结构化到足以解析，宽松到足以扩展）、人机协作（两者都能读写）。
反模式
资料列出的反模式包括：僵化的 schema 强制、剥离注释、只给机器看的 YAML（人类读不了就用 JSON）、过度规格化、把 JSON 用于工具调用、隐藏含义的编译/转换步骤。
经验证据：熵坍缩
资料引述 Sunil Kumar（Groundlight AI）在 2025 年 4 月的发现：把模型的工具调用接口从 JSON 换成 YAML，显著改善了生成熵的稳定性，并带来更强性能；强制小模型生成结构正确的 JSON 会严重限制其搜索与推理能力。资料列出 JSON 对 LLM 的不利之处（严格括号匹配、强制逗号、引号转义、不允许注释、刚性语法导致熵坍缩）与 YAML 的有利之处（语法开销小、缩进即结构、允许注释、格式灵活、人类可读且与训练数据重叠），并给出简化 schema 示例：
<tool>
name: <tool name>
arg1: value1
arg2: value2
</tool>
资料注明该示例无间距要求、无括号匹配，只有语义结构，并引述「Anything to reduce syntax is a win!」。
「源即目标」原则
资料引用 Anil Dash 2025 年 1 月的文章，把同一原则应用到数据：XML 的源与目标（解析后 DOM）之间存在中等差距，JSON 有小差距，而 YAML Jazz 的源与目标（被理解的 .yml）没有差距——你写的 YAML 就是 LLM 读的 YAML，注释被保留，结构承载意义。资料还引用 Adele Goldberg 关于文档是与系统共同设计的说法，并举例说明注释本身就是规格，LLM 会读取并据此行动。
配套技能与协议符号
资料列出姐妹技能：schema/、markdown/、plain-text/、format-design/、postel/、soul-chat/；内核参考 kernel/constitution-core.md 第 3 节「YAML Jazz Principle」；协议符号为 YAML-JAZZ，在语义性地（而非仅语法性地）解释 YAML 时调用，详见 PROTOCOLS.yml。