setup-ux

配置 UX

为未来的 UX 工作做好准备，从意图和证据出发，而不是凭猜测行事。

始终遵循

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

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

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

选择配置路径

判断这是新项目还是现有项目。根据现有项目内容明显判断路径。如果无法判断，就简短询问一个问题：这是新项目／产品，还是要处理现有项目？

不要创建第二个配置技能。两条路径最终都应形成同一套精简的 .ux/ 上下文层。

新项目：通过对话明确意图

目前可能还没有多少有用的项目证据，因此先请用户用自己的话描述想法。只询问下一个可能实质影响设计的问题。

视需要厘清以下方面：

• 为什么要做这个项目，以及希望改善什么或实现什么新可能；
• 影响哪些人，以及他们需要完成什么；
• 核心体验或用户旅程；
• 当前范围和明确的非目标；
• 已知的限制条件；
• 如果已有定义，成功的标准是什么；
• 可用证据，以及假设和未知事项。

每次提出一个问题或少量相关问题。不要照固定问卷提问，也不要要求每个标题都填写完整后才能开始工作。

当意图具体到足以指导决策时，先编写 .ux/INTENT.md。向设计人员展示有用的归纳内容，并以他们的修正为准，覆盖推断。

现有项目：重建意图前先检查

在提问前，先探索代码库和关联来源。检查可用内容：README 和产品文档、现有用户研究、分析与支持证据、包文件、Storybook、组件、令牌、设计系统文档、Figma 或其他关联的设计来源、无障碍指南、问题／PR 模板，以及现有决策。

根据权威证据重建产品意图草案，但要将当前行为与预期结果分开。代码可以证明某个流程存在，但通常无法证明组织为何选择这种设计。

只针对重要的信息缺口、冲突，或无法可靠确定的意图提问。不要向用户询问你可以自行查明的信息。

如果旧版 .ux/ 目录中只有 CONTEXT.md、DESIGN-SYSTEM.md 和 DECISIONS.md，请保留这些文件并添加 INTENT.md；不要仅仅为了匹配新结构而重写已经确定的上下文。

精简上下文

创建或更新最精简且有用的核心内容：

.ux/
├── INTENT.md
├── CONTEXT.md
├── DESIGN-SYSTEM.md
└── DECISIONS.md

阅读 references/context-contract.md，了解所有权、模板、证据状态、迁移、意图更新，以及项目何时有理由将上下文拆分为更小的文件。

INTENT.md

说明产品或能力存在的原因、预期结果、受影响的人群、核心任务/体验、当前范围与非目标、重要约束、已知的成功标准，以及重要假设或未知信息。

保持简短。它是指引方向的北极星，不是产品需求文档（PRD）。

CONTEXT.md

说明运行环境：可观察到的产品机制、主要用户旅程、证据存放位置、工程技术栈与工作流、无障碍预期、术语，以及有助于未来 UX 工作的稳定项目事实。

不要仅仅因为两个文件都提到产品，就重复说明产品意图。

DESIGN-SYSTEM.md

记录实际的设计系统来源与规则：Storybook、Figma、组件包、设计令牌、事实来源的优先顺序、复用预期和贡献流程。

DECISIONS.md

轻量记录重要 UX 或架构决策的索引。如果项目已有 ADR 或其他决策系统，请指向该系统，而不是再创建一个与之竞争的系统。

渐进式提供上下文

默认情况下，不要在设置期间创建研究资料库、人物角色库、用户旅程目录或约束文件夹。

只有在信息密度、重复使用或职责划分使拆分有益时，才将信息拆分到较小的文件中。对于确实需要的项目，可参考 .ux/users/tasks.md、.ux/evidence/research.md 或 .ux/constraints/accessibility.md。

未来的技能应在产品目的、预期结果、范围或成功标准可能影响答案时加载 INTENT.md，然后只加载与任务相关的其他上下文。不要将整个 .ux/ 目录视为每个请求都必须加载的上下文。

.ux/STATE.md 不属于设置流程，也不是第五个核心上下文文件。只有在连续性可能因此丢失时，未来的 Agent 才可为重要的多步骤工作创建此文件。它是可丢弃的工作状态，不是持久的产品事实。

允许信息缺失

不要因为存在未知信息而阻止设置。只有当答案会实质性改变未来建议时才提问。

绝不要把假设当作事实。当区分有意义时，应将关于人群、证据、需求、决策、意图和重要未知信息的说法标注为已知、推断、假设、未知或存在冲突；普通的产品机制无需标注。

谨慎更新意图

将 INTENT.md 视为稳定但非一成不变的文件。现有意图是默认依据，应在常规设计和实现工作中保持不变。

只有在明确的人类指示或权威证据表明产品目的、预期结果、受影响人群、范围、非目标、重要约束或成功定义确实发生变化时，才修改它。应做最小限度的必要修改，而不是重新生成整个文件。

如果只是小幅澄清，且能在不改变含义的情况下让已确立的意图更加明确，可直接在原处完善。重要变更应将其依据的决策或证据保留在 DECISIONS.md 或项目现有的 ADR/RFC 系统中。

绝不要为了合理化当前实现、删除不便的约束，或事后让已完成的工作显得与意图一致而重写意图。Agent 的推断本身不足以推翻已确立的意图。

以有用的方式结束

告诉设计师你了解到的内容、发现的少数重要缺口，以及对意图、用户上下文和设计系统的理解是否充分，能否开始工作。

然后停止。不要把设置变成审计或发现研讨会。