Detect Breaking API Changes Prompt: Diff a Surface, Get the Semver Bump

You changed a function signature, added two methods, and renamed a constant. Is that a minor release or a major one? Get it wrong and either you've shipped a breaking change as a minor, or you've scared every consumer into a migration they didn't need. A detect breaking API changes prompt diffs the old surface against the new one and tells you: here's what broke, here's the semver bump, here's the note your consumers need.

The existing tooling is language-locked. .NET has analyzers, some ecosystems have surface-diffing binaries, and all of them need a build and only work for one language. For a polyglot repo, or a quick check before you publish, none of that helps. So the bump gets decided by gut feeling, which is how a "patch" ends up removing a public method.

A prompt fills the gap because it reasons about the declarations, not a compiled artifact. Two API surfaces in, a classified diff and the correct semver bump out, in any language.

Why semver gets decided wrong

Semver is simple in theory and slippery in practice. The rule is "the most severe change wins," but a real diff mixes ten safe additions with one signature change, and the additions make it feel minor. They don't. One breaking change in a sea of safe ones is still a major release. The cognitive trap is averaging the changes instead of taking the maximum.

The stance worth holding. Underbumping is worse than overbumping, every time. A consumer who updates to your "minor" and finds their build broken loses trust in your versioning permanently. An over-cautious major they didn't strictly need costs them a glance at a changelog. When the prompt is unsure between two bumps, it should pick the higher one. Conservative semver is the polite default.

What a detect breaking API changes prompt does

A detect breaking API changes prompt is a surface differ that reads two API versions and returns a classified change list, the correct semver bump, and a consumer migration note. It works without a build.

Use it to:

• Diff the public surface across two versions: exported functions, types, signatures, constants
• Classify every change as breaking, non-breaking, or deprecated
• Add a consumer-impact statement for each change
• Recommend the correct semver bump, justified by the diff
• Generate a migration note in the format consumers need to update
• Catch the breaking change buried among safe additions

The "most severe change wins" logic is what people get wrong by hand.

Anatomy of the prompt

Variables
  {{old_surface}}      → the previous public API
  {{new_surface}}      → the new public API
  {{language}}         → for declaration syntax
  {{current_version}}  → to compute the next version

Prompt
  Role: you are an API breaking-change detector.
  Task: diff {{old_surface}} against {{new_surface}}.
  Rules:
    - Classify each change: breaking | non-breaking | deprecated.
    - The semver bump is the most severe change, not the average.
    - When unsure between two bumps, pick the higher.

Output contract
  Return: change table + semver bump + migration note.

1. Capture both surfaces

Put the old and new public declarations in {{old_surface}} and {{new_surface}}. Just the surface, exports and signatures, not the implementation.

2. Name the language

{{language}} tells the prompt how to read declarations. A Go interface and a TypeScript type have different breaking rules; the prompt needs to know which.

3. Read the bump and its justification

The output recommends a bump with a reason tied to a specific change. If the justification points at a removed export, that's your major, no matter how many additions surround it.

4. Ship the migration note

For breaking bumps, the prompt writes the consumer-facing note. That's what goes in the release so your users know exactly what to change.

Prompt-craft patterns for surface diffing

Pass surfaces, not implementations. The public API is what consumers depend on. Pasting full implementations buries the signal and tempts the model to flag internal refactors that consumers never see. Surface in, surface reasoning out.

Make "most severe wins" an explicit rule. Models, like people, average. Without the rule, a diff with one break and nine additions sometimes gets called minor. State that the bump equals the worst change.

Force a migration note for every breaking change. A breaking diff with no migration note is half a job. The note is what makes the major release usable instead of a wall the consumer hits.

Prompt vs language-specific analyzer

A purpose-built analyzer is precise. It compiles both versions and computes the surface diff exactly, with no judgment involved. The catch is it's locked to one language and needs a build, which rules it out for a polyglot repo or a quick pre-publish check.

The sensible pattern is to use both where you can: let the prompt draft the classification and the migration note in seconds, then back the critical packages with the analyzer in CI for the exact diff. One caveat about the prompt path. It reasons rather than compiles, so for anything consumers truly depend on, pair the bump with a consumer-side test rather than trusting the surface read alone. Pin the model version once the classifications look right. A detector that drifted toward calling breaking changes "non-breaking" after an update is the worst kind of regression, because it ships an underbump that erodes trust in your versioning before anyone notices the pattern.

Variables you'll set

Getting started

1. Copy the structure into your model of choice.
2. Put the old and new public declarations in {{old_surface}} and {{new_surface}}.
3. Set {{language}} so the prompt reads declarations correctly.
4. Run it and read the semver bump with its justification.
5. Treat any ambiguous change as breaking and bump higher.
6. Ship the generated migration note in your release.

To diff a surface and publish the migration note with the classifier and publisher steps already wired, the Breaking Change Detection Harness Agent Pack runs the full flow.

Breaking-change detection is the publish-side bookend to the upgrade side. The Dependency Upgrade Harness Agent Pack handles the consumer's view, planning the bumps your breaking changes force on them. Before you cut the release, the monorepo impact analysis prompt maps which internal packages the surface change touches. For staged moves across a framework, see the framework migration prompt. New to buying packs? Read how to choose a reusable AI prompt pack.