让 Cursor 规则引用接口契约

把接口说明写进 Cursor rules，看起来能让 AI 少猜一点，却也多了一份需要手动维护的 API 文档。OpenAPI 改了，规则没改，AI 就可能照着旧字段、旧路径继续生成代码。

作者给出的结论是：让 OpenAPI 管接口事实，让 rules 管开发约定和查找入口，再从契约生成工具与 mock。对已经使用 OpenAPI、又在用 Cursor 写接口调用的团队，这个分工值得参考；但文章给的是工作流建议，没有实测数据证明收益。

为什么规则越具体，反而越容易带偏 AI

Cursor rules 适合记录相对稳定的约定：文件怎么命名、handler 放在哪里、什么算完成、优先使用哪些工具。问题出在把接口路径、请求字段和认证方式也抄进去。

这些细节已经存在于 OpenAPI 文档中。再写一份，就需要有人保证两边始终一致。作者指出，普通文字规则没有构建校验兜底：契约新增字段后，生成的客户端可能已经更新，规则却还描述旧结构。

文章用下面这段反例说明重复维护的问题：

// fragile: hand-maintained API copy inside rules, untracked by any build // .cursor/rules/api.mdc Always call POST /v1/charge (singular) with fields amount and currency. The auth header is X-Api-Key. // spec later moves to /v1/charges and uses Bearer auth; the rule is now // wrong, but nothing fails until the agent follows the stale instruction

要盯住的是路径从 /v1/charge 变为 /v1/charges，认证从 X-Api-Key 变为 Bearer。规则里仍然要求发送 amount、currency，并坚持旧路径和旧认证，但这个冲突未必会让构建失败。

作者把后果分成三类：

• 规则与契约对同一字段给出不同定义，AI 面临冲突指令。
• 示例保留旧 header 或路径，AI 直接复制过期用法。
• 新操作已经进入契约和工具，规则没有提到，AI 可能自己拼请求。

作者认为，AI 此时可能受提示顺序和描述具体程度影响，而非可靠地选出正确来源。这个判断没有附带对照实验，不能理解成 Cursor 在所有场景下都会如此。

让 AI 找契约，还要让契约变成可用工具

rules 应当告诉 AI 去哪里找接口定义，而不是再写一份接口定义。

按照作者的分工，路径、必需 header、请求体结构都归 OpenAPI；rules 只说明契约位置、开发约定，以及优先使用哪些生成工具。

MCP server 则负责暴露可调用的操作。可以把它理解成 AI 使用接口的工具入口：rules 说明工作方式，工具提供具体动作，两者各有职责。

这也解释了为什么仅写一句「请参考 OpenAPI」还不够。作者建议从契约生成 MCP tools 和 mock，让遵守契约成为最方便的操作路径，减少 AI 手写 fetch 的需要。再加入响应 schema 校验，检查返回内容是否符合约定，捕获违背契约的结果。

不过，「引用同一份契约」不等于「产物自动保持最新」。生成过程必须进入工作流。文章提出两个检查：

• 对 rules 做 lint，拒绝硬编码的接口路径和字段列表，防止接口副本重新混入。
• 把 OpenAPI 放进仓库，在 CI 中据此生成 MCP tools 和 mock，让工具跟随契约更新。

在这个安排下，接口变化主要触发重新生成工具，稳定的规则无需同步修改。若每次改接口都要改 rules，就该检查是不是把接口细节放错了地方。

原文提到 local-first OpenAPI studio 能帮助统一这些步骤，但没有给出具体配置、生成命令或 lint 实现。它说明了应当怎样分工，还不足以作为直接照抄的接入教程。

我的判断

我赞同把接口事实收敛到 OpenAPI。它减少的是重复维护点：与其要求开发者每次同时改契约和提示词，不如让规则只保留引用关系。

但收益有前提。首先，OpenAPI 自己必须及时更新。若真实服务已经变了，契约仍旧过期，从中生成的工具和 mock 只会一起过期。其次，生成产物需要可靠更新，AI 也得能找到并使用它们。文章没有提供这些环节的失败处理细节。

对比在 rules 中堆满请求示例，这套做法更适合接口持续变化、已有契约生成流程的团队。但文章没有给出错误率、维护时间或调用成功率的对照数据，因此目前只能把它视为有道理的工程经验。

生成 MCP server 也需要投入。如果团队已经有可靠的生成客户端，可以先完成「契约唯一、规则引用、产物更新」这几个步骤，再判断是否需要增加 MCP 工具入口。原文没有比较这两种路径的成本，不能据此认定 MCP 是所有团队的必选项。

还要区分校验范围：响应符合 schema，只能说明被检查的结构约束通过，不能证明权限、业务结果和整个调用流程都正确。

能拿来做什么

• 检查 .cursor/rules/api.mdc 等规则文件，把路径、认证 header 和请求字段列表移回 OpenAPI，规则中保留契约位置与工具使用约定。
• 给前端或 Node 项目的接口变更流程补上生成步骤，确认客户端、MCP tools 或 mock 中实际使用的产物会跟随契约更新。
• 为 AI 编程任务写清工具优先级，并在调用后增加响应 schema 校验，减少凭记忆拼请求的空间。
• 如果一次接口变更总要同步修改多份说明，先清点重复信息，再决定是否引入新的生成工具，避免继续扩大手工维护范围。