Breaking Change Detection Prompt for Interface Contracts

This prompt is built for platform and backend engineering teams that need to compare two versions of an API contract—OpenAPI, gRPC proto, GraphQL schema, or JSON Schema—and produce a categorized, actionable list of changes. The core job-to-be-done is preventing silent breaking changes from reaching production consumers. Use it during pull request review when a contract file changes, as a gate in your CI pipeline before merging a spec update, or when generating a migration guide for external developers. The ideal user is an API designer, service owner, or release engineer who has access to the old and new contract snapshots and needs a structured diff analysis faster than manual line-by-line review.

The prompt assumes you have either a structured diff (unified diff, git diff) or two complete contract snapshots. It classifies each change as breaking, additive, or compatible, and attaches a consumer impact analysis that explains what will fail and for whom. Breaking changes include removed fields, changed types, narrowed validation constraints, removed endpoints, and altered authentication requirements. Additive changes include new optional fields, new endpoints, and relaxed constraints. Compatible changes include documentation updates, description clarifications, and reordering of fields. The prompt is not a replacement for integration tests, consumer-driven contract testing, or runtime compatibility gates—it is a design-time safety net that catches obvious breaks before they reach downstream systems.

Do not use this prompt when you lack a complete before-and-after contract snapshot, when the contract is defined only in prose or tribal knowledge, or when the change involves runtime behavior that isn't expressed in the contract (e.g., rate limit changes, latency SLO shifts, or backend logic modifications). It also won't detect semantic breaks where the contract is unchanged but the implementation behavior has changed. For those cases, pair this prompt with integration tests and consumer-driven contract verification. If your API uses multiple contract formats simultaneously (e.g., gRPC proto plus a JSON Schema gateway), run the prompt separately for each format and cross-reference the results.

The prompt below is designed to be dropped into your AI harness with minimal adaptation. It accepts two versions of an interface contract—typically OpenAPI specs, gRPC protobufs, or GraphQL schemas—and a set of classification rules. The model's job is to produce a structured diff report that separates breaking changes from additive and compatible changes, with consumer impact analysis for each finding. Replace every square-bracket placeholder with your actual contract versions, classification rules, and output schema before use.

textCopy
You are an API contract reviewer specialized in detecting breaking changes between two versions of an interface contract.

## INPUT
[CONTRACT_VERSION_A]
[CONTRACT_VERSION_B]

## CLASSIFICATION RULES
[CLASSIFICATION_RULES]

## CONSTRAINTS
- Classify every detected change as BREAKING, ADDITIVE, or COMPATIBLE.
- For each BREAKING change, explain the consumer impact and which existing clients would fail.
- Do not flag cosmetic changes (whitespace, comment reordering, description rewording) unless they alter generated code or runtime behavior.
- If a change is ambiguous, mark it as REQUIRES_HUMAN_REVIEW and explain why.
- Ignore changes to [IGNORE_PATHS_OR_FIELDS] unless they affect contract semantics.

## OUTPUT SCHEMA
Return a single JSON object with this structure:
{
  "summary": {
    "breaking_count": <int>,
    "additive_count": <int>,
    "compatible_count": <int>,
    "requires_review_count": <int>
  },
  "changes": [
    {
      "id": "<string>",
      "location": "<path or field reference>",
      "type": "BREAKING | ADDITIVE | COMPATIBLE | REQUIRES_HUMAN_REVIEW",
      "description": "<what changed>",
      "consumer_impact": "<who breaks and how, or null for non-breaking>",
      "confidence": "HIGH | MEDIUM | LOW"
    }
  ]
}

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Analyze the two contract versions and return only the JSON object.

Adapt this template by filling in the placeholders with concrete values. [CONTRACT_VERSION_A] and [CONTRACT_VERSION_B] should contain the full text of your old and new contract specifications. [CLASSIFICATION_RULES] is where you encode your team's specific definition of breaking versus non-breaking changes—for example, whether adding a required field is breaking, or whether enum value removal counts. [IGNORE_PATHS_OR_FIELDS] lets you suppress noise from known internal-only fields or deprecated paths. [FEW_SHOT_EXAMPLES] should include 2–4 annotated examples of changes with correct classifications to anchor the model's behavior. [RISK_LEVEL] can be set to HIGH, MEDIUM, or LOW to adjust the model's conservatism—at HIGH, the model should err toward flagging ambiguous changes as REQUIRES_HUMAN_REVIEW.

Before wiring this into a production pipeline, validate the output against your expected schema. Common failure modes include the model collapsing additive and compatible changes into a single category, missing changes in deeply nested schema components, or producing consumer impact descriptions that are too vague to act on. Run this prompt against a golden dataset of known contract diffs with labeled breaking changes and measure precision and recall before trusting it in a CI gate. For high-risk APIs where a missed breaking change could cause an outage, always route REQUIRES_HUMAN_REVIEW and LOW-confidence findings to a human reviewer before merging.

The breaking change detection prompt is designed to operate as a gate in a CI/CD pipeline, triggered on pull requests that modify API specification files (OpenAPI, gRPC protobufs, GraphQL schemas, or custom contract formats). The harness should extract the base and target contract versions, compute a structural diff, and pass both the diff and the full contracts to the prompt. Do not rely on the model to compute the diff itself—pre-compute it using a deterministic tool (e.g., openapi-diff, buf breaking, or a custom JSON Schema differ) and include it as the [DIFF] input. This ensures the model focuses on classification and impact analysis rather than mechanical comparison, which reduces hallucination risk and token waste.

The implementation should wrap the LLM call in a validation layer that parses the structured output against the expected [OUTPUT_SCHEMA]. Each detected change must include a change_type field constrained to the enum ['breaking', 'additive', 'compatible', 'deprecation', 'unknown']. If the model output fails schema validation, retry once with the validation error appended to the prompt as a correction hint. If the second attempt also fails, fail the pipeline step and flag for human review. For high-risk APIs (auth, payments, data deletion), configure the harness to require explicit human approval on any change classified as breaking or unknown before the pipeline can proceed. Log every run with the contract versions, diff, model response, validation result, and reviewer decision to an audit store for governance traceability.

Model choice matters here. Use a model with strong structured output support and a large context window if your API specs are verbose. For OpenAPI specs over 10,000 lines, truncate to the changed paths and their referenced schemas rather than passing the entire spec. Implement a false-positive suppression registry: maintain a JSON file of known false positives (e.g., reordering of enum values that are explicitly documented as unordered) and filter them from the diff before passing to the prompt. After deployment, monitor the ratio of human-overridden classifications to total classifications. If the override rate exceeds 15%, review the prompt's classification rules and the false-positive registry for gaps. Do not use this prompt as the sole gate for regulatory compliance; always pair it with a deterministic contract compatibility check and a human review step for regulated surfaces.