改了你没要求改的公共 API
Changed a public API you didn't ask to change
智能体改了导出函数的签名、公共类型或 API 返回结构，破坏了 diff 之外的调用方。
适用于: Claude Code · Cursor · Codex · Copilot agent
症状
仓库里一切都能编译、测试也通过，然后下游服务、SDK 用户或移动端坏了。
为什么会这样
智能体只看得到仓库内的调用方，就以为签名可以随意改。agent-review 列为 AR032“修改了公共契约”（高严重度）。
示例
示意。
diff- export function getUser(id: string): Promise<User>
+ export function getUser(opts: { id: string; includeDeleted?: boolean }): Promise<User | null>
复制即用的修复
按你用的智能体挑选文件。规则片段用英文写，放进任何仓库都能用。
规则
Claude Code：加入 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.
规则
Codex、Copilot 编码智能体等：加入 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 规则
Cursor：项目规则
.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 / 脚本
在 CI 中发现 API 表面变化（TypeScript，api-extractor）
把生成的 API 报告提交进仓库；任何改了公共接口的 PR 都会体现为这个文件的 diff。
.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