Help us improve
Share bugs, ideas, or general feedback.
From code-audit
Compares REST API surface between two git revisions and reports breaking changes. Works with Flask, FastAPI, Express, Spring Boot, and OpenAPI specs.
npx claudepluginhub dan323/easier-life-skills --plugin code-auditHow this skill is triggered — by the user, by Claude, or both
Slash command
/code-audit:find-breaking-rest-apisonnetThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Compare the REST API surface between two git revisions and produce a structured, actionable report. A breaking change is any change that requires existing API clients to update their code.
Provides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
Share bugs, ideas, or general feedback.
Compare the REST API surface between two git revisions and produce a structured, actionable report. A breaking change is any change that requires existing API clients to update their code.
This skill is read-only. It produces a report. It does not modify any file.
Before doing any work, call TaskCreate for each phase below. Call TaskUpdate (status in_progress) when you begin a phase and TaskUpdate (status completed) when you finish it.
If the user didn't specify refs, use the most recent semver tag vs HEAD. If there are no tags, use HEAD~1 vs HEAD. Tell the user which range you're comparing before proceeding.
BASE=$(git tag --sort=-version:refname | grep -E '^v?[0-9]+\.[0-9]+' | head -1)
[ -z "$BASE" ] && BASE="HEAD~1"
git diff --name-only "$BASE" HEAD
Get the list of changed files. Then:
Always trace prefixes: Flask url_prefix, FastAPI router prefixes, Spring @RequestMapping at the class level, Express app.use('/prefix', router). The full public path is what clients call.
Breaking changes — require client updates:
| Change | Client impact |
|---|---|
| Endpoint removed | 404 or 405 |
| Path changed | 404 on old path |
| HTTP method changed | 405 |
| Required request field added | 400 if not sent |
| Optional request field made required | 400 if not sent |
| Response field removed | undefined/null on client |
| Response field type changed incompatibly | Parse error on client |
| Auth added to previously open endpoint | 401/403 |
| Auth scheme changed | 401 with old credentials |
| Status code changed | Client branching on status codes breaks |
| Shared schema: response field removed / required field added | All endpoints using schema are affected |
Non-breaking changes — safe to ship:
Edge cases — flag with a note:
/:id → /:userId): non-breaking for URL construction, but note itSeverity — assign to each breaking change:
Always use this exact structure. Every section is required (write "None" if empty).
## Breaking REST API Change Report
Comparing: {BASE} → HEAD | {date}
Route files changed: {N} | Shared schemas changed: {N} | Files traced (unchanged): {list or 0}
---
### Summary
| Endpoint | Change | Severity | Client action |
|----------|--------|----------|---------------|
| POST /api/orders | Required field added: `sourceChannel` | HIGH | Send `sourceChannel` in all POST /api/orders requests |
| GET /api/users/:id | Response field removed: `phone` | MEDIUM | Remove reads of `.phone` from response handling |
| DELETE /api/v1/users/:id | Endpoint removed | HIGH | Migrate to DELETE /api/v2/users/:id |
Total breaking: {N} | Total non-breaking: {N}
---
### Breaking Changes
#### {Endpoint or schema name} [{severity}]
{file:line}
- **What changed**: {specific field/path/method that changed}
- **Why it breaks clients**: {concrete impact — 400, 404, null, parse error, etc.}
- **Client action required**: {exact step — "add field X to request body", "update path from X to Y", "handle null for field Z"}
{If discovered via shared schema in unchanged file: "Discovered via shared schema `SchemaName` in `file.py` — this route file was not in the diff"}
---
### Non-Breaking Changes
- {brief description}
---
### Recommended next steps
- {specific action tailored to what was found — not generic advice}
#### POST /api/orders, POST /api/admin/orders [HIGH]
src/main/java/com/example/dto/CreateOrderRequest.java:34
- **What changed**: Required field `sourceChannel` added (`@NotBlank`)
- **Why it breaks clients**: Clients not sending `sourceChannel` will receive HTTP 400
- **Client action required**: Add `sourceChannel` (non-empty string) to all POST /api/orders and POST /api/admin/orders request bodies
Discovered via shared DTO `CreateOrderRequest` in `OrderController.java` and `AdminOrderController.java` — neither controller file was in the diff
## Breaking REST API Change Report
Comparing: {BASE} → HEAD | {date}
Route files changed: {N} | Shared schemas changed: {N}
No breaking REST API changes detected.
Non-breaking changes: {list}
All changes are backward-compatible with {BASE}.
## Breaking REST API Change Report
Comparing: HEAD~1 → HEAD
No REST API surface was affected by these changes.
Changed files: {list — tests, README, internal utilities, etc.}