代码契约
一种开放格式,用于将 @cc 指令与代码放在一起,以结构化方式表达假设与需求 — 为人类和智能体提供规范、关注点与验证,并由 cc-check CLI 强制执行。
概述
代码契约是一种简单的开放格式,用于在代码旁以结构化方式表达假设与需求,以支持更快、更好的智能体驱动软件开发。契约以文档注释中的 @cc 指令形式编写,通常附加在函数、类或方法声明上:
/**
* @cc [owner:spolu,label:product] balance-pre-and-fail
* `from.balance` is expected to be greater than or equal to `invoice.amount`, fails with
* `InsufficientBalanceError` otherwise.
*/
export async function payInvoice(invoice: Invoice, from: Account): Promise<PaidInvoice> {
...
}
为什么使用代码契约
代码契约由人类和智能体共同编写和使用,用于对代码进行推理。它们有三个用途:
- 规范 — 与独立的产品或系统规范文件不同(后者会与代码脱节且难以发现),契约嵌入在本地。人类无需检查实现细节即可推理行为;智能体使用它们来指导实现,并向人类和未来的智能体呈现假设。
- 关注点 — 它们以结构化方式呈现假设和不变量,减少推理代码所需的周期,从而释放作为瓶颈资源的人类注意力。
- 验证 — 其结构和粒度使工具能够强制执行合规性并随时间推移简化维护,为智能体提供提升性能的验证信号。
工具
cc-check 命令行界面(npm install --global @spolu/cc-check)提供:
cc-check format [file-like]— 报告受支持的源文件或@cc文件中格式错误的CONTRACTS语法和重复的契约 ID。未提供路径时,递归检查当前目录中的每个受支持文件。它从不重写文件,也不评估契约文本或实现合规性。cc-check list <file-like|location-like>— 列出附加到整个源文件中各声明的契约,或适用于包含某个源位置的声明及其祖先声明的契约。默认包含来自祖先CONTRACTS文件的目录级契约;传入--no-global可排除它们。
规范与语法
@cc 指令从任何受支持源语言的文档注释中提取;注释分隔符和装饰(/**、*/、//、///、Python 文档字符串三引号、前导 *)在解析前被移除。每个指令定义一个契约,通常与函数、类或方法定义放在一起。
未附加到声明的契约位于名为 CONTRACTS 的文件中,适用于该文件所在目录及其子目录中的所有代码 — 通常是目录级规则,例如架构边界、依赖约束或安全实践:
@cc [owner:spolu,label:architecture] database-access-thru-resources
Database accesses must happen exclusively through `Resource`-like interfaces.
@cc [owner:spolu,label:security] no-sensitive-data-logging
Credentials, tokens, secrets and user data must not be logged.
指令由 @cc 后跟可选的方括号元数据和契约 ID 组成:@cc [owner:spolu,label:product] balance-post。元数据键可扩展;owner、notify 和 label 是众所周知的键。一个契约可以有多个所有者、通知接收者和标签;分号在一个属性内分隔多个值([owner:spolu;tdraier,label:product]),而不是重复键,不过重复键仍然有效。
正文非空,延伸至文档注释末尾、@cc 文件中的下一个 CONTRACTS 指令或该文件末尾。它可以跨任意多行;核心格式不规定词汇、句式、情态或需求记法,但通常期望使用 Markdown。
契约 ID 在其附加的声明内唯一且稳定(同一 ID 可以在不同声明上重复出现);在 CONTRACTS 文件中,ID 在该文件内以及所有父级 CONTRACTS 文件中唯一且稳定。一个文档注释恰好携带一个 @cc 指令,但多个连续的契约注释可以附加到同一个声明上。
Owner 与 Notify 语义
owner 列出在现有契约被更改或移除时要通知的 GitHub 用户名;引入契约不会通知所有者。notify 列出在每次发现该契约违规时要通知的 GitHub 用户名。除非同时列在 notify 中,否则所有者不会自动收到违规通知。审查智能体会拆分分号列表、合并重复键并对用户名去重。