ビジョン — 製品とは何か、そして何になることを拒むか
super-uxの一部 — パイプライン全体についてはsystem-map.mdを参照。 ドキュメント作成後、
python3 docs/ux/lint.pyを実行すること。
ux-foundationの上位レイヤー。Foundationは誰が製品を使い、なぜ使うのかに答える。ビジョンは製品とは何か、そして何になることを拒むかに答える。これがないと、「これは作るべきか？」という問いに、最後に意見を持った人の意見以上の寿命を持つ答えは存在しない。
scenarios.mdと混同しないこと。scenariosも「何を」で始まる別のレイヤーだが、scenariosは製品が行うことをステップごとに述べる。ある機能が完璧にシナリオ化されていても、アンチビジョンに違反する可能性がある。
このスキルは二つの成果物を生み出し、重要なのは二つ目である。
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 — 9つのレイヤーでdocs/ux/vision.mdを書く
すべてのレイヤーは必須。プロジェクトのドキュメント言語で書くこと。
1. 本質 (Essence)。 一文で。[製品]は、[ユーザー]が[Xをする方法]を変える[システムの種類]である。機能名、UI、技術は含めない。テスト：もし製品が別のスタックで一から作り直されたとしても、この文は依然として真か？ もし違うなら、それは実装を名指しているのであって、本質ではない。
2. コアアイデア (Core idea)。 問題文ではなく、世界についての観察。
[X]は豊富にある。
[Y]は希少である。
→ この製品がそのギャップを埋める。
一つの観察。リストではない。「情報は豊富だが、明確さは希少である。」
3. システムが行うこと (What the system does)。 継続的な振る舞い、動詞（名詞ではない）：観察する…理解する…変換する…表面化する…。機能名は含めない。「ダッシュボードがある」は振る舞いではない。「ソース間の矛盾を表面化する」は振る舞いである。
4. ユーザーの役割 (The user's role)。 それを使うことでユーザーは何になるか。「ユーザーがクリックする」ではない — ユーザーは指示する、判断する、決定する。もしユーザーの役割が他のツールを操作するのと区別がつかないなら、ビジョンはまだ具体的ではない。
5. 原則 (Principles)。 三つから五つ。それぞれ私たちはXを行い、Yは行わないという形で。Yは合理的なチームが実際に選びうるものでなければならない。拒否された代替案のない原則はスローガンである。
6. アンチビジョン (Anti-vision)。 この製品がなることを拒むものを明示的に。チームがスキップするレイヤーであり、議論を決着させる唯一のレイヤー。製品が漂流する可能性のある隣接製品を挙げ、それぞれに対してノーを言う。
7. 地平線 (Horizon)。 2〜3年後にどこへ向かうか。ロードマップではなく方向性として。ロードマップはトラッカーに属し、四半期で陳腐化する。
8. 一言 (The one sentence)。 誰かが正確に一つのことを覚えるなら、それがこれである。
9. 整合性テスト (The alignment test)。 三つから五つの質問。提案された機能はすべてこれらを通過しなければならない。これらがステップ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を説明するだけ |