SuperAPI AI Directory

interface-design-lab

Coding & development

View repository

Updated 11-06 16:19

About this skill

Interface Form Exploration

Based on the "design twice" principle from A Philosophy of Software Design: your first option is unlikely to be the best. First generate several distinctly different designs, then compare them.

Workflow

1. Gather requirements

Before starting the design, first understand the following information:

  • What problem is this module meant to solve?
  • Who will call it? (other modules, external users, test code)
  • What are the core operations?
  • What constraints are there? (performance, compatibility, existing patterns)
  • What should be encapsulated internally, and what needs to be exposed?

Key question: "What does this module need to do? Who will use it?"

2. Generate design options (parallel subagents)

Launch 3 or more subagents at the same time (using the Task tool), and each subagent must produce onedistinctly differentdesign option.

每个子代理的提示词模板:

为以下模块设计接口:[模块描述]

需求:[已收集的需求]

本设计的约束条件:[为每个代理分配不同的约束]
- 代理 1:"方法数量最少——目标 1-3 个方法"
- 代理 2:"灵活性最大——支持尽可能多的使用场景"
- 代理 3:"为最常见场景优化"
- 代理 4:"借鉴 [特定范式/库] 的思路"

输出格式:
1. 接口签名(类型/方法)
2. 使用示例(调用方如何使用)
3. 该设计在内部隐藏了什么
4. 该方案的优劣权衡

3. Present the design options

Each option should present:

  1. Interface signature - types, methods, parameters
  2. Usage example - how the caller uses it in a real scenario
  3. Encapsulated content - what complexity is hidden internally

Present the options one by one so the user can fully understand each approach before comparing them.

4. Compare the options

After presenting all options, compare them along the following dimensions:

  • Interface simplicity: fewer methods and simpler parameters make it easier to learn and use correctly
  • Generality vs. specificity: the trade-off between flexibility and focus
  • Implementation efficiency: does the interface form support efficient implementation? Or does it lead to awkward internal structure?
  • Depth: a small interface encapsulating a large amount of complexity = deep module (good); a large interface backed by a thin implementation = shallow module (should be avoided)
  • Ease of use vs Risk of misuse

Discuss the trade-offs in prose, not in a table. Focus on pointing out where the options differ the most.

5. Synthesize and refine

The best option often combines the strengths of multiple designs. You can ask the user:

  • "Which option best fits your main usage scenario?"
  • "Are there any elements from the other options worth borrowing?"

Evaluation criteria

From A Philosophy of Software Design:

Interface simplicity: fewer methods and simpler parameters = easier to learn and less prone to misuse.

Generality: able to handle future usage scenarios without modification. But beware of over-generalization.

Implementation efficiency: does the interface form support efficient implementation? Or does it force the internal structure to become awkward?

Depth: a small interface encapsulating a large amount of complexity = deep module (good). A large interface backed by a thin implementation = shallow module (should be avoided).

Anti-patterns

  • Do not let sub-agents produce similar solutions—you must ensure that the solutions are fundamentally different from one another
  • Do not skip the comparison step—its value lies in the clash between solutions
  • Do not start implementing—this step focuses only on the interface shape
  • Do not use implementation difficulty as an evaluation criterion