---
name: api-shape-explorer
description: 使用并行子代理为一个模块生成多个截然不同的接口设计方案。当用户想要设计 API、探索接口选项、比较模块形态或提到「设计两次」时使用。
---

# 设计接口

基于《软件设计哲学》中的「设计两次」原则：你的第一个想法不太可能最好。生成多个截然不同的设计方案，然后进行比较。

## 工作流程

### 1. 收集需求

在设计之前，了解以下内容：

- [ ] 这个模块解决什么问题？
- [ ] 调用方是谁？（其他模块、外部用户、测试）
- [ ] 关键操作有哪些？
- [ ] 是否有约束条件？（性能、兼容性、现有模式）
- [ ] 哪些内容应该隐藏在内，哪些应该暴露？

询问：「这个模块需要做什么？谁会使用它？」

### 2. 生成设计方案（并行子代理）

使用 Task 工具同时启动 3 个以上的子代理。每个代理必须提出一种**截然不同**的方案。

```
每个子代理的提示模板：

为以下内容设计接口：[模块描述]

需求：[收集到的需求]

该设计的约束条件：[为每个代理分配不同的约束条件]
- 代理 1：「最小化方法数量——目标最多 1-3 个方法」
- 代理 2：「最大化灵活性——支持多种使用场景」
- 代理 3：「针对最常见的情况进行优化」
- 代理 4：「借鉴[特定范式/库]的灵感」

输出格式：
1. 接口签名（类型/方法）
2. 使用示例（调用方如何使用）
3. 该设计在内部隐藏了什么
4. 该方法的权衡取舍

### 3. 展示设计方案

展示每个设计，内容包括：

1. **接口签名** —— 类型、方法、参数
2. **使用示例** —— 调用方在实际中如何使用
3. **隐藏内容** —— 隐藏在内部的复杂性

按顺序展示设计方案，以便用户在比较之前能充分理解每种方案。

### 4. 比较设计方案

展示所有设计方案后，从以下几个方面进行比较：

- **接口简洁性**：方法更少、参数更简单
- **通用性与专用性**：灵活性 vs 专注度
- **实现效率**：接口形态是否允许高效的内部实现？
- **深度**：小接口隐藏大量复杂性（好）vs 大接口搭配薄实现（差）
- **正确使用的容易程度** vs **误用的容易程度**

用散文而非表格讨论权衡取舍。突出各个设计方案之间分歧最大的地方。

### 5. 综合提炼

通常最好的设计方案融合了多个选项的见解。询问：

- 「哪个设计最符合你的主要使用场景？」
- 「其他设计中是否有值得借鉴的元素？」

## 评估标准

摘自《软件设计哲学》：

**接口简洁性**：方法更少、参数更简单 = 更容易学习和正确使用。

**通用性**：能够在不改动的情况下处理未来使用场景。但要注意过度泛化。

**实现效率**：接口形态是否允许高效的实现？还是会迫使内部结构变得笨拙？

**深度**：小接口隐藏大量复杂性 = 深度模块（好）。大接口搭配薄实现 = 浅度模块（避免）。

## 反模式

- 不要让子代理产生相似的设计方案——要强制它们截然不同
- 不要跳过比较环节——价值在于对比
- 不要实现——这纯粹是关于接口形态的设计
- 不要根据实现工作量来评估