愿景——产品是什么，以及它拒绝成为什么
属于 super-ux 的一部分——参见 system-map.md 了解完整流程。编写本文档后，运行
python3 docs/ux/lint.py。
位于 ux-foundation 之上的一层。基础回答了谁使用产品以及为什么；愿景回答了产品是什么以及它拒绝成为什么。没有愿景，“我们应该构建这个吗？”就没有一个比最后一个有意见的人活得更久的答案。
不要将其与 scenarios.md 混淆，后者的名字也以“什么”开头：场景详细说明了产品做什么，一步一步地。一个功能可以完美地场景化，但仍然违反反愿景。
此技能产出两样东西，第二样才是关键。
docs/ux/vision.md— 文档。- 项目自身指令文件中的一条愿景对齐规则，使得后续每个功能都会根据愿景进行检查，而不是让愿景被写一次后就再也不被阅读。
一份无人阅读的愿景只是一份文档，而不是一条约束。
适配链：愿景 → 基础（角色、JTBD、旅程、故事）→ 流程 → 场景 → 审计。 每一层都追溯到其上一层。
步骤 0——阅读项目，而不是其 README
在写下任何文字之前：
README.md，ARCHITECTURE.md，ROADMAP.md，CHANGELOG.md，以及docs/中的所有内容。- 关键源码：入口点，主要服务，模式定义，路由表。
- 营销材料（如果存在）——着陆页、定价、功能清单。
package.json/pyproject.toml/Cargo.toml，了解实际依赖项。- 实际的UI。产品的实际行为，而不是它声称的行为。
- 如果
docs/ux/foundation.md存在，请阅读它——愿景不得与已经确认的角色和任务相矛盾。
仅从 README 编写的愿景描述的是 README 本身。 项目声称的内容与其代码实际行为之间的差距通常是真正愿景所在之处，并且公开指出这一差距通常是此技能最有价值的地方。
步骤 1——转变
在编写之前，先在内部回答：
此产品存在前的用户 → [混乱 / 复杂 / 痛苦]
此产品存在后的用户 → [清晰 / 简单 / 力量]
以下所有内容都源于此。如果你无法陈述这一点，说明你对产品的了解还不足以编写其愿景——请返回步骤 0。
步骤 2——分九层编写 docs/ux/vision.md
每一层都是必需的。使用项目的文档语言编写。
1. 本质。 一句话。[产品] 是一种 [系统类型]，它改变了 [用户] [做 X] 的方式。不涉及功能名称、界面或技术。检验标准：如果产品在完全不同的技术栈上重建，这句话是否仍然成立？ 如果不成立，那么它命名的是一个实现，而非本质。
2. 核心设想。 不是一个问题陈述——而是对世界的一种观察。
[X] 是丰富的。
[Y] 是稀缺的。
→ 此产品弥合了鸿沟。
一个观察，而不是一个列表。“信息是丰富的，清晰是稀缺的。”
3. 系统做什么。 持续的行为，动词而非名词：观察……理解……转换……呈现……。不涉及功能名称。“拥有仪表盘”不是行为；“呈现不同来源之间的矛盾”才是。
4. 用户的角色。 用户在使用产品时成为了什么。不是“用户点击”——而是用户引导、判断、决策。如果用户的角色与其他任何工具的用户无法区分，说明愿景还不够具体。
5. 原则。 三到五条，每条采用我们做 X，而非 Y 的形式，其中 Y 是合理团队实际可能选择的东西。没有否定替代方案的原则就是一句口号。
6. 反愿景。 此产品拒绝成为什么，明确写出。这是团队跳过的唯一一层，也是唯一能解决争论的一层。明确指出它可能漂移成的相邻产品，并对每个说“不”。
7. 远景。 未来两到三年内的发展方向，作为一个方向而非路线图。路线图属于追踪器，一个季度就会过时。
8. 一句话总结。 如果有人只记得一件事，那就是这个。
9. 对齐测试。 三到五个任何提议的功能都必须通过的问题。这些正是第 4 步中的规则将实际运行的内容。
步骤 3——在交付前验证
检查每一项，如有问题则修复而非合理化：
- 本质能在不同技术栈上完全重写的情况下保持不变
- 没有任何一层命名了一个功能、一个页面或一个供应商
- 反愿景提到了真实的替代方案，而非稻草人
- 原则有一个被否决的一方，且该方是有人可能会真正选择的
- 没有任何内容与
docs/ux/foundation.md相矛盾——如果有，这是一个需要提出的发现，而不是默默掩饰 - 一个陌生人可以使用对齐测试来拒绝一个看似合理但实则有问题的功能
步骤 4——安装对齐规则
将该规则写入项目自己的指令文件，与 ux-rule 使用的文件相同：Claude Code 使用 CLAUDE.md，Codex 和 opencode 使用 AGENTS.md，Gemini 使用 GEMINI.md。检测项目已有的文件；仅在没有任何文件存在时创建 CLAUDE.md。切勿硬编码某个代理的路径——一条安装在正在运行的代理无法看到的文件中的规则比没有规则更糟糕，因为每个人都认为它已经被覆盖了。
幂等性：如果标题已存在，则就地更新该块，而不是追加第二个副本。
## 愿景对齐——硬性规则（super-ux）
在计划任何新功能、能力或重大更改之前，请根据 `docs/ux/vision.md` 对其进行检查——特别是**反愿景**和**对齐测试**。
**对齐** → 继续，并用一行说明它服务于愿景的哪一部分。
**未对齐** → 在编写代码之前停止并说明原因：
1. 指出冲突所在——它与哪一层相矛盾，并引用该层的内容。
2. 提供两条路径：(a) 重塑功能以使其符合，附上具体更改；(b) 修改愿景，说明哪些层发生更改及其代价。
3. 等待决策。不要默默选择其中一个。
**对于以下情况请勿触发：** 错误修复、重构、依赖项工作、测试、文档，或任何没有用户界面的内容。对一个拼写错误进行愿景检查，是团队学会跳过重要检查的方式。
步骤 5——在 README 中指向它
在项目概述之下添加一行，链接到 docs/ux/vision.md。从正门找不到的愿景，就是没人读的愿景。
常见错误
| 错误 | 为何会出问题 |
|---|---|
| 本质命名了技术 | 第一次重写时就不再成立 |
| 原则没有否定的一边 | “我们重视质量”无法解决任何争论 |
| 没有反愿景 | 唯一能决定范围的那一层缺失了 |
| 远景写成路线图 | 一个季度后过时，然后整个文档都显得过时 |
愿景与 foundation.md 矛盾 | 两个真相来源，团队会遵循他们最后读到的那一个 |
| 规则安装在某个代理的硬编码路径下 | 对实际正在运行的代理不可见；没人注意到，因为缺失看起来和合规一样 |
| 仅从 README 编写 | 描述的是 README 本身 |