/design-an-interface

name: design-an-interface
description: 设计接口契约 — 来自 superpowers 体系。本 skill 是桥接层,完整纪律见 <SUPERPOWERS_SKILL_ROOT>/design-an-interface/。
version: 4.0.0

Design-an-Interface(桥接到 superpowers)

Contract

• Inputs: design spec, domain constraints, integration points
• Outputs: interface contract document
• Gates: interface is testable and accepted by caller/implementer
• Required disciplines: `stage-gate`
• Next: `/domain-modeling` or `/writing-plans`

> **本仓库不维护此 skill 的内容**。完整纪律请读: > `<SUPERPOWERS_SKILL_ROOT>/design-an-interface/SKILL.md`

何时调

• brainstorming 之后,writing-plans 之前
• 需要把功能拆成可测试的接口

衔接点

• **产出**:接口契约文档
• **下一步**:`/domain-modeling` 或 `/writing-plans`
• **门控**:`disciplines/stage-gate` 第 2 层

降级方案(superpowers 未装时)

如果 `<SUPERPOWERS_SKILL_ROOT>/design-an-interface/` 不存在,按以下 4 步产出接口契约:

1. 列举调用方与实现方

• **调用方**是谁?(controller / 巴枪 / 第三方系统)
• **实现方**是谁?(哪个 service / 模块)
• **触发场景**有哪些?(主动调用 / 事件回调 / 定时)

2. 写接口契约表

每个接口必须含 5 列:

| 列 | 含义 | 例子 | |---|---|---| | Name | 方法/路径名 | `POST /api/v1/asn/receive` | | Input | 入参 schema | `{tcAsnId, lpnList[]}` | | Output | 出参 schema | `{receivedQty, exceptionList[]}` | | Errors | 错误码字典 | `E_ASN_NOT_FOUND(40401)` | | Pre/Post | 前置/后置条件 | 前置:ASN 状态=10;后置:状态=30 |

3. 验收契约

• **可测试性**:每个契约都对应 1 个测试用例(契约层用)
• **错误码对齐**:与全局 `09-QA审计报告` 的错误码字典一致
• **联调**:与调用方对齐字段名 / 类型,**字段名严禁猜测**(走 `disciplines/no-field-guessing`)

4. 输出 + 签字

写到 `docs/superpowers/specs/<topic>-interface.md`,末尾 `## Sign-off` 等用户白名单签字(4 句之一)。

最小纪律摘要

• **契约是合同**:写下来就不准改,改了要重新签字
• **错误码全局唯一**:不复用业务字段名当错误码
• **Pre/Post 必须**:只写 Input/Output = 验收没边界
• **联调不靠人脑**:调用方拿到契约文档就能写 Mock

安装提示

npx skills@latest add obra/superpowers-design-an-interface