vision

vision — プロダクトとは何か、そして何にならないのか

super-ux の一部です — パイプライン全体については system-map.md を参照してください。ドキュメントを書いた後、 python3 docs/ux/lint.py を実行してください。

ux-foundation の上位レイヤーです。Foundation は、プロダクトを使うのは誰か、そしてなぜ使うのかに答えます。vision は、プロダクトが何であるか、そして何にはならないのかに答えます。これがなければ、「これを作るべきか？」という問いに、最後に意見を持った人がいなくなっても通用する答えはありません。

名前が「what」で始まるもう一つのレイヤーである scenarios.md と混同しないでください。scenarios は、プロダクトが何をするかを手順ごとに示します。機能がシナリオとして完璧に定義されていても、アンチビジョンに反することはあります。

このスキルが作成するものは2つあり、重要なのは2つ目です。

1. docs/ux/vision.md — ドキュメント。
2. プロジェクト独自の指示ファイルに記載するビジョン整合性ルール。これにより、ビジョンを一度書いて二度と読まないのではなく、後から追加されるすべての機能をビジョンに照らして確認できます。

誰にも読まれないビジョンは、制約ではなく単なるドキュメントです。

この連鎖に適合します：vision → foundation（ペルソナ、JTBD、ジャーニー、ストーリー）→ flows → scenarios → audit. 各レイヤーは、その一つ上のレイヤーまでたどれます。この連鎖には、口頭でのオプトアウトがあります。オペレーターが 「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 に戻ってください。

Step 2 — docs/ux/vision.md を9つのレイヤーで記述する

すべてのレイヤーが必須です。プロジェクトのドキュメント言語で記述してください。ビジョンの9つのセクションは英語のタイトルではなく番号で識別されます。番号を翻訳してなくさず、必ず ## 6. <お使いの言語でのタイトル> のように記述してください。セクションの仕様は scenario-format.md → docs/ux/vision.md です。ビジョンを書く前に読んでください。リンターは番号を基準に判定するため、セクション（例：アンチビジョン）が欠けていると、言語に関係なく失敗します。

1. 本質。 一文で記述します。[Product] is [type of system] that changes how [user] [does X]（[製品]は、[ユーザー]の[Xを行う方法]を変える[システムの種類]です）。機能名、UI、テクノロジーは含めません。確認方法：異なる技術スタックで製品を一から作り直したとしても、この文は真実のままですか？ そうでなければ、それは本質ではなく実装を表しています。

2. 中核となる考え。 問題の説明ではなく、世の中についての観察を記述します。

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

列挙ではなく、ひとつの観察にします。「情報は豊富にあるが、明瞭さは乏しい。」

3. システムが行うこと。 名詞ではなく、継続的な振る舞いを動詞で記述します：観察する……理解する……変換する……提示する……。機能名は含めません。「ダッシュボードがある」は振る舞いではありません。「情報源間の矛盾を提示する」は振る舞いです。

4. ユーザーの役割。 このシステムを使うことで、ユーザーがどのような存在になるかを記述します。「ユーザーがクリックする」ではなく、ユーザーは指示する、判断する、決定するのです。ユーザーの役割がほかのどのツールを操作する場合とも区別できないなら、ビジョンはまだ具体性に欠けています。

5. 原則。 3〜5個を記述します。それぞれ「Yではなく、Xを行う」という形式にします。Yには、合理的なチームが実際に選びそうなものを入れます。却下する選択肢がない原則は、スローガンにすぎません。

6. アンチビジョン。 この製品が決してならないものを明確に記述します。チームが省略しがちなレイヤーですが、議論に決着をつける唯一のレイヤーです。製品が変化して近づく可能性のある、隣接する製品を挙げ、それぞれに対して「ならない」と明言します。

7. 展望。 2〜3年後にどこへ向かうのかを、ロードマップではなく方向性として記述します。ロードマップはトラッカーに記載するものであり、四半期も経てば古くなります。

8. 一文で表すなら。 誰かがひとつだけ正確に覚えているとしたら、それはこの一文です。

9. 整合性テスト。 提案される機能が必ず通過すべき質問を3〜5個記述します。ステップ4のルールで実際に使うのはこれらの質問です。

Step 3 — リリース前に検証する

それぞれを確認し、正当化するのではなく修正してください。

• 本質は異なるテクノロジーで完全に作り直しても成り立つ
• どのレイヤーにも機能、画面、ベンダーの名前が含まれていない
• アンチビジョンでは、架空の代替案ではなく実際の代替案を挙げている
• 原則には、誰かが本当に選んだ可能性のある、却下する側面がある
• docs/ux/foundation.md と矛盾する内容がない。矛盾がある場合は、黙って取り繕うのではなく、報告すべき問題として提示する
• 初めて読む人が、整合性テストを使ってもっともらしい機能案を却下できる

Step 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、Claude が HOST であるか HOST を特定できない場合に限り CLAUDE.md を作成します。CLAUDE.md を決め打ちしてはいけません。実行中のエージェントが認識できない場所にルールを設定するのは、誰もがルールでカバーされていると思い込むため、ルールがないよりも悪い結果を招きます。

複数の HOST を使うプロジェクト（マーカーが複数存在する場合）では、アクティブな各 HOST のファイルにルールを記述し、すべての対象ファイルを明示して、どの HOST もカバーされないことがないようにします。

冪等性を保ちます。HOST のファイルに見出しがすでにある場合は、2つ目のコピーを追記するのではなく、その箇所のブロックを更新してください。再実行時には新たな内容を書き込みません。

## 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 へのリンクを 1 行追加します。入口から見つけられないビジョンは、誰にも読まれません。

よくある間違い

間違い	問題が起きる理由
エッセンスに技術の名前を含める	最初の書き換えで、真実ではなくなります
否定する側面のない原則	「品質を重視します」では、議論に決着がつきません
アンチビジョンがない	スコープに関する疑問を判断する唯一のレイヤーが欠けています
方向性をロードマップとして記述する	1 四半期で古くなり、その後、ドキュメント全体が古く見えます
ビジョンが foundation.md と矛盾する	真実の情報源が 2 つになり、チームは最後に読んだほうに従います
ルールを、あるエージェントのハードコードされたパスに配置する	実際に実行中のエージェントから見えず、誰も気づきません。ルールがない状態は、準拠している状態と見分けがつかないためです
README をもとに書く	README の説明になってしまいます