vision

愿景——产品是什么，以及它拒绝成为什么

属于 super-ux——查看 system-map.md 了解完整流程。写完文档后，运行 python3 docs/ux/lint.py。

位于 ux-foundation 之上这一层。Foundation 回答产品的使用者是谁以及为什么；愿景回答产品是什么以及它拒绝成为什么。没有愿景，“我们该不该开发这个？”就没有一个能够超越最后发表意见之人的答案。

不要把它和 scenarios.md 混淆，后者是另一个名称以“什么”开头的层：场景按步骤说明产品会做什么。一个功能即使场景描述得再完善，也仍可能违反反愿景。

这项技能会产出两样东西，而第二样才是重点。

1. docs/ux/vision.md——文档。
2. 项目自身的指令文件中的一条愿景一致性规则，让之后的每项功能都接受愿景检查，而不是让愿景只写一次就再也无人阅读。

无人阅读的愿景只是文档，不是约束。

适用于这条链路：愿景 → 基础（人物画像、JTBD、用户旅程、用户故事）→ 流程 → 场景 → 审计。 每一层都能追溯到上一层。链路设有口头退出选项：操作者说出**“no scenarios”** / «без сценариев»，即可跳过这些层继续，并明确说明。

触发条件

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

"vision" / "видение", "product vision" / "продуктовое видение", "what is this product about", "define product direction", "write a vision", 没有明确方向的新项目，感觉偏离战略的功能。

第 0 步——了解项目，而不是只看它的 README

动笔之前：

1. 阅读 README.md、ARCHITECTURE.md、ROADMAP.md、CHANGELOG.md 以及 docs/ 中的所有内容。
2. 阅读关键源代码：入口点、主要服务、架构、路由表。
3. 如果存在营销页面，也要查看——着陆页、定价、功能介绍。
4. 查看 package.json / pyproject.toml / Cargo.toml，了解项目实际依赖什么。
5. 查看正在运行的 UI。看产品实际在做什么，而不是它声称自己在做什么。
6. 如果 docs/ux/foundation.md 存在，就阅读它——愿景不能与已经达成一致的人物画像和待完成任务相矛盾。

仅凭 README 写出的愿景，描述的只是 README。 项目自称的定位与代码实际做的事情之间通常存在差距，而真正的愿景往往就藏在那里。坦率地指出这个差距，往往是这项技能最有价值的作用。

第 1 步——转变

动笔前，先在心里回答：

User BEFORE this product exists →  [chaos / complexity / pain]
User AFTER  this product exists →  [clarity / simplicity / power]

后续内容都由此展开。如果你无法说清楚，就说明你还不够了解这个产品，无法撰写它的愿景——返回第 0 步。

第 2 步 — 分九层编写 docs/ux/vision.md

每一层都是必需的。使用项目的文档语言编写——愿景的九个章节按其编号识别，而非英文标题：写成 ## 6. <你所用语言的标题>，绝不要省略编号。章节规范见 scenario-format.md → docs/ux/vision.md — 编写愿景前先阅读，因为检查器会根据编号进行匹配，缺少章节（例如反愿景）就会导致失败，无论使用哪种语言。

1. 本质。 一个句子。[产品] 是一种[系统类型]，改变了[用户][做 X]的方式。不要出现功能名称、界面或技术。测试标准：如果产品从头开始用不同的技术栈重建，这句话是否仍然成立？ 如果不成立，它描述的是实现，而非本质。

2. 核心理念。 不是问题陈述，而是对世界的观察。

[X] is abundant.
[Y] is scarce.
→ this product bridges the gap.

一个观察，而非列表。“信息丰富，清晰度稀缺。”

3. 系统的作用。 描述持续发生的行为，使用动词而非名词：观察……理解……转换……呈现……。不要出现功能名称。“有一个仪表盘”不是行为；“呈现不同来源之间的矛盾”才是。

4. 用户的角色。 用户使用产品时会成为怎样的人。不是“用户点击”，而是用户指导、判断、决策。如果用户的角色与操作其他任何工具毫无区别，这个愿景就还不够具体。

5. 原则。 三到五条，每条采用我们做 X，而不做 Y的形式，其中 Y 必须是一个合理的团队确实会选择的做法。没有明确舍弃方案的原则，只是口号。

6. 反愿景。 明确说明本产品拒绝成为什么。这是团队会跳过的一层，也是唯一能真正解决争论的一层。指出产品可能演变成的相邻类型产品，并逐一明确拒绝。

7. 远景。 描述两到三年后的发展方向，而非路线图。路线图属于跟踪工具，而且一个季度内就会过时。

8. 那句话。 如果有人只记住一件事，那就是这句话。

9. 对齐测试。 列出三到五个问题，任何拟议功能都必须通过。这些问题会用于执行第 4 步中的规则。

第 3 步 — 发布前验证

逐项检查，并修正问题，而不是为问题找理由：

• 本质在完全重写并采用不同技术后仍然成立
• 每一层都没有提及功能、屏幕或供应商
• 反愿景指出了真实的替代方案，而非稻草人
• 原则有明确舍弃的做法，而且有人可能真的会选择那种做法
• 内容不与 docs/ux/foundation.md 矛盾——如果存在矛盾，应提出并记录，而不是悄悄掩盖
• 陌生人可以使用对齐测试来否决一个看似合理的功能

第 4 步 — 安装对齐规则

将规则写入运行中的 HOST 实际读取的文件——首先根据 HOST 的能力确定目标文件：Claude Code 使用 CLAUDE.md，Codex 和 opencode 使用 AGENTS.md，Gemini 使用 GEMINI.md。通过标记目录（.claude/、.codex/、.gemini/）检测当前 HOST；明确的项目目标文件（已包含该规则的文件）优先于默认文件。如果不存在任何目标文件，就创建当前 HOST 读取的文件——Codex 项目使用 AGENTS.md，Gemini 项目使用 GEMINI.md，仅当 HOST 是 Claude 或无法检测时才使用 CLAUDE.md。绝不要硬编码 CLAUDE.md——如果规则写入运行中的 Agent 看不到的文件，情况比没有规则更糟，因为所有人都会以为已经覆盖到位。

多 HOST 项目（存在多个标记目录）必须在每个活动 HOST 对应的文件中安装规则，并明确标记每个目标文件，确保没有 HOST 遗漏。

保证幂等：如果某个 HOST 的文件中已存在该标题，就原位更新规则块，而不是追加第二份；重复运行时不写入任何新内容。

## Vision alignment — hard rule (super-ux)

Before planning any new feature, capability or significant change, check it
against `docs/ux/vision.md` — specifically the **anti-vision** and the
**alignment test**.

**Aligned** → proceed, and say in one line which part of the vision it serves.

**Misaligned** → stop and say so before writing code:
1. Name the conflict — which layer it contradicts, quoting that layer.
2. Offer two paths: (a) reshape the feature to fit, with the specific change;
   (b) amend the vision, saying which layer changes and what that costs.
3. Wait for the decision. Do not pick one silently.

**Do NOT trigger for:** bug fixes, refactors, dependency work, tests,
documentation, or anything with no user-facing surface. A vision check on a
typo fix is how a team learns to skip the check that matters.

第 5 步 — 在 README 中添加链接

在项目概述下方添加一行，链接到 docs/ux/vision.md。如果没人能从项目首页找到愿景，那就没人会读它。

常见错误

错误	为什么会出问题
Essence 中写入了技术名称	第一次重写时它就不再成立
原则没有明确拒绝的立场	“我们重视质量”无法解决任何争论
没有反愿景	缺少了决定范围问题的关键层
将 Horizon 写成路线图	一个季度内就会过时，随后整份文档都会显得过时
愿景与 foundation.md 相矛盾	出现两个事实来源，而团队会遵循自己最后读到的那个
将规则安装在某个 Agent 的硬编码路径下	实际运行的 Agent 看不到它；没人会察觉，因为缺失看起来和遵守规则完全一样
根据 README 撰写	描述的只是 README