product-from-scratch

从零打造产品

在代码限制设计之前，先决定用户会看到什么、做什么：用户是谁、预期结果是什么、旅程如何展开、有哪些交互、状态、失败情况和恢复方式。当实现暴露出真实约束时，应重新审视负责该约束的决策，而不是围绕代码重新设计。

成本规则

1. 设计投入应与后果和未解决的不确定性相称。对于普通改动，设计成本应明显低于重复实现两次的成本。
2. 每件产物和每个字段都必须促成不同的决策或改进验证。若某项反复无法做到其中任何一项，就将其移除。
3. 撰写任何内容之前，先复用现有规范。涉及界面不意味着必须新建文档。

如果工作不断增加，却没有解决决策或降低合理的风险，就精简流程。流程缺陷绝不能靠再加一层流程来修复：不要添加清单文件、哈希值、计算得出的状态、审批记录、证据分类体系、审查机制或产物配额。文档 lint 只能验证形式，不代表设计获得批准。

决策链

BRD  when business intent changes
PRD  when product behaviour changes
XDS  when a material experience decision exists
SDD  when a material technical decision exists
then implementation, then verification

仅当某一层确实存在相应决策时，才使用该层。有条件地使用可以避免制作空文档，但不能因此搁置决策。新增能力或跨界面旅程通常需要用到所有层。

产物	适用情形	负责内容	不得负责的内容
BRD，业务需求	业务意图、目标用户、预期结果、范围或不可妥协的品质发生变化	工作值得存在的原因、用户和业务预期结果、可接受的投入、不得牺牲的品质	控件、布局、文案、颜色
PRD，产品需求	新能力或实质性的行为变化需要明确且持久的规则	产品故事、规则、数据、权限，以及成功、失败、中断、恢复和返回时必须满足的预期结果与不变量、可观察的验收标准	控件选择、交互编排、布局、文案、层级、动效、技术实现
XDS，体验设计（PR 中的简短 UX 说明也算）	新旅程或发生实质变化的旅程、衔接点、层级、状态模型、共享控件或交互选择需要设计	旅程、状态与转换、控件与事件、文案、反馈责任归属、保留内容、重试、返回、响应式布局、动效、替代方案	新的业务或产品需求、技术实现
SDD，解决方案设计	架构、数据、安全、部署、性能或跨模块行为需要持久的技术决策	架构、API、持久化、性能、安全、技术故障处理	重新设计体验

顺序与权责：

• 业务意图先于产品行为，产品行为先于其体验，两者都先于技术实现。纯技术类 SDD 无需 XDS。
• PRD 说明产品必须做什么。XDS 说明用户如何完成流程、理解过程并从中恢复。设计中发现的产品规则应写入 PRD，绝不能写入 XDS。
• 可行性冲突应重新审视负责该问题的产品或体验决策。技术工作可以揭示约束并提出选项，但不能替用户决定面向用户的解决方案。
• XDS 的范围应按完整连贯的旅程或界面系列划分。一份 XDS 可以服务多份 PRD，一份 PRD 也可以出现在多个旅程中。
• 当前实现、研究和测量结果都属于证据。它们可以为目标提供参考，但不能定义目标。目标与实际构建记录必须分开。

动笔之前，先明确决策，并且只阅读负责该决策或对其构成约束的产物。仅当决策发生变化时才修订规范。应链接到负责该决策的陈述，而不是重复表述。对于没有文档体系的遗留产品，小型修复无需先补齐历史文档：将最小限度缺失的决策写入 issue 或 PR；只有当某项决策必须在本次改动之后继续有效时，才创建持久规范。

比例原则

变更	最少需要的有效材料
不影响用户可见内容或交互	无，除非业务、产品或技术决策本身需要持久记录
小型维护变更	在 issue 或 PR 中说明：参与者和任务、当前故障、预期行为、受影响的可达状态、保留的上下文、恢复和返回规则、可观察的验收标准。链接现有需求和测试，而非重复描述
新增能力或实质性行为变更	新增或修订 PRD。当变更引入或改变用户旅程、交界点、层级、状态模型、共享控件或交互选择时，新增或修订 XDS 材料
新增或实质性变更的用户旅程或跨界面交界点	按遍历顺序编写一份 XDS，仅涵盖该用户旅程所需的决策
影响重大的技术选择	一份 SDD

没有篇幅配额。使用足够轻量的材料，同时确保没有重要决策被隐去。 只有较轻量的材料未能促成决策时才升级。要求增加文档本身不是理由。

体验提示

使用能解决变更问题的提示，其余提示无需说明即可省略。

1. 产品故事：谁，在什么情境下，做什么，以实现什么结果。
2. 体验主张：仅适用于新功能或用户旅程：用一句话指出已确定的方向，以及用户应该记住的一件事。如果这句话原封不动地也能用来描述竞争对手的产品，那就还没有形成主张。
3. 用户旅程：入口、关键时刻、完成、返回或恢复。
4. 交互场景：明确命名控件和事件、可见响应、终止状态，以及绝不能发生的情况。将感受描述为可观察的数值：在 100 ms 内确认输入，1 s 内完成或进入经过设计的慢速状态（经典响应时间限制），明确并限定动态效果的特征。没有具体数值支撑的形容词只是愿望。仅在影响重大的关键节点比较备选方案，并用一句话说明落选方案为何未被采用。
5. 状态模型：会改变用户所见或可执行操作的可达状态。
6. 恢复：故障后保留什么、丢失什么、可以重试什么，以及重试入口在哪里。
7. 验收：可供他人实际验证的可观察场景。

当布局、信息密度、动态效果、时序或响应式适配影响决策时，应提供状态板、模拟稿或原型。对于新的界面或用户旅程，起始状态、关键交互、故障与恢复，以及完成状态都属于视觉主张，因此应将它们呈现出来。

语法

当上下文、投入、放弃或证伪可能改变决策时，传统的故事描述（“作为一名创作者，我想添加我的游戏，以便玩家能够找到它”）过于笼统。

STORY        <id>
As           <actor>
in           <context: first-run, returning, signed-out, empty account, ...>
I            <the task, independent of route, schema, or control>
so that      <the business or personal outcome>

Arrives at   <the observable state that constitutes success>
Abandons at  <plausible exit points and what makes leaving plausible>
Effort       <inputs, decisions, context switches, external tools; quantify when useful>
Falsified by <the observation that disproves the story>

只有在完整语法中的各行能促成决策时，才使用完整语法。局部维护变更只需说明参与者、任务、预期结果和验收标准。不具备有意义退出方式的原子操作无需添加 Abandons at 行。

故事本身不会决定控件。将重要故事映射到交互中：

SCENARIO     <id, linked to the story when one exists>
Starts in    <state and context>
User         <activates a named control or performs a named event>
Immediately  <visible response>
While        <pending, slow, or interrupted behaviour, when applicable>
Succeeds as  <terminal state>
Fails as     <truthful failure state, when reachable>
Recovers by  <durable action and preserved context>
Returns to   <resume, back, refresh, authentication return, later return, when material>

如果场景遗漏了重要控件、响应、终止状态或可达的恢复方式，就说明交互的这部分尚未设计。

状态提示词

作者往往会省略自己没有想到的状态。针对一段关键旅程，扫描以下四个维度，并选用会改变受影响体验的维度。

维度	检查项	例如会产生
数据	值：缺失、不完整、无效、达到上限。集合：零个、一个、几个、非常多	空账户、填写一半的表单、超出限制的标题
时间	异步操作：等待中、缓慢（超过 1 s）、成功、失败、已被取代、重复、延迟完成	缓慢状态提示、提示消息消失后的持久结果、丢弃过时的完成结果
路径	值的来源和中断：手动输入、恢复、默认值、获取、已认证、刷新	过时预填值的有效性、绕过认证后草稿仍完整
界面	支持的宽度、输入模式和内容极限	窄视口适配、最长标签、加载失败的图片

只记录会改变用户可见行为或带来合理失败可能的可达状态。只有在某个合理状态被有意排除，且说明理由能避免歧义时，才记录排除项。切勿枚举笛卡尔积，也不要声称覆盖了所有情况。

对于每个受影响的控件，都要确定键盘、指针和触控行为；焦点的放置与恢复；以及方向、安全区域和宽度方面的行为。这些都是常规交互决策。

逆向分析症状

观察到的情况	判断
成功状态只显示在提示消息中	时间。成功应显示在持久的结果状态中；提示消息至多起到强调作用
等待超过 1 s，却没有任何确认	时间。缓慢状态是经过设计的状态
错误在有效预填、恢复或修正后仍然存在	路径。显示判断结果后，必须告知用户何时可以离开
失败显示为死胡同	恢复。重试入口应位于失败显示处，且不能随提示消息一起消失
页面先出现，然后重新排列	使用近似最终结构的骨架屏。加载指示器会隐藏页面布局（references/vocabulary.md，loading）
在窄宽度或最长的实际标签下出错	界面。内容极限是测试输入
规范单独写了“下拉菜单”“模态框”“选项卡”或“提示消息”	尚未做出决策（references/vocabulary.md）

选择并命名控件

控件选择取决于任务，而非架构类型：

1. 复用审查：产品中的其他地方如何解决相同任务？由哪个组件负责？除非任务存在实质差异，否则应沿用产品的交互规范。
2. 检索方式：用户是回忆某个值，还是从一组值中辨认？
3. 数量与比较：有多少个选项？用户对它们有多熟悉？是否必须并排比较？
4. 现实中的数量：根据现实情况先确定是一个还是多个，再考虑架构。
5. 辅助方式：该值能否获取、推导、设为默认值或提供建议？架构要求绝不能成为让用户手动抄录的理由。
6. 控件名称应准确到足以体现其行为。references/vocabulary.md 定义了那些名称：选择这些名称会改变行为、状态、输入模型或恢复方式。名称存在歧义时，请查阅该文件；它只是供查阅，不会产生任何义务。如果没有适用的通用名称，项目可以定义本地术语。

持久交接

下一位 Agent 只能看到仓库和议题或 PR。交接前，将所有对后续工作至关重要的信息放在一个持久位置：用户及预期结果；当前故障或决策；选定的行为和交互；受影响的状态、保留、恢复、中断和返回；非目标；可能导致决策被推翻的已接受和已否决方案；可观察的验收标准和实际执行的验证；已知缺口和受阻的检查。

链接到负责的文档，而不是重复其内容。规范性文档说明当前目标；PR 保留决策缘由、被否决的方案和偏差。绝不要写“参见聊天记录”，也不要让关键决策只留在私人推理中。如果公开评审结论发生变化，请明确更正 PR 讨论串；静默编辑无法修复其他 Agent 已经读到的交接内容。

评审

评审产品决策。产物的存在本身不能证明任何事情。

• 在给出公开结论之前，完整阅读分支中的每个变更过的产品或设计文件。Diff、lint 和链接检查只能验证机制。
• 有用的评审意见会指出缺失或错误的面向用户的决策，并给出证据。
• 新功能或新流程应由未参与编写的人进行一次设计评审，并提供判断其视觉和时间决策所需的渲染结果。小改动进行常规 PR 评审即可。
• 修正后重新检查具体问题。不要进行评审的评审，也不要设立收敛流程。
• 负责人批准方向后，就按该方向执行。只有在负责人改变方向、需求得到更正、出现重大约束，或具体证据表明决策错误、不可行或不安全时，才重新审视设计。

验证

设计可以先于实现准备就绪。只有结果确实可用，改动才算完成。

• 在有代表性的宿主环境中实际体验受影响的流程，包括可触达的失败、恢复、中断和返回路径。正常流程的截图或 HTTP 状态码都无法验证交互，静态图也无法验证动效。
• 仪器化体验会测量设计承诺的时长、状态和动效属性。对体验感受的最终判断来自实际使用产品的人。如果此人不同意结果良好的体验测试，说明设计遗漏了一项承诺；应补充能发现问题的指标。
• 运行仓库要求的检查和与改动相关的测试。测试不能取代实时验证。
• 如果无法体验某个宿主环境或衔接点，请在 PR 中记录确切的未验证场景，并且不要声称已经完成。
• 如果主要的不确定性在于用户是否理解或感受到的操作成本，应尽可能观察有代表性的用户；否则记录假设和后续行动。更多文档无法回答这个问题。
• 面向读者的文档应进行受众适配检查：项目以外的读者有哪些内容看不懂？产品文档中应避免工作流行话。
• 机器检查只负责机械性事项：链接有效、ID 唯一、引用的文档存在、格式可解析。

构建时的润色（圆角、缓动、交错、按压状态、视觉对齐）属于开始制作时加载的工艺技能。本方法不重复这些内容。

完成定义

准备实现：

1. 仅按链路顺序创建或修订决策所需的产物。
2. 用户、任务、结果和可观察的验收标准足够明确，可以证伪该决策。
3. 在变更涉及交互、状态、保留、恢复、中断、返回、投入、放弃和非目标时，均已明确相关决策，且没有任何故事选择控制方式。
4. 已考虑数据、时间、路径和画面，且未使用完整性清单。
5. 评审者已呈现并检查视觉和时间决策。
6. 其他 Agent 仅凭仓库就能找出起决定作用的决策和已知缺口。
7. 删除了所有未促成任何决策的内容。

已实现：

1. 实现保留了所选体验；约束没有在未明说的情况下改写体验。
2. 已在有代表性的宿主环境中演练真实流程及其失败和恢复路径，或者已记录未经验证的衔接点，且未声称已完成。
3. 已运行必需的检查和相关测试；已记录受阻的检查。
4. 面向读者的文档描述了当前目标，并通过了受众适配审阅。