---
name: api-design
description: >
  API 设计与接口契约整理。
  Use when: 设计/评审 REST 或内部 API 契约、错误码、版本与兼容
  Do not use when: 实现金蝶 BOS 插件（走产品线 skill）；纯前端 UI 视觉（ui-ux-design）
---

# API 设计与接口契约整理

细则与检查清单：[references/details.md](references/details.md)

## When / Do not

**Use when**：设计/评审 REST 或内部 API 契约、错误码、版本与兼容  
**Do not use when**：实现金蝶 BOS 插件（走产品线 skill）；纯前端 UI 视觉（ui-ux-design）

## Input / Output

| Input | Output |
|-------|--------|
| 目标代码/需求/约束 | 可执行改动建议或产出物 + 验证方式 |

## Steps

```
- [ ] 1. 明确资源与用例
- [ ] 2. 定义路径/方法/请求响应字段
- [ ] 3. 错误码与幂等/超时约定
- [ ] 4. 兼容与版本策略
- [ ] 5. 给出示例请求响应
```

## 硬规则摘要

- 默认 JSON + 明确错误结构
- 破坏性变更需版本或迁移说明

## 失败策略

| 失败 | 动作 |
|------|------|
| 范围过大 | 拆任务，先交付最小可验证切片 |
| 信息不足 | 列出最小待确认项，不臆造业务事实 |

## 验证

- 说明改了什么、如何验证、剩余风险