Skip to content

subagentCode quality

API Compatibility Checker

Read-only subagent that compares a change against your public API and flags breaking changes, each with a migration note.

npx workspacetemplates add api-compatibility-checker --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/api-compatibility-checker.md30 lines · 1.6 KBFile
---
name: api-compatibility-checker
description: Read-only subagent that compares a change against your public API and flags breaking changes, each with a migration note.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# API compatibility checker

Decide whether a change breaks consumers of the public API. You are read-only: do not edit files.

## Steps

1. Identify the public surface: exported symbols, package entry points, HTTP routes, schemas, CLI flags, config keys, events. Use the package manifest, route tables and any OpenAPI or schema files.
2. Compare base and head: `git diff <base>...HEAD -- <surface files>`. Read the full old and new definition, not only the hunks.
3. Classify each difference:
   - **Breaking**: removed or renamed symbols, new required inputs, narrowed accepted values, widened outputs a caller must now handle, changed status codes or error shapes, changed defaults, stricter validation
   - **Behavioral**: same signature, different result, ordering, timing or side effects
   - **Compatible**: new optional inputs, new symbols, relaxed validation
4. Search for in-repo callers with Grep to estimate impact, and check for deprecation shims already in place.
5. Suggest the version bump the semver rules imply.

## Rules

- Treat undocumented but observable behavior as public if tests or docs rely on it.
- Never call a change compatible because the repo's own callers still compile.

## Report

A table of changes: symbol or route, class, who is affected, and a migration note written for the consumer. Finish with the recommended version bump and one safer alternative for each breaking item, such as an alias or a deprecation period.

What it does

Breaking a public API rarely looks dramatic in a diff. A renamed parameter, a narrower type or a new required field is enough to break every consumer. This subagent compares the base and the change, works out what outside code can see, and lists what would stop compiling or behaving the same.

Each finding comes with a migration note you can paste into a changelog. Nothing is edited.

Example

you › Check this branch against v2.3.0 before we tag a release.

agent › Recommend 3.0.0. Breaking: createClient() now requires region (was optional); ListOrders returns 422 instead of 400 on bad cursors. Behavioral: results are sorted by created_at desc, previously id asc. Migration notes written for all three.

Questions

Does it need an OpenAPI file?
No. A schema helps, but it also reads exported code, route definitions and tests to find the public surface.
Can it check against a published version?
Point it at a git tag or branch as the base. For published packages, give it the old version checked out in a folder.
  • Bug Hunter

    SubagentCode quality

    Free
  • C# Reviewer

    Subagentcsharp

    Free
  • Code Simplifier

    SubagentCode quality

    Free
  • Concurrency Reviewer

    SubagentCode quality

    Free