为机器接口编写契约文档：用 DTO 目录和四个细节层级记录…

当需要为调用方记录任何机器调用或解析的接口（REST/RPC、消息队列、Webhook、CLI、文件格式）时，按四个细节层级和 DTO 目录写出穷尽、可核对的契约文档。

适用场景

解决思路

1. 先阅读序列化配置再写任何字段行：契约以配置后的序列化器实际发出和接受的内容为准，全局 trimmer、省略 null 的映射器或自定义日期格式都会在不动 DTO 的情况下改变契约。
2. 把文档拆成四个细节层级，每层各有归属，并把放错层级的细节移回其所属层级：索引层（有哪些端点/消息/命令，放在端点、消息、命令表中）、语义层（调用后发生什么，放在每个端点/消息/命令的正文中，写副作用、发布的事件、幂等性、重投递、退出行为、怪癖）、形状层（线上传什么，放在 DTO 目录中，每个 DTO 一张字段表）、示例层（长什么样，每个 DTO 至多一个示例）。
3. 猎杀跨层级的重复：端点章节重述其 DTO 字段、示例夹带字段表中没有的字段，都是缺陷。
4. 若已存在 OpenAPI 或 AsyncAPI 规范，或代码会生成规范，则字段表归该规范所有；markdown 只记录规范无法表达的内容（语义、副作用、顺序、省略与 null 的区别）并链接该规范；绝不在生成的规范旁手工维护字段表，第二个归属地必然漂移。
5. 在没有机器可读规范时建立 DTO 目录：每个 DTO 只定义一次，在所有地方引用。
6. 字段类型写线上类型而非语言类型，例如 `string (date, ISO 8601)`、`number (64-bit integer)`、`string (decimal)`；列中说明跨线传输的内容，完整到读者无需借助实现类型作代理；超出消费者原生数字类型范围或精度的 64 位整数属于线上信息，产生它的类型名不是。
7. 每个 DTO 写一行 Source，指明所属的类或 schema 文件，作为引用类文档允许的证据锚点。
8. Required 用三态：`yes`、`no` 或 `if <condition>` 并写明条件。
9. 在重要之处说明省略与 null 的区别，对用于替换式写入的 DTO 必须说明——省略的字段在结果中不存在；若服务器在省略时假定某值，则把该值写入 Default 列。
10. 枚举单独建表，列出取值及含义；嵌套对象链接到自己的目录条目，绝不内联复制第二份。
11. 约束用领域术语表述，如 “past date”、“1..100 chars”、“must reference an existing budget policy”，从代码实际执行的校验中读取。
12. 按模板组织文档：Conventions（只写一次，不逐端点重复：base path、auth、content type、错误信封、全局（反）序列化行为、幂等默认值）、Endpoints 表（Method/Path/Purpose/Request/Response/Errors）、每个端点的语义正文（只写语义，不列字段）、Messages 表（Direction/Destination/Payload/Reply/On error）、每条消息的语义正文（重投递、顺序、发布的事件、怪癖，并指出与同类传输的差异）、Commands 表（Command/Purpose/Arguments/Output）及每条命令的语义正文（副作用、幂等性、退出行为、怪癖）、DTOs 目录（每个 DTO 一张字段表：Field/Type/Required/Default/Constraints/Meaning，并说明省略与 null 的区别，至多一个示例）、Errors 表（Status/When/Body）。
13. 把不对称当作语义记录：在一种传输上发布事件而在另一种上什么都不发的变更、跳过同类端点都会执行的某一步的端点，都写在语义层。
14. 示例只作说明、绝不规范：每个 DTO 至多一个，明确标注，且不得包含字段表中没有的字段；字段表才是契约。
15. 错误只编目一次，即错误信封加状态表；端点只列出适用于自己的条目；命令失败按退出码以同样方式编目。
16. 让穷尽性可核对：端点数量和 DTO 数量像其他分母一样（核心真相规则），在遗留项目中将它们连同背后的命令和日期记录在覆盖台账中。

适用边界 · 注意事项

• 不要用于内部代码接口——代码本身即可说明。
• 不要用于配置参考——那属于核心 Reference 规则下的 `config-reference.md`。
• 不评判契约设计得好不好：本技能只记录已存在的契约。