api-contract：让 Claude Code 替你检查 API 设计有没有坑

为什么你的 API 总是改着改着就炸了

写后端的人大概都经历过：需求评审时 API 文档画得漂漂亮亮，上线跑了两周，前端开始抱怨「这个字段你们悄悄下了」「返回结构怎么多了层嵌套没人说」。然后就是无尽的接口对齐会、临时 hotfix、以及深夜群里的一声叹息。

这不是团队能力问题，是 API 设计没有约束力——没有人在写代码的时候被强制思考「这个接口的边界在哪里」「错误怎么返回才合理」「谁有权调用」。

今天想分享一个 Claude Code Skill，叫 api-contract。它做的事情很简单：当你设计或审查 API 时，自动跑一套结构化检查清单，覆盖从路由定义到数据库交互到认证边界的全链路。

它检查什么

• 请求 / 响应结构：字段类型、是否必填、嵌套深度有没有失控
• 认证与授权：谁可以调这个接口，token 验证放在哪一层，有没有越权路径
• 错误模型：HTTP 状态码用对了没，错误 body 格式统不统一，客户端能据此做判断吗
• 数据库交互边界：查询有没有 N+1 风险，事务边界画清楚了吗
• 变更兼容性：加字段算不算 breaking change删字段呢，版本号升了没有

为什么对开发者有用

常规 Code Review 的问题是——reviewer 不一定能覆盖到所有维度，尤其在接口设计阶段，很多问题还没显现就合入了。api-contract 的思路是把「好 API 长什么样」固化成一个可执行的检查集，让 Claude Code 在你写代码的时候就能提示，而不是等到测试阶段才发现。

它特别适合两类场景：

• 新接口设计：写完路由和 schema 之后跑一遍，提前堵住设计漏洞
• 接第三方 API：在写 typed client 之前用这个 skill 梳理清楚接口契约，避免和上游预期错位

怎么装

Claude Code 用户直接跑：

npx skills add https://github.com/allytag/claude_code --skill api-contract

或者手动下载 SKILL.md 放到 ~/.claude/skills/ 目录下，重启 Claude Code 即可。

Skill 来自 allytag/claude_code 仓库，这个库还收录了 agent-bootstrap、tool-coach、performance-pass 等 15 个覆盖软件工程全生命周期的 Skill 合集，质量都维持在较高的工程水准。

小结

API 设计是软件工程的门面，但大多数团队只有「口头规范」没有「自动检查」。api-contract 把 API 设计规范变成了一道道可以执行的检查项，用 AI 的力量把它嵌进了日常开发流。不保证你再也不改 API，但至少能少踩很多「这个接口不是这么用的」的坑。

作者：江望·开发者洞察
GitHub：https://github.com/allytag/claude_code

GitHub: https://github.com/allytag/claude_code