design-an-interface

name	design-an-interface
description	使用并行 sub-agents 为一个 module 生成多套差异显著的 interface 设计。适用于用户希望设计 API、探索 interface 选项、比较 module 形态，或提到“design it twice”的场景。

设计 Interface

本 skill 基于《A Philosophy of Software Design》中的 “Design It Twice”：你的第一个想法很可能不是最佳方案。先生成多套差异显著的设计，再进行比较。

工作流程

1. 收集要求

开始设计前，先弄清楚：

• 这个 module 要解决什么问题？
• 谁会调用它？（其他 modules、外部用户、tests）
• 关键操作有哪些？
• 存在哪些约束？（性能、兼容性、既有模式）
• 哪些内容应隐藏在内部，哪些需要公开？

询问：“这个 module 需要完成什么？谁会使用它？”

2. 生成设计（并行 Sub-Agents）

使用 Task tool 同时启动 3 个以上的 sub-agents。每个 sub-agent 必须提出一套差异显著的方案。

每个 sub-agent 使用以下 Prompt 模板：

为以下 module 设计 interface：[module description]

要求：[gathered requirements]

当前设计的约束：[为每个 Agent 分配不同约束]
- Agent 1：“尽量减少 method 数量，最多 1–3 个”
- Agent 2：“尽量提高灵活性，支持多种使用场景”
- Agent 3：“围绕最常见的调用场景进行优化”
- Agent 4：“参考 [specific paradigm/library] 的设计思路”

输出格式：
1. Interface signature（types/methods）
2. Usage example（caller 如何使用）
3. 该设计在内部隐藏什么
4. 该方案的取舍

3. 展示设计

每套设计都应展示：

1. Interface signature——types、methods、params
2. Usage examples——callers 在实际场景中如何使用
3. 隐藏内容——哪些复杂度保留在内部

依次展示各套设计，让用户先理解每个方案，再进入比较。

4. 比较设计

展示完全部设计后，从以下方面进行比较：

• Interface simplicity：methods 更少、params 更简单
• General-purpose 与 specialized：灵活性与聚焦程度
• Implementation efficiency：这种形态能否支持高效的内部实现？
• Depth：小 interface 隐藏大量复杂度（理想）；大 interface 只有单薄 implementation（应避免）
• 正确使用的难易程度与误用的难易程度

使用 prose 讨论取舍，不要使用 tables。重点说明不同设计分歧最大的地方。

5. 综合方案

最佳设计经常会结合多套方案中的优点。询问：

• “哪一套设计最符合你的主要使用场景？”
• “其他设计中是否有值得吸收的部分？”

评估标准

以下标准来自《A Philosophy of Software Design》：

Interface simplicity：Methods 越少、params 越简单，就越容易学习和正确使用。

General-purpose：无需修改即可处理未来的使用场景，但要警惕过度泛化。

Implementation efficiency：Interface 的形态是否允许高效实现，还是会迫使内部采用别扭结构？

Depth：小 interface 隐藏大量复杂度，构成 deep module（理想）。大 interface 配合单薄 implementation，构成 shallow module（应避免）。

反模式

• 不要允许 sub-agents 产出相似设计，必须确保方案具有显著差异
• 不要省略比较，价值来自方案之间的对照
• 不要进入实现阶段，当前工作只关注 interface 形态
• 不要根据实现工作量评估设计