How to Prevent Breaking API Contracts with Cursor

1---
2description: Enforce backward-compatible GraphQL schema changes
3globs: "*.graphql,*.gql,*.resolver.ts,*.schema.ts"
4alwaysApply: true
5---
6
7# GraphQL API Contract Rules
8- NEVER remove existing fields from a type
9- NEVER change the return type of an existing field
10- NEVER rename existing queries, mutations, or subscriptions
11- NEVER make a previously optional argument required
12- ALWAYS add new fields instead of modifying existing ones
13- ALWAYS use @deprecated(reason: "...") before removing fields
14- New required arguments must have default values
15- New enum values are safe to add
16- Breaking changes require a new API version (v2)
17
18## Safe Changes (ALLOWED):
19- Adding new fields to existing types
20- Adding new queries, mutations, subscriptions
21- Adding new types, enums, unions
22- Adding optional arguments to existing fields
23- Deprecating fields with @deprecated
24
25## Breaking Changes (NEVER without versioning):
26- Removing any field, type, or operation
27- Changing a field's return type
28- Making optional arguments required
29- Removing enum values

1@graphql-compat.mdc @src/schema/schema.graphql
2
3Add a new 'analytics' section to the User type:
41. Add lastLoginAt: DateTime field
52. Add loginCount: Int field
63. Add a new UserAnalytics type with detailed metrics
74. Add a userAnalytics(userId: ID!): UserAnalytics query
8
9Do NOT modify or remove any existing fields on the User type.
10All changes must be additive only.

1@graphql-compat.mdc @src/schema/schema.graphql
2
3Deprecate these fields (do NOT remove them):
41. User.fullName -> deprecated in favor of User.displayName
52. Query.getUser -> deprecated in favor of Query.user
63. User.avatarUrl -> deprecated in favor of User.avatar.url
7
8Add @deprecated directives with clear reasons and migration paths.
9Add the new replacement fields/queries alongside the deprecated ones.
10Both old and new must work simultaneously.

1@graphql-compat.mdc @src/schema/schema.graphql @src/schema/schema-proposed.graphql
2
3Compare the existing schema with the proposed changes.
4Identify any breaking changes:
51. Fields removed from any type
62. Return types changed on existing fields
73. Required arguments added without defaults
84. Enum values removed
95. Types renamed or removed
10
11For each breaking change found, explain the impact on existing
12clients and suggest a backward-compatible alternative.

1@graphql-compat.mdc @src/schema/schema.graphql @src/resolvers/user.resolver.ts
2
3Update the User resolver to support both deprecated and new fields:
41. fullName (deprecated) — still returns firstName + lastName
52. displayName (new) — returns the preferred display name
63. avatarUrl (deprecated) — still returns the URL string
74. avatar (new) — returns { url, width, height, format }
8
9Both old and new resolvers must work simultaneously.
10Share logic between deprecated and new resolvers to avoid duplication.