Changed a public API you didn't ask to change
改了你没要求改的公共 API
The agent modifies an exported function signature, a public type or an API response shape, breaking consumers outside the diff.
Applies to: Claude Code · Cursor · Codex · Copilot agent
Symptom
Everything in the repo compiles and passes, then a downstream service, SDK user or mobile client breaks.
Why it happens
The agent only sees in-repo callers and treats the signature as free to change. agent-review lists AR032 "Changed public contract" (High severity).
Example
Illustrative.
diff- export function getUser(id: string): Promise<User>
+ export function getUser(opts: { id: string; includeDeleted?: boolean }): Promise<User | null>
Copy-paste fixes
Pick the files for the agents you use. Snippets are in English so they work in any repo.
Rules
Claude Code: add to CLAUDE.md
CLAUDE.md## Public contracts are frozen unless the task says otherwise
- Do not change exported signatures, public types, API routes, response shapes, CLI flags,
env var names or DB schemas unless the request explicitly asks.
- If a change is needed, keep backward compatibility (add an optional parameter or a new function)
and list it under "Contract changes" in your summary.
Rules
Codex, Copilot coding agent and others: add to AGENTS.md
AGENTS.md## Public contracts are frozen unless the task says otherwise
- Do not change exported signatures, public types, API routes, response shapes, CLI flags,
env var names or DB schemas unless the request explicitly asks.
- If a change is needed, keep backward compatibility (add an optional parameter or a new function)
and list it under "Contract changes" in your summary.
Cursor rule
Cursor: project rule
.cursor/rules/public-contract-changed.mdc---
description: "AgentFails: Changed a public API you didn't ask to change"
alwaysApply: true
---
## Public contracts are frozen unless the task says otherwise
- Do not change exported signatures, public types, API routes, response shapes, CLI flags,
env var names or DB schemas unless the request explicitly asks.
- If a change is needed, keep backward compatibility (add an optional parameter or a new function)
and list it under "Contract changes" in your summary.
CI / script
Catch API surface changes in CI (TypeScript, api-extractor)
Commit the generated API report; any PR that changes the public surface shows up as a diff to that file.
.github/workflows/api-surface.ymlname: api-surface
on: pull_request
jobs:
api:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22 }
- run: npm ci && npm run build
- run: npx api-extractor run # fails if etc/*.api.md changed and isn't committed