接口契约先行是一个面向 AI 编程智能体的软件开发设计原则,核心主张是先描述调用方契约,再写实现细节,避免实现完成后才补注释去解释机制。
用途与激活条件:当当前任务证据同时满足以下两点时应用:接口是公开的、跨越模块或所有权边界,或行为无法从既有类型与约定中直观看出;调用方必须理解至少一项有意义的保证、错误、副作用、顺序规则、生命周期约束或不变量才能正确使用。函数、类、组件、包入口、服务 API、事件、命令或数据交换都算接口;对既有契约做实质性变更同样会激活该原则。
主要能力与决策规则:原则要求在实体之前描述调用方契约,用该描述反推并改进设计,并在实现演进中维护不直观的保证。具体探测步骤包括:命名抽象及其职责,记录「谁拥有」以表明策略归属;依据既有声明说明可接受的输入与约束,先用散文描述行为,复用现有签名,仅在获得授权时才设计新的可调用形态或返回类型;区分既定保证、明确选择的授权设计决策与未知项,证据缺失不能推出命题或其反面;列出影响正确使用的错误、副作用、生命周期或顺序规则及不变量;据此写出契约草案,并展示未决问题而非猜测性签名或实现叙述。
设计警示与迭代:若契约难以解释,应视为设计警告,需区分可避免的实现泄漏与固有约束;隐藏调用方无需了解的机制,把相关策略留在有证据支持的所有者处;任何拆分或新包装必须降低总体负担,而不只是缩短描述。契约与实现应随编码和测试发现更好语义而共同修订,注释先行是可迭代的设计探测,而非冻结的前置规格。
记录与可发现性:签名只描述名称与静态输入输出形态,可能遗漏非正式保证;类型草图、测试名称或聊天记录可作起点,但不足以承载不直观行为。长期存在的接口应在声明附近或既有权威 schema/API 文档中保留简洁的规范描述,并引用而非重复该来源,使未来调用方无需重建实现或对话即可找到契约。必要的顺序、错误、安全、并发与生命周期约束即使难以表述也必须保留,不能为让接口显得简单而隐藏必需知识。
限制与反例:契约从名称、局部类型和约定中一望即知的私有小工具函数无需仪式化描述;生成接口应源自权威 schema 或生成器,仅当手写门面带来额外不直观行为时才应用探测;简洁描述不能替代强类型、运行时校验或通过真实调用方验证。
职责分工:本原则只负责实现前的调用方契约探测;接口负担、模块深度、接缝与替代方案分析归 codebase-design;跨模块、所有者、部署边界、兼容性或可逆性的重大选择归 architect;静态模型、运行时类型证据、泛型与编译器契约归 typescript,框架相关接口归对应框架所有;独立 API 文档任务与文档风格归 docs;当重设计超出获批任务范围时,先触发 principle-stop-on-plan-drift 停止并请求授权。
可观察结果:契约在实现之前以面向调用方的简洁形式存在,对未来调用方可发现,并随授权语义变更同步更新;最终要么在无需实现知识的情况下继续(抽象、输入、输出、失败、效果与不变量清晰),要么调整接口以减少调用方需知,要么因未决重大设计决策而停下。
资料还提供了若干示例:如 replaceDocument 的替换契约需说明版本冲突、权限拒绝、并发无提交顺序保证,以及编辑器与服务各自拥有的策略;缓存 API 需先厘清键范围、缺失值行为、过期保证、序列化错误、并发写与读取是否更新近期性;生成的客户端应绑定权威 schema,手写门面额外保证须在接口处保留;新事件 sink 只保留已确立的两项保证,排序、取消等未决语义应标为提案而非伪造。资料注明该原则改编自 Ousterhout 的斯坦福注释笔记、作者公开的第二版摘录第 12 章第 99–100 页及 2024–25 年与 Martin 的讨论,属于受限的工作流改编。