ux-scenarios

ux-scenarios — 维护场景库

属于 super-ux — 请参阅 system-map.md， 了解完整流程和四条同步规则。更改后，运行 检查器（python3 docs/ux/lint.py）。

没有用户行为模型就构建 UI，会让 AI 生成的界面变得糟糕。这项技能会维护这样一个模型：目标项目中的 docs/ux/scenarios.md 是所有用户可执行、可查看和可能遇到的内容的唯一事实来源——每项功能、每个按钮、每种状态、每个错误、每项结果。

格式契约： scenario-format.md （ux-contract v4）。编写或编辑场景前请先阅读。不得偏离其中的字段名称、ID 规则、状态或检查清单。

WHY 和 HOW 层： 当存在 docs/ux/foundation.md（角色、JTBD、用户旅程、故事——ux-foundation 技能）和/或 docs/ux/flows.md（任务分析、用户流程——ux-flows 技能）时，场景应从这些内容推导得出：每个流程对应一组场景，覆盖顺畅路径、每个错误分支，以及流程图中的每个备选分支；填写 Traces:，注明故事和流程 ID；执行可追溯性规则（每个 must/should 故事都要有覆盖；每个流程节点/边都要有覆盖；每个场景都要服务于一个故事或任务——没有任何用途的场景应考虑删除，而不是实施）。步骤应采用用例风格编写：用户操作 -> 可观察到的系统响应。如果非小型产品缺少上层内容，请先建议使用 ux-foundation → ux-flows；只有对于小型项目或用户明确选择时，才以 v1 模式（不填写 Traces）继续。

设计品味： 编写预期结果和错误与恢复内容时，应用 ux-design-principles.md — 屏幕状态、错误恢复和主要操作规则。

触发条件

会将请求路由到此技能的英文和俄文短语。技能描述只保留其中最有代表性的触发词，以便技能列表不超出预算（2026-10-20）；系列路由钩子与此列表一致。

“ux scenarios” / “сценарии использования”、“use cases”、“new feature” / “новая фича”、新功能或项目规划、UI 更改。

硬性规则

1. 场景先于界面。新功能或新项目应从起草场景并与现有场景库核对开始，检查冲突、重叠和缺漏，并获得批准。只有之后才能设计和构建 UI。
2. 任何影响面向用户行为的更改，都必须在同一次更改中更新 docs/ux/scenarios.md。没有对应场景的新行为属于阻塞项，而非警告。

退出规则必须由用户明确提出，不得自行假定： 操作者通过说 “no scenarios” / «без сценариев» 选择不走此流程——此时不使用场景库继续，并在交付说明中注明，而不是悄悄跳过。

最佳实践： 起草或审查场景时，请查阅 best-practices.md — 根据匹配功能/用户旅程阶段（引导、付费墙、留存等）的标签和产品领域筛选。仅在有助于可追溯的任务/故事时应用某项实践；在场景的设计理由中注明已应用实践的 ID（BP-NNN）。目录会持续更新——新增经验证有效的实践时，按其中的“如何添加”规则追加。

选择工作流

情况	工作流
不存在 docs/ux/scenarios.md，代码很少或没有代码	Init（全新项目）
不存在 docs/ux/scenarios.md，但已有产品代码	Init（现有代码）
场景库已存在；正在添加/更改行为	Update
场景库已存在；对一致性有疑问，或出现新的功能想法	Validate

说明你将运行哪种工作流。如果缺少 docs/ux/，请创建该目录，并使用此技能自带的 templates/scenarios.md 初始化 scenarios.md。

初始化（绿地项目）

场景在此处设计，不通过逆向工程得出。

1. 每次只问用户一个问题：有哪些用户角色？每个角色会因什么任务而选择该产品？核心功能是什么？绝不能让用户遇到什么情况？
2. 起草用户角色，然后按功能逐一编写场景。对于每项功能，满足单功能完整性检查清单（正常流程、所有错误流程、空状态、可见的加载状态、破坏性操作确认、回访用户变体）和格式契约中的产品级检查清单（从首次运行引导到多实体流程）。只有真实用户和真实数据才能确定用户角色或场景：合成用户角色、LLM“数字孪生”或模拟会话都只是待验证的假设，绝非证据（相关规则由 ux-foundation 的 research-evidence.md 负责）。
3. 所有条目的初始状态均为 Status: draft、Coverage: none yet、Product: unobserved。最后一项是结果状态，在收到来自现实世界的信号前，始终保持 unobserved——发布场景不会改变它，审核通过也不会改变它。
4. 按章节向用户展示基准内容以供批准。获批的场景状态改为 validated。
5. 只有在场景通过验证后，才能开始其所依赖界面的 UI 设计或实现，并以这些场景为依据。构建状态采用 ux-flows 的四状态机（full / provisional / tooling-degraded / declined）：即使缺少可选的 Figma，也可根据已批准的文本规格进行构建（延后同步画面）；严重的未知问题只会阻止依赖它的界面；此处记录的批准在每一层均有效，无需重新走完整流程。

初始化（现有代码）

基准内容必须涵盖所有现有内容，然后指出其中的缺口。

1. 全面盘点代码库（大型代码库可并行使用可用的子 Agent，每个 Agent 负责一个区域；如果不委派，则按相同的覆盖范围逐一检查）：路由和界面； 交互元素（按钮、表单、对话框、菜单）；状态分支（加载 / 空 / 错误 / 成功）；错误流程及用户看到的内容； 引导和首次运行逻辑；设置；多实体流程。
2. 根据盘点结果按功能起草场景，并在 Coverage: 中填写盘点时找到的 file:line 证据。
3. 在给用户的报告中明确指出两个方向的缺口：
   • 有代码行为却没有场景（即临时设计的行为——现在已记录下来）；
   • 有检查清单项目却没有对应代码（例如完全没有空状态）——将这些记录为 Status: draft、Coverage: none yet 的场景。
4. 按绿地项目第 4 步的方式提交验证。

更新

收到变更（差异、功能说明、错误修复）后：

1. 按功能和 UI 元素确定受影响的场景。搜索基准内容，不要依赖记忆。
2. 应用编辑：调整现有场景的步骤 / 元素 / 错误；为新行为添加场景；将不再成立的场景标记为退役（Status: retired + 一行原因）——绝不删除。
3. 变更后的场景状态恢复为 draft，直到重新获批；保持 Index 表同步。
4. 如果此次变更引入了经过本轮检查后仍不属于任何场景的用户可见行为，请停止并说明——该行为在发布前必须先确定对应场景。

验证

对基础内容进行一致性检查（在批准任何新功能创意前也要运行）：

1. 完整性： ID 按顺序排列且唯一；索引与条目一致；每个被引用的角色都已定义；状态均合法。
2. 覆盖： 每项功能都满足逐功能检查清单；产品满足逐产品检查清单。列出缺失项。
3. 可追溯性（当 foundation.md 存在时）：每个 must/should 故事至少有 1 个场景；每个场景都可追溯到至少 1 个故事或任务；每个有产品触点的旅程阶段至少有 1 个场景。任一方向上的孤立项都属于发现项。
4. 冲突： 相互矛盾的场景（相同入口点、结果不兼容；相同元素、行为不同）。对于新的功能创意：先根据基础内容进行验证（它服务于哪个任务？对应哪个旅程阶段？），再根据现有场景进行验证——在开展任何 UI 工作前，先提出协调方案。若创意不服务于任何任务，应提出质疑，而不是默默接受。
5. 将发现项以清单形式报告，并为每项提供修复方法；应用已批准的修复。

基础内容中的主持式测试任务（按需提供）

对于多屏旅程，建议在基础内容旁提供可点击的场景预览；用户提出要求时，这就是一项交付物。遵循 interactive-flow-prototypes.md。 该预览可在正式批准前完善草稿场景：将每个案例追溯到屏幕状态和转换，包含替代、错误和恢复路径，并将声明的覆盖范围与实际点击体验分开。模拟成功不会改变实施覆盖范围或产品结果状态。

场景本身就符合可用性测试任务所需的形式：一个情境、一个目标和一个可观察的成功条件。将场景改写为任务只是重写，不是新产物——因此，当有人准备与用户进行测试时，应从基础内容生成任务，而不是从头编写。

对于范围内的每个场景：

• 场景——使用参与者的措辞描述情境，而不是产品的措辞：“你刚从同事手中接过一个项目”，而不是“打开 SCN-014”。
• 目标——说明他们想要实现什么，不要提及用于实现目标的 UI。“找到设置”会引导任务；“更改通知的发送位置”才是任务。
• 成功——采用场景“预期结果”中描述的可观察最终状态。

确保任务真实的规则：措辞中不得出现界面上的动词（例如“点击”“轻触”“X 按钮”）；先安排热身任务，最后安排边缘案例；每个场景对应一个任务——需要两个目标的任务就拆成两个任务。如果场景包含替代或错误路径，就将它们作为压力测试任务。

测试结果应根据同一份基础内容进行评估：无人完成的任务是针对其场景的发现项，而不是针对参与者的发现项。参与者是真实的人；以某个角色身份作答的模型不是参与者，其完成情况也不是测试结果。

完成定义

• 索引、角色和条目保持同步；遵守格式约定。
• 用户已查看并批准新增或修改的场景（validated）。
• 诚实报告缺口和冲突——绝不默默略过。

references/ 中还有什么。 此技能直接引用了 5 份约定；references/ 中共有 13 份，因为此技能引用的约定还会链接到其他约定，而完整的依赖闭包都包含在此技能中——skills CLI 安装的是一个目录，如果引用同级目录中的文件，该文件就会缺失。打开此处命名的文件；其余文件会在约定要求时按名称从中找到。