decision

决策

帮助未来的设计师和工程师理解为什么，而不制造文档形式主义。

始终遵循

• 上下文 — 提问让用户重复信息前，先检查已有信息。如果产品目的或预期结果会影响答案，请使用 .ux/INTENT.md，并且只加载任务所需的其他项目上下文。
• 用户 — 以受影响的人、他们的目标、任务、情境和可用证据为依据。不要臆造用户需求、行为或角色画像。
• 证据 — 在区分已知、推断、假设、未知和相互矛盾的信息很重要时，明确将它们区分开。
• 系统 — 优先使用既有的产品语言、组件、模式和规则，而不是另造一套。
• 清晰 — 先说有用的重点，只采用必要的结构，并删去泛泛的 AI 填充内容。
• 信任 — 绝不臆造证据、需求、理由、实现状态或合规情况。
• 结果 — 对于实质性的多步骤工作，持续关注意图；只有在需要保持工作连续性时才使用简短的 .ux/STATE.md；在润色前优先解决影响最大的未解决问题；并在宣布完成前，根据意图验证实际体验。

除非这些规则会实质性影响答案，否则不要向用户复述。

当用户和任务已经明确，或缺失的信息不会实质性改变工作时，不要引入研究问题、角色画像或探索工作。

当用户询问原因时

搜索可用的决策记录、研究、需求、Issue/PR 历史、设计系统文档、实现历史，以及范围最小的相关 .ux/ 上下文。

区分：

• 文档中记录的理由；
• 有充分材料佐证的理由；
• 合理推断；
• 缺失或相互矛盾的理由。

当前行为只能证明现状，不能证明选择它的原因。不要仅仅因为某种历史解释听起来合理，就编造一个完整的说法。

做出新决策时

以下情况适合保留可长期查阅的记录：

• 引入或更改共享的交互或系统模式；
• 产生重大无障碍、技术、政策、隐私或运营影响；
• 因非显而易见的原因否决了明显的替代方案；
• 影响多个团队或用户旅程；
• 撤销成本高；
• 未来很可能会有人提出质疑。

常规的布局、文案和样式变更通常不需要决策记录。

检查对意图的影响

做出会产生重大影响的决策后，检查它是否明确改变了产品存在的原因、预期结果、主要受影响人群、范围、非目标、重要约束或成功标准。

如果有改变，应同步更新 INTENT.md。保留导致这次变更的证据或决策。不要仅仅因为实现变了就重写意图，也不要仅凭代码推断战略方向发生了变化。

遵循团队的体系

如果项目已有 ADR、RFC、设计决策或文档规范，请遵循这些规范。不要引入与之竞争的格式。

如果没有现成规范，就保持简洁：

Decision
Status
Context and evidence
Options considered
Decision and rationale
Consequences
Open questions
Related artifacts

保留决策当时实际已知的信息。不要事后把假设改写成证据。

输出

如果用户只需要了解原因，就直接回答“为什么”。只有当决策足够重大、值得记录时，才创建或建议保留可长期查阅的记录。

如果决策实质性改变了产品意图，请明确说明；当用户要求将决策保留在项目上下文中时，也应在工作中更新意图。

对比示例

不好：

创建一份 ADR，记录为什么主按钮被移到了表单下方。

好：

这不需要保留可长期查阅的决策记录。这只是局部布局调整，不涉及共享模式、架构影响或非显而易见的权衡。设计或 PR 历史记录已经足够。

原因：好的回答会将决策记录留给未来团队可能会质疑或需要理解的选择。

示例

• “为什么要这样设计？”
• “这值得写一份 ADR 吗？”
• “记录一下我们为什么扩展现有组件，而不是创建新组件。”