evanflow-design-interface

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EvanFlow: Design an Interface

EvanFlow：设计接口

Source principle: "Design It Twice" from John Ousterhout's A Philosophy of Software Design. Your first idea is unlikely to be the best. Generate radically different designs, compare, synthesize.

核心原则：源自John Ousterhout所著《软件设计哲学》中的“两次设计法”。你的首个想法未必是最优解。生成截然不同的设计方案，进行对比并整合。

Vocabulary

术语说明

See

evanflow

meta-skill. Key terms: interface, depth, module, adapter.

参考

evanflow

元技能。关键术语：interface、depth、module、adapter。

When to Use

适用场景

Designing a new API surface (tRPC router, service interface, public function set)
Refactor changes a public interface — design before implementing
Stuck on the shape of a module
The team disagrees on the right interface

设计新的API层面（如tRPC路由、服务接口、公共函数集）
重构需修改公共接口——先设计再实现
对模块架构形态感到困惑
团队对合适的接口方案存在分歧

The Flow

流程步骤

1. Gather Requirements

1. 收集需求

What problem does this module solve?
Who are the callers? (other modules, external users, tests)
Key operations
Constraints (performance, compatibility, existing project patterns from
```
CONTEXT.md
```
)
What should be hidden vs. exposed

该模块要解决什么问题？
调用方是谁？（其他模块、外部用户、测试用例）
核心操作有哪些？
约束条件（性能、兼容性、
```
CONTEXT.md
```
中记录的现有项目模式）
哪些内容需要隐藏，哪些需要暴露？

2. Spawn Parallel Sub-Agents (Design It Twice — actually 3+)

2. 生成并行子Agent（两次设计法——实际生成3个及以上）

Dispatch 3+ Explore or general-purpose agents simultaneously (single message, multiple Agent tool calls). Each gets a radically different constraint:

Agent 1: "Minimize method count — aim for 1–3 methods max."
Agent 2: "Maximize flexibility — support many use cases."
Agent 3: "Optimize for the most common case (specify what that is)."
(Optional) Agent 4: "Take inspiration from <specific paradigm or library>."

Each returns:

Interface signature (types, methods, params)
Usage example (how the caller actually uses it)
What the design hides internally
Trade-offs

同时调度3个及以上探索型或通用型Agent（单条消息，多次调用Agent工具）。为每个Agent设定截然不同的约束条件：

Agent 1：“最小化方法数量——目标是最多1-3个方法。”
Agent 2：“最大化灵活性——支持多种使用场景。”
Agent 3：“针对最常见场景优化（明确说明该场景）。”
（可选）Agent 4：“参考<特定范式或库>的设计思路。”

每个Agent需返回以下内容：

接口签名（类型、方法、参数）
使用示例（调用方实际如何使用）
该设计在内部隐藏了哪些细节
设计的权衡点

3. Present Designs Sequentially

3. 依次展示设计方案

Show each design separately so the user can absorb each before comparison. No tables yet — let each design stand on its own.

分别展示每个设计方案，让用户在对比前充分理解每个方案。暂不使用表格——让每个方案独立呈现。

4. Compare

4. 方案对比

After all designs are shown, compare on:

Interface simplicity: fewer methods, simpler params
General-purpose vs. specialized: flexibility vs. focus
Implementation efficiency: does the shape allow efficient internals or force awkward ones?
Depth: small interface hiding significant complexity (good) vs. large interface with thin implementation (bad)
Ease of correct use vs. ease of misuse

Discuss in prose. Highlight where designs diverge most.

所有设计方案展示完毕后，从以下维度进行对比：

接口简洁性：方法数量更少、参数更简单
通用型vs专用型：灵活性vs专注度
实现效率：接口形态是否允许高效的内部实现，还是会导致尴尬的实现方式？
深度：小接口隐藏大量复杂度（优秀）vs大接口但实现层较浅（糟糕）
易用性vs误用风险：正确使用的便捷性vs错误使用的可能性

采用文字论述，重点突出设计方案间的主要差异。

5. Synthesize

5. 方案整合

Often the best design combines insights from multiple options. Ask:

"Which design best fits the primary use case?"
"Any elements from other designs worth incorporating?"

最优设计通常会整合多个方案的亮点。思考以下问题：

“哪个设计最符合核心使用场景？”
“其他方案中有哪些元素值得纳入？”

6. Embedded Grill on the Synthesis

6. 对整合方案的深度质询

Before committing to the design:

"What's the simplest way a caller could misuse this?"
"What test would force this interface to change unnecessarily? Does that test exist or would we write it?"
"Is the interface still simple after we incorporate the borrowed elements, or did the synthesis bloat it?"
"Apply the deletion test to internal helper modules implied by this design."

在确定最终设计前：

“调用方最容易误用该接口的方式是什么？”
“哪些测试会导致该接口不必要地变更？这类测试已存在还是需要我们编写？”
“纳入其他方案的元素后，接口是否依然简洁，还是整合过程导致了接口膨胀？”
“对该设计隐含的内部辅助模块应用删除测试。”

Hard Rules

硬性规则

Don't let sub-agents converge. Enforce radical difference. If agents return similar designs, re-spawn with sharper constraints.
Don't skip comparison. The value is in the contrast.
Don't implement. This skill is purely about interface shape. Implementation goes through
```
evanflow-writing-plans
```
+
```
evanflow-tdd
```
.
Don't evaluate based on implementation effort. Evaluate on interface quality.
Never auto-commit. Even a design doc gets staged, not committed.

禁止子Agent趋同：必须保证设计方案截然不同。若Agent返回相似方案，需重新生成并施加更明确的约束条件。
不可跳过对比环节：价值源于方案间的差异对比。
禁止直接实现：本技能仅聚焦于接口形态。实现环节需通过
```
evanflow-writing-plans
```
+
```
evanflow-tdd
```
完成。
不可基于实现难度评估：需以接口质量为评估标准。
绝对禁止自动提交：即使是设计文档也仅需暂存，不可直接提交。

Hand-offs

移交路径

Design chosen →
```
evanflow-writing-plans
```
(the plan implements the design)
Design reveals architecture concerns →
```
evanflow-improve-architecture
```
first
New domain terms emerged →
```
evanflow-glossary
```
to update
```
CONTEXT.md
```

选定设计方案 → 移交至
```
evanflow-writing-plans
```
（该计划负责实现设计）
设计暴露架构问题 → 优先移交至
```
evanflow-improve-architecture
```
出现新领域术语 → 移交至
```
evanflow-glossary
```
以更新
```
CONTEXT.md
```