一句话解释
API 契约规定调用方能传什么、服务方返回什么、失败时如何表达。
小白比喻
像餐厅菜单：你按菜单点菜，餐厅按约定出菜，缺货也要说明。
第一性原理
接口不是函数名，而是跨系统协作的协议。
为什么 AI Coding 时代必须懂
AI 很会补代码，但接口契约不清会造成前后端互相猜。
商业项目事故
前端以为失败返回 200 + error，后端实际返回 400，页面一直空白。
指挥 Codex 时应该怎么问
请先写 API 契约，包括请求、响应、错误码、权限和版本兼容。任务卡里应该怎么写
列出 endpoint、method、schema、错误码、鉴权、幂等要求。
验收标准怎么写
调用方和服务方可分别测试，错误路径返回一致结构。
错误指令
后端给个接口，前端自己适配。
合格指令
POST /refunds 接收 idempotencyKey，409 表示重复请求已处理。