用途
设计说明文档（Design Rationale）用于记录设计决策背后的“为什么”——即背景、约束、考虑过的替代方案以及导向特定方案的推理过程。设计本身展示“做了什么”，而说明文档保留“为什么这样做”的机构知识。
适用场景包括：做出影响用户体验的重大 UX 决策时；设计评审前准备相关方讨论时；存在多个可行方案且需要为选择提供依据时；帮助新成员了解既有设计决策时；回顾过往决策以理解原始推理时；在设计系统演进过程中记录模式选择时。
不适用场景：决策属于架构或技术选型，应使用 develop-adr（Nygard 格式）；需要相关方对整体解决方案方向达成一致，应使用 develop-solution-brief；记录的是探索发现而非决策，应使用 develop-spike-summary；决策可轻易逆转且影响很小，撰写说明文档会增加额外流程负担，此时在 PR 或工单中记录推理即可。
主要能力
该技能指导产出结构化的设计说明文档，文档应覆盖以下内容：
- 决策摘要：用一句话清晰概括所做的设计决策，作为文档标题和参照点。
- 背景：说明促使该决策的情境、要解决的问题、存在的约束、影响方向用户需求，以及相关研究发现。
- 考虑过的备选方案：记录至少 2 到 3 个评估过的替代方案，描述每个方案的形态和关键特征，公平对待所有选项，避免稻草人论证。
- 评估标准：明确如何评估各选项，例如可用性启发式、技术可行性、品牌一致性、用户研究发现、业务需求或设计原则。
- 决策理由：说明所选方案为何最符合标准，明确权衡取舍——获得了什么、牺牲了什么，并说明决策是可逆还是不可逆。
- 接受的权衡：命名放弃了什么以及为何可以接受，这种坦诚有助于后续团队理解约束。
- 后续考虑事项：记录需要后续关注的内容，例如需要观察的指标、可能需要重新审视决策的条件，或相关待做决策。
使用方式
当被要求记录设计说明时，按以下步骤进行：陈述决策、描述背景、列出考虑过的选项、定义评估标准、解释推理、记录接受的权衡、注明后续考虑事项。输出时使用 references/TEMPLATE.md 中的模板组织结构，完整说明应填满模板每个部分：Decision Summary、Context、Options Considered、Evaluation、Decision Rationale、Trade-offs Accepted、Reversibility、Follow-up Considerations、Supporting Materials 和 Decision History。参考资料 references/EXAMPLE.md 提供了完整示例。
质量检查
定稿前需验证：决策是否用一句话清晰陈述；背景是否解释了“为何是现在”及约束；是否公平记录了多个备选方案；评估标准是否明确；推理是否说明所选方案为何优于替代方案；权衡是否坦诚承认；接手该设计的读者能否在不询问任何人的情况下重建所选方案胜出的原因。
限制
该技能聚焦于 UX 与设计决策的说明记录，不用于架构决策、技术选型、整体方案方向对齐或探索发现总结等场景，这些应使用对应的其他技能。对于可轻易逆转、低影响的决策，不建议使用本技能，以免增加不必要的流程负担。