让 AI 编程交付可验证：契约、工具与 CI

AI 编程代理最容易栽在两件事上：不知道真实 API，却照样补出字段；代码在本地跑绿，就宣布任务完成。作者给出的解法是，把接口契约通过工具交给代理，再用能在 CI 中执行的业务验证来定义「完成」。

这篇指南值得读的地方，是把关注点从提示词转向工程约束。不过，原文更像一组实践文章的入口，没有展开实验过程，也没有提供对照数据。读的时候，要把合理的工程原则和产品宣传分开看。

为什么接口契约比粘贴文档更可靠

作者认为，给代理一条 curl 命令或一大段文档，仍可能让它缺少关键上下文。示例只覆盖某次请求，文档摘录也未必包含完整字段、错误类型和操作限制。遇到缺口，代理可能按已有知识补出一个看似合理的接口。

他的建议是以 OpenAPI 为契约，通过 MCP server 提供代理可调用的工具。大白话解释，就是让代理有渠道查询接口定义、调用已声明的操作，而不是靠聊天记录猜参数。

但 MCP 只是连接方式。工具暴露的契约是否准确，才决定代理拿到的上下文是否可信。 原文没有说明契约如何同步、工具如何生成，也没有证明接上 MCP 就能消除字段幻觉。信息不足时承认未知，仍然是必要行为。

接口本身也要方便代理使用：操作能被发现，错误有明确类型，标识符保持稳定。需要返回结构化数据时，作者建议用 JSON Schema 约束输出，并结合 tool calling，而不是再从自由文本里提取字段。前者把格式要求变成可检查的规则，后者仍要处理模型自由发挥的结果。

为什么测试通过，还不能算完成

作者把代理说出的「done」视为一项待验证的声明。单元测试通过，不代表应用启动过；构建成功，不代表重构后的业务路径正确；API 返回 200，也不代表业务场景完成。

例如，前端发起更新请求后，除了确认响应成功，还应检查数据是否真的改变、页面是否展示了预期状态。这是对作者原则的具体应用，原文没有给出这样的完整案例。

他提出的最低要求有三项：在 CI 中运行相关测试，覆盖真实业务流程，并确认没有修复时验证会失败。最后一项尤其有用：如果改动前后都绿，就需要检查测试是否真正经过了出问题的路径。

验收标准应当是一条能运行、能失败的验证命令。 不过，命令只是入口，决定证明力度的是它实际检查了什么。作者批评「绿色 CI」，针对的也是没有覆盖关键行为的检查，不能据此否定 CI 的价值。

审查代理改动时，原文列出的反模式也很具体：用 as any 消除类型错误，新增的类型大部分仍是 any，用宽泛的 try-catch 隐藏失败，重命名漏掉字符串引用。还有两类容易被忽略的问题：交接只保留决定、丢掉理由，以及任务结束后留下无人管理的开发服务器。

我的判断

这套思路说得对：上下文解决「依据什么实现」，验证解决「凭什么相信实现完成」。两者缺一，代理都可能产出表面完整、实际错误的代码。

但原文没有提供 MCP 与粘贴文档的效果对照，也没有展示那组「真实案例」的复现过程。因此，它更适合作为经验清单，不能当作某种架构已经得到量化验证的证据。

对接口少、任务短的项目，直接提供准确的 OpenAPI 文件，也可能足够。团队频繁切换代理或 IDE、需要重复接入同一套 API 时，把契约和工具统一维护的收益才更明显。与此同时，「真实业务流程」如何在 CI 中准备数据、处理外部依赖，原文没说清，落地仍需团队补齐。

文末介绍的 Powerduck，被定位为 local-first、OpenAPI-first 的工作空间，覆盖调试、测试、mock 和代理工具。这是作者推荐的产品路径，原文没有给出它优于其他方案的比较依据。

能拿来做什么

• 给前端或 Node 接口任务附上准确的 OpenAPI 契约；需要反复查询和调用时，再通过 MCP 提供工具，并明确要求缺失字段先核实。
• 在任务开始前写明验收命令和业务结果，例如请求成功后还要检查数据变化与页面状态，并把验证接入 CI。
• 审查 AI 改动时，重点追查新增的 any、宽泛 try-catch 和字符串引用；交接记录也要保留关键决定的理由。
• 让代理自主探索和实现，把修改契约、涉及资金与认证的决定留给人工；验证越快、覆盖越充分，再逐步扩大自主范围。