Quick answer: Cursor rules and an OpenAPI contract are two sources of truth that will drift the moment they are edited separately, and the agent ends up following whichever is more specific in the moment. The durable arrangement is to keep the OpenAPI document as the authoritative source and let rules point at it — encoding conventions and where to look, rather than duplicating endpoint details that change. Rules that restate the API by hand become stale on the first spec change; rules that reference the contract stay correct because the contract is what the generated tools and mocks already follow.
Cursor rules are excellent at durable conventions: how to name files, where handlers live, what "done" means, and which tools to prefer. They are the wrong place to maintain a copy of the API's paths and fields. When a team writes endpoint details into rules, they create a second, manually maintained description that no build validates. The spec adds a field, the generated client picks it up, but the rule still says the old shape, and the agent receives conflicting instructions. Naming the two artifacts' responsibilities is the fix.
What goes wrong when they duplicate
The failure shows up in three recognizable ways, all rooted in the same duplication.
- Contradiction. The rule names a field one way while the spec defines it another; the agent's choice depends on prompt ordering, not on which is correct.
- Stale examples. A rule's sample request keeps an old header or path after the contract changed, and the agent copies the stale example.
- Silent missing coverage. A new operation exists in the spec and tools but is never mentioned, so the agent does not know it is available and hand-writes a request.
// 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
Let the contract be the source of truth
Restructure the rules so they describe conventions and navigation, never a duplicated API. Endpoint details, required headers, and body shapes live in the OpenAPI document; the rule tells the agent to read the spec and use the generated tools. That keeps a single source that the build can validate.
Because the rule now references the contract rather than copying it, a spec change needs no rule edit. The generated MCP server and mocks already reflect the new shape, and the agent is instructed to use them.
Responsibilities at a glance
| Concern | Cursor rules | OpenAPI contract |
|---|---|---|
| Paths and methods | Do not duplicate | Authoritative |
| Headers and auth scheme | Point to spec | Authoritative |
| Request/response fields | Do not duplicate | Authoritative |
| File layout and naming | Authoritative | Not concerned |
| Definition of done | Authoritative | Not concerned |
| Tool preference | Authoritative | Not concerned |
Keep them aligned through the workflow
Two practical checks make this hold. First, lint the rules to reject hardcoded endpoint paths and field lists, so a duplicated API cannot creep back in. Second, keep the spec in the repo and generate the MCP tools and mocks from it in CI, so the thing the agent is told to use is always current. When the contract changes, regenerating the tools is the only required step; rules describing conventions remain untouched. This is where a local-first OpenAPI studio helps: the spec, generated tools, and contract verification all derive from one file rather than a pile of hand-synced notes.
Frequently asked questions
Can't I just put the whole API description into rules?
It works briefly and then drifts, because no build validates the rule against the real API. Rules are prose the agent reads; the contract is executable and generates the tools. Keep endpoint detail in the contract and let rules reference it.
What if the agent still ignores the spec and guesses?
Make the generated MCP tools the preferred path and remove the need to hand-write fetch calls, so using the contract is the easiest action. Pair that with a verification step that checks the response against the schema; a guessed call that violates the contract is then caught.
How often do rules need updating?
Rarely, because they encode durable conventions rather than changing endpoints. If you find yourself editing rules on every API change, that is a signal that endpoint detail has leaked into them and should move back to the contract.
Does this replace the MCP server?
No. Rules tell the agent how to work; the MCP server exposes the actual operations. The reliable setup uses both: rules for conventions and tool preference, the generated MCP server for concrete calls derived from the contract.
This is part of the Powerduck vs Cursor comparison — start there for the full picture of how an API contract tool works alongside an AI editor.
Top comments (0)