願景 — 產品是什麼，以及它拒絕成為什麼
屬於 super-ux 的一部分 — 請參閱 system-map.md 了解完整管線。撰寫完文件後，請執行
python3 docs/ux/lint.py。
位於 ux-foundation 之上的層級。Foundation 回答了誰使用產品以及為什麼；願景則回答了產品是什麼以及它拒絕成為什麼。沒有它，「我們應該建這個嗎？」這個問題就沒有比最後一個提出意見的人更長久的答案。
不要將它與 scenarios.md 混淆，這是另一個名稱以「什麼」開頭的層級：情境描述了產品做了什麼，一步一步地。一個功能可以完美地被情境化，但仍然違反反願景。
此技能產出兩個東西，而第二個才是重點。
docs/ux/vision.md— 文件本身。- 在專案自己的指令檔案中放置一個願景對齊規則，這樣後續的每個功能在提出時都會與願景進行比對，而不是讓願景被寫一次後就再也無人問津。
一個無人閱讀的願景只是一份文件，而非約束。
符合此鏈：願景 → 基礎（人物誌、JTBD、旅程、故事）→ 流程 → 情境 → 稽核。每個層級都可追溯至其上層。
步驟 0 — 閱讀專案本身，而不是它的 README
在撰寫任何文字之前：
README.md、ARCHITECTURE.md、ROADMAP.md、CHANGELOG.md，以及docs/中的所有內容。- 關鍵原始碼：入口點、主要服務、schema、路由表。
- 如果存在的話，行銷面向的內容 — 登陸頁面、定價、功能。
package.json/pyproject.toml/Cargo.toml，了解它實際依賴什麼。- 實際的 UI。產品做了什麼，而不是它說它做了什麼。
- 如果
docs/ux/foundation.md存在，請閱讀它 — 願景不得與已達成共識的人物誌和工作相矛盾。
僅從 README 撰寫的願景只是在描述 README。 專案所說的內容與其程式碼實際做的內容之間的差距，通常就是真實願景隱藏的地方，而明確說出這個差距往往是此技能所做的最有價值的事情。
步驟 1 — 轉變
在撰寫之前先在內部回答：
此產品存在之前的用戶 → [混亂 / 複雜度 / 痛苦]
此產品存在之後的用戶 → [清晰 / 簡潔 / 力量]
以下所有內容都源於此。如果你無法陳述它，表示你還不夠了解產品以撰寫其願景 — 請回到步驟 0。
步驟 2 — 以九個層級撰寫 docs/ux/vision.md
每個層級都是強制的。請使用專案的文檔語言撰寫。
1. 本質。 一句話。[產品] 是一個 [系統類型]，它改變了 [用戶] [做 X] 的方式。 不能提到功能名稱、UI 或技術。測試方法：如果這個產品在不同的技術棧上從頭重建，這句話仍然成立嗎？ 如果不是，那它描述的是實作，而非本質。
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 |