一句话

设计能长期稳定的 API 和模块边界：契约先行、错误语义统一、演进只加不改，覆盖 REST 和 TypeScript 两套写法。

何时用

• 适合：设计 REST 或 GraphQL 端点、模块间类型契约、前后端边界；公共接口第一版定稿前。
• 不适合：纯内部私有函数、一次性脚本；接口已冻结只做 bug 修复。

怎么用

帮我设计订单模块的 REST API，契约要稳定，以后能加字段但不破坏老客户端

1. 契约先行：先定请求、响应和错误体的形状，再写实现。
2. 统一错误语义：状态码、错误体格式、校验失败的表现全端一致。
3. 在边界校验输入，内部不重复校验。
4. 演进只加不改（Prefer Addition Over Modification），守 One-Version Rule，不并行维护多版本。
5. 写操作 honour 幂等键；命名可预测。REST 侧套分页、过滤、PATCH 局部更新模式；TypeScript 侧用 discriminated union、输入输出分离、branded ID。

产出

• 接口契约与错误格式约定，以及相应的端点或类型定义。

要点与坑

• Hyrum's Law：任何可观察行为都会被依赖，默认只加不改；破坏性变更要走 addy-deprecation-and-migration 的流程。
• Common Rationalizations 列出「这只是内部 API」等借口，Red Flags 段用于自查。
• 接口冻结前值得配 addy-doubt-driven-development 做一次对抗性复核。

关联

• 上游：addy-spec-driven-development · 下游：addy-deprecation-and-migration · 同类：matt-codebase-design
• 所属：00-addy-概览 · 工作流：W4-大型模糊项目