Back to Details

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:
  1. Interface signature (types, methods, params)
  2. Usage example (how the caller actually uses it)
  3. What the design hides internally
  4. Trade-offs
同时调度3个及以上探索型或通用型Agent（单条消息，多次调用Agent工具）。为每个Agent设定截然不同的约束条件：
  • Agent 1：“最小化方法数量——目标是最多1-3个方法。”
  • Agent 2：“最大化灵活性——支持多种使用场景。”
  • Agent 3：“针对最常见场景优化（明确说明该场景）。”
  • （可选）Agent 4：“参考<特定范式或库>的设计思路。”
每个Agent需返回以下内容：
  1. 接口签名（类型、方法、参数）
  2. 使用示例（调用方实际如何使用）
  3. 该设计在内部隐藏了哪些细节
  4. 设计的权衡点

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