How I Made Claude Code Auto-Fix Breaking API Changes in CI

#ai #openai #devops #openapi

AI coding assistants are great at generating code. But what happens when the code they generate breaks your API contract? I built a workflow where Claude Code reads structured CI output, understands the breaking change, and fixes it — automatically.

The Problem

If you have an OpenAPI spec checked into your repo, there's a good chance nobody is actually reviewing it on pull requests. Linters like Spectral validate the spec in isolation, but they don't compare old vs. new. They'll catch a missing description, but not the fact that you just changed a response field from string to integer — the kind of change that breaks every downstream consumer.

I needed something that would:

Diff the spec against the base branch on every PR
Classify each change as breaking or non-breaking
Tell me the exact semver impact
Give me a migration guide so I could fix it fast

The Solution: Delimit GitHub Action

I built Delimit, a GitHub Action that does all of this deterministically. No LLM in the loop, no external API calls — just a diff engine that understands 27 types of OpenAPI contract changes (17 breaking, 10 non-breaking).

Setup

Add one workflow file to your repo:

name: API Contract Check
on: pull_request

jobs:
  delimit:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: delimit-ai/delimit-action@v1
        with:
          spec: api/openapi.yaml

That's it. Delimit auto-fetches the base branch version of your spec and diffs it against the PR changes. It runs in advisory mode by default — posts a PR comment but never fails your build.

The Auto-Fix Loop

Here's where it gets interesting. Claude Code can read CI output. So when Delimit flags a breaking change, Claude sees:

What changed (endpoint removed, type changed, enum value removed)
Where it changed (exact path in the spec)
Why it's breaking (severity classification)
How to fix it (migration guide)

That structured output is enough for Claude to submit a fix.

The Loop in Practice

You can see this working end-to-end on PR #11:

Claude Code makes changes that modify the OpenAPI spec
Delimit runs and flags the breaking changes in a PR comment
Claude reads the comment, understands the issue, and pushes a fix
Delimit re-runs — all checks pass

The reason this converges (instead of looping forever) is that the diff engine is deterministic. Same input, same output.

CLI for Local Development

npx delimit-cli lint api/openapi.yaml
npx delimit-cli diff api/openapi.yaml --base main

Custom Policies

# .delimit/policies.yml
rules:
  - id: no-v2-removals
    change_type: endpoint_removed
    path_pattern: "/v2/*"
    severity: error
    message: "v2 endpoints cannot be removed without a deprecation period"