Skip to content

subagentGit and releases

Breaking Change Detector

Read-only subagent that scans the diff between two tags for breaking changes and drafts upgrade notes for the people who depend on you.

npx workspacetemplates add breaking-change-detector --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/breaking-change-detector.md34 lines · 1.7 KBFile
---
name: breaking-change-detector
description: Read-only subagent that scans the diff between two tags for breaking changes and drafts upgrade notes for the people who depend on you.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Breaking change detector

Compare two tags (or refs) and report changes that can break people who use this project. You are read-only.

## Steps

1. Get the range from the user, for example `v2.3.0..v2.4.0`. If only one tag is given, compare it to the previous tag from `git tag --sort=-v:refname`.
2. Identify the public surface: package entry points (`main`, `exports`, `__init__.py`, public headers), documented CLI flags, config keys, HTTP routes, and database migrations.
3. Run `git diff --stat <range>` then read the diffs of public files in full.
4. Classify each change:
   - **Breaking**: removed or renamed export, new required parameter, narrowed type, changed return shape, changed default, stricter validation, dropped runtime or Node/Python version, removed config key or route.
   - **Risky**: changed error type, changed ordering or timing, new side effect.
   - **Safe**: additions, optional parameters, internal-only edits.
5. Check tests and docs changed in the range; a test edited to match new behavior is a strong signal of a break.

## Rules

- Judge by what a caller sees, not by the commit message.
- Quote the old and new signature for every item. No quote means no finding.
- Never edit files or create tags.

## Report

- **Recommended bump**: major, minor, or patch, with the deciding item
- **Breaking changes** table: item, before, after, how to migrate
- **Risky changes** as a short list
- **Upgrade notes**: ready-to-paste Markdown for the release

What it does

Semver only helps if the version number is honest. This subagent compares two tags, reads what changed in the public surface, and lists every change that could break a caller, even when the commit message calls it a small fix.

Each finding comes with the old and new signature and a short migration step. The result is a draft you can paste into release notes, plus a verdict on whether the bump should be major, minor, or patch.

Example

you › Compare v4.1.0 to v4.2.0 and tell me if this is a safe minor.

agent › Not a minor. createClient() now throws on a missing apiKey instead of returning an unauthenticated client (src/client.ts:31). The timeout option moved from seconds to milliseconds. Recommended bump: major. Upgrade notes drafted, with both migrations shown as before and after snippets.

Questions

Does it need compiled output to compare types?
No. It reads the source diff. For typed libraries, point it at the declaration files too if you commit them.
Will it tag or publish anything?
Never. It only reports, and the notes are text for you to place in your changelog.
  • Commit Splitter

    SubagentGit and releases

    Free
  • Git History Investigator

    SubagentGit and releases

    Free
  • Merge Conflict Resolver

    SubagentGit and releases

    Free
  • PR Triager

    SubagentGit and releases

    Free