从零设计一个 API，要先想清楚哪些事
设计阶段改一行，比上线后改一个字段便宜得多。把不确定性尽量留在还没有调用方的时候。
怎么做
先把需求落成实体和状态机
把需求和主要使用场景贴进「把需求转成数据模型」，先不写代码。让它给出实体清单、关系与基数、核心对象状态机，以及半年内会变的字段，最后让它列出三处必须问产品的地方。实体和状态决定了接口有哪些资源、哪些动作不能直接暴露。
在写实现之前挑设计的刺
把资源、路径、请求响应示例、分页和错误码草案给「接口设计挑刺」。它会列五个实现时最容易出问题的点、冗余和缺失的字段、向后兼容的改法，以及有没有更简单的替代方案。现在改只需要改文档，有调用方之后就要协调排期。
把失败路径写清楚
等错误码和重试约定成形，把相关代码给「审查错误处理」。只看失败路径：被吞掉的异常、缺少关键 id 的错误信息、不安全的重复写入、该失败却继续跑的地方。它给出的错误码和重试语义要写回接口文档，成为调用方能依赖的契约。
用测试把契约锁住
把实现和测试给「给测试用例挑漏」。重点补这些边界：空列表、超长字段、重复提交、权限不足、上游超时。每条写清输入、预期和为什么容易漏；契约测试断言状态码和响应结构，不要断言内部实现。
契约定稿后再拆并行任务
最后把定稿的契约和团队规模给「把需求拆成可并行的任务」。先定不可并行的顺序约束，其余按可独立交付切分，标出依赖方向和最容易冲突的共享文件。前端可以照契约先做 mock，不必等后端全部完成。
用到的提示词
常见问题
API 要不要一开始就加版本号
要留位置，但不必第一天就上 v2。先把资源命名、错误码和分页约定稳定下来；真出现破坏性变更时，版本号是最低成本的分叉方式。上来就为想象中的变化加一层版本，往往只是多维护一套路径。
接口还没实现，能让 AI 先挑设计吗
可以，而且这时候改最便宜。把请求响应示例、错误码和调用方场景一起给它，挑出的问题才有依据；只给一句「设计一个用户接口」，得到的是通用建议。
错误码是不是分得越细越好
不是。调用方真正要区分的是能不能重试、要不要提示用户、是不是权限问题。按这三个维度分组，比堆几十个错误码更容易被正确使用。