← codebase-design · 技能图谱

Design It Twice

设计两次

When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.

当用户想为选定的加深候选项探索替代接口时，使用这个并行子代理模式。基于"设计两次"（Ousterhout）——你的第一个想法不太可能是最好的。

Uses the vocabulary in SKILL.md — module, interface, seam, adapter, leverage.

使用 SKILL.md 中的词汇——模块、接口、接缝、适配器、杠杆收益。

Process

流程

1. Frame the problem space

1. 界定问题空间

Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:

在生成子代理之前，为所选候选项写一份面向用户的问题空间说明：

  • The constraints any new interface would need to satisfy
  • 任何新接口需要满足的约束条件
  • The dependencies it would rely on, and which category they fall into (see DEEPENING.md)
  • 它依赖的依赖项及其所属类别（见 DEEPENING.md）
  • A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
  • 一个粗略的示意性代码草图来具体化约束——不是方案，只是让约束变得具体的方式

Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.

向用户展示这些内容，然后立即进入步骤 2。用户在阅读和思考的同时，子代理并行工作。

2. Spawn sub-agents

2. 生成子代理

Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a radically different interface for the deepened module.

使用 Agent 工具并行生成 3 个以上的子代理。每个子代理必须为加深后的模块生成一个截然不同的接口。

Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from DEEPENING.md, what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:

为每个子代理提供单独的技术简报（文件路径、耦合细节、来自 DEEPENING.md 的依赖类别、接缝背后的内容）。简报独立于步骤 1 中面向用户的问题空间说明。给每个代理不同的设计约束：

  • Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
  • Agent 1："最小化接口——最多 1-3 个入口点。最大化每个入口点的杠杆收益。"
  • Agent 2: "Maximise flexibility — support many use cases and extension."
  • Agent 2："最大化灵活性——支持多种用例和扩展。"
  • Agent 3: "Optimise for the most common caller — make the default case trivial."
  • Agent 3："为最常见的调用方优化——让默认情况变得简单。"
  • Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
  • Agent 4（如适用）："围绕端口和适配器设计跨接缝依赖。"

Include both SKILL.md vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.

在简报中同时包含 SKILL.md 词汇和 CONTEXT.md 词汇，使每个子代理的命名与架构语言和项目的领域语言保持一致。

Each sub-agent outputs:

每个子代理输出以下内容：

  1. Interface (types, methods, params — plus invariants, ordering, error modes)
  1. 接口（类型、方法、参数——以及不变性、顺序、错误模式）
  1. Usage example showing how callers use it
  1. 使用示例，展示调用方如何使用
  1. What the implementation hides behind the seam
  1. 实现在接缝后隐藏了什么
  1. Dependency strategy and adapters (see DEEPENING.md)
  1. 依赖策略和适配器（见 DEEPENING.md）
  1. Trade-offs — where leverage is high, where it's thin
  1. 权衡——杠杆收益高的地方和薄弱的地方

3. Present and compare

3. 展示与比较

Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by depth (leverage at the interface), locality (where change concentrates), and seam placement.

依次展示设计，让用户逐一消化，然后用文字进行比较。按深度（接口处的杠杆收益）、局部性（变更集中的地方）和接缝位置进行对比。

After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

比较之后，给出你自己的推荐：你认为哪个设计最强以及为什么。如果不同设计的元素可以很好地组合，提出一个混合方案。要有主见——用户想要的是有力的判断，而不是一个菜单。