design-first

name	design-first
description	在编写任何代码之前，引导结构化设计思维，通过 5 个渐进式层级。层级：能力（Capabilities）、组件（Components）、交互（Interactions）、契约（Contracts）、实现（Implementation）。在构建新功能、重构重要代码、设计模块时使用，或在用户说'design this'、'architect this'、'let's think before coding'、'walk me through the design'或'whiteboard this'时使用。对于简单工具类或单组件任务，从第 4 层（契约）开始。不要用于快速 bug 修复。

Design-First（渐进式设计引导）

问题所在

AI 会跳过需求→实现的步骤，将所有设计决策静默处理。结果：你在评估范围、架构、集成、契约、质量时，所有这些都纠缠在一起。在 400 行生成的代码中发现范围不匹配，远比在 2 分钟的设计对话中捕获要昂贵得多。

解决方案：重建人类结对编程时自然进行白板讨论的方式——在编码之前，通过渐进式设计层级逐步推进。

5 个层级

五个层级，从抽象到具体。每个层级揭示原本会隐藏在生成代码中的决策类别。

第 1 层：能力（Capabilities）——"做什么"

目的：确认范围。揭示系统需要交付的用户可感知成果。建立共享词汇表——确保人类和 AI 谈论的是同一个功能、同一边界。

输出格式：用户可感知能力的编号列表，最多 5 项。每项用平实语言描述成果，而非实现细节。

边界：不涉及组件、架构或技术细节。如果能力描述中提到具体技术、类或数据结构——应属于后续层级。本层只回答"用户得到什么？"

检查点："第 1 层（能力）看起来正确吗？我可以进入第 2 层（组件）吗？"

第 2 层：组件（Components）——"谁来做"

目的：识别构建块。系统有哪些主要部分，每个部分负责什么？

输出格式：3-5 个组件，每个组件有单一职责和一行描述。包含 ASCII 或 Mermaid 图展示它们之间的关系。注明与现有基础设施的集成点。

边界：不涉及数据流、序列操作或交互细节。每个组件只描述它是什么和它拥有什么——不描述如何与其他部分通信。如果写"A 向 B 发送 X"——应属于第 3 层。

检查点："第 2 层（组件）看起来正确吗？我可以进入第 3 层（交互）吗？"

第 3 层：交互（Interactions）——"它们如何通信"

目的：定义组件之间的数据流。构建块如何通信以交付能力？

输出格式：序列图（ASCII 或 Mermaid）或编号流程，展示操作顺序。对于每次交互，描述组件之间传递的数据内容。参见 ./references/methodology-detail.md 获取符号指南。

边界：不涉及函数签名、类型定义或实现细节。关注组件之间传递什么，而非每个组件内部如何处理。如果定义方法参数或返回类型——应属于第 4 层。

检查点："第 3 层（交互）看起来正确吗？我可以进入第 4 层（契约）吗？"

第 4 层：契约（Contracts）——"接口定义"

目的：定义接口、方法签名、类型定义，以形式化交互。交接产物——实现将基于此规范构建的规格说明。

输出格式：类型化接口、方法签名、类型定义。使用项目的主要语言（TypeScript 接口、Java 接口、Python protocols 等）。如果模糊，在编写契约前询问。不包含函数体——仅签名和类型。在交互可能失败时包含错误/异常类型。参见 ./references/methodology-detail.md 获取接口定义模式。

边界：不包含实现逻辑。如果出现函数体——应属于第 5 层。契约反映第 1-3 层同意的设计，不多不少。设计中未包含的工具函数、辅助方法、便捷包装器不属于此处。第 3 层的每次交互必须对应至少一个接口或类型；第 4 层不得出现第 3 层未同意的交互。

检查点："第 4 层（契约）看起来正确吗？我可以进入第 5 层（实现）吗？"

第 5 层：实现（Implementation）——"编码"

目的：编写代码。基于已同意的契约、在已同意的组件边界内、遵循已同意的交互模式进行实现。

输出格式：满足第 4 层定义契约的可用代码。每个组件在已同意的边界内实现。实现可被审查——审查者检查每个组件是否符合第 2 层描述、每次交互是否符合第 3 层流程、每个接口是否符合第 4 层契约。

边界：仅在明确批准第 4 层后才开始。实现遵循设计；不引入新组件、新交互或新契约。

零实现规则（The Zero Implementation Rule）

最关键的纪律：设计未获同意前，不写代码。

如果发现自己正在第 5 层批准之前编写函数体——停止。返回当前设计层级，仅呈现该层级适当的输出。

此规则存在是因为 AI 训练优化为快速产出有形输出，意味着 AI 不断试图压缩层级——提供已附带代码的组件图，或提出已附带实现的契约。坚守当前抽象层级的纪律保护工作记忆免受过早细节干扰，保持对话聚焦于正在做出的决策类别。

最简单版本：设计未获同意前不写代码。其他一切由此衍生。

复杂度校准

并非每个任务都需要全部五个层级。框架随工作复杂度缩放——是管理复杂度的工具，而非对每项工作都机械应用的仪式。

任务复杂度	从第几层开始	示例
简单工具类	第 4 层（契约）	日期格式化器、字符串辅助函数
单组件	第 2 层（组件）	验证服务、API 端点
多组件功能	第 1 层（能力）	通知系统、支付流程
新系统集成	第 1 层 + 深入第 3 层	第三方 API、事件管道

当从较后层级开始时，前面层级已隐式同意——范围和组件足够明显，无需显式对齐。

入口评估

在产出第一层输出之前，声明入口层级及理由：

"基于 [复杂度信号]，我将从第 [N] 层（[名称]）开始。前面层级已隐式同意——[简要说明假设内容]。想从这里开始还是更宽泛一些？"

等待确认后再产出第一层输出。如果用户不同意，调整入口点。

层级完成协议

在每个层级结束时：

1. 按该层指定的格式呈现层级输出（编号列表、图表、序列流程或接口）。
2. 自检：是否过于复杂？如果存在更简单的替代方案，一并呈现："我有一个更简单的选项——[替代方案]。你偏好哪个？"
3. 询问门禁问题："第 [N] 层看起来正确吗？我可以进入第 [N+1] 层吗？"
4. 等待明确批准后再前进。不因沉默或模糊而自动推进。
5. 如果用户重定向、纠正或提出疑虑——修订当前层级。未获批准前不推进。

每个层级约束下一层的决策空间。跳过层级或未获批准就前进意味着约束未建立，后续层级会漂移。

跨层输入：如果用户提供属于较后层级的细节（例如在第 2 层期间提供交互细节），予以确认——"好想法，我将在第 [N] 层（[名称]）捕获那个信息"——并继续当前层级。不要忽略或拒绝。

回溯：如果较后层级揭示前面层级的缺口（例如在第 3 层交互中发现缺失组件），指出缺口，提出对前面层级的修订建议，获得修订批准后再恢复当前层级。

第 5 层的范围扩展：如果在实现期间用户请求新范围，评估影响。如果影响组件或交互，提议回退到受影响层级进行对齐。如果纯粹是实现细节（日志、配置），直接纳入。

中途退出：如果用户在设计未完成时说"跳过到代码"或"直接实现"，在继续前承认权衡："跳过第 [N] 层意味着 [未对齐的内容]——我将在实现过程中标记任何注意到的设计缺口。现在继续。"然后实现。不拒绝或阻止；标注风险后继续推进。

简洁性检查（每个层级）

主动抵制不必要的复杂度：超出范围的能力、可以合并的组件、无价值的交互步骤、包含无人请求的工具函数的契约。首先呈现更简单的替代方案。让用户选择增加复杂度，而非由 AI 移除。

这不是设计后的顾虑——是每个检查点的主动纪律。每项新增都必须审查、测试、维护。更简单更好。

反模式（Anti-Patterns）

常见的压缩渐进式结构的违规行为：

反模式	症状	修复
层级压缩	组件描述附带实现代码	移除代码，回到仅组件边界
范围蔓延	第 1 层列出需求中不存在的能力	移除未请求的项目，确认范围
过早细节	第 2 层包含序列图或数据流	将交互细节移至第 3 层
镀金	契约包含设计中未要求的工具函数	移除；契约反映设计，而非额外功能
跳过层级	从第 1 层直接跳到第 4 层	后退；每个层级约束下一个层级
静默推进	未获明确批准就进入下一层	始终询问门禁问题并等待
功能注入	添加无人请求的速率限制、分析或钩子	移除未请求的功能；设计已请求的内容