aep-envision

Envision

漠然とした製品アイデアを、明確で検証可能な製品定義へと変えます。まず、その機会に取り組む価値があるかを検証し（Phase 0）、その後、後続のエージェントが曖昧さなく作業できる精度で製品を定義します（Phase 1）。

この工程の位置づけ：

/aep-envision → /aep-map → /aep-scaffold → [ /aep-design → /aep-launch → /aep-build → /aep-wrap ] → /aep-reflect
▲ you are here

• セッション： メイン。ユーザーと対話しながら進めます
• 入力： 製品アイデア（漠然としたもの、または具体化されたもの）
• 出力： product/index.yaml（opportunity、personas、capabilities、product セクション）＋ product-context.yaml（calibration、changelog）。V1 のフォールバック（分割なし）：すべてを product-context.yaml に記録します。
• YAML スキーマ： フィールドの構造と定義は templates/product-context-schema.yaml に記載されています。

開始前

プローブを実行し、該当するケースに沿って進めます。検出は自動で行われるため、プローブによって有効なモードがわかります。

ls product/index.yaml 2>/dev/null && echo "SPLIT MODE" || echo "V1 MODE"
ls product-context.yaml 2>/dev/null

分割モード、V1 モード、新規プロジェクトの動作（V1 から分割モードへの移行を一度だけ提案する場合を含む）は、references/file-resolution.md に正規の仕様が記載されています。ケースを判断する際は、同ファイルを読んでください。更新モードでは、既存のファイルを読み、修正するか新規に作成するかをユーザーに尋ね、更新対象ではないすべてのセクションを保持してください。

---

Phase 0：機会の見極め

目標： 製品設計に投資する前に、このアイデアをそもそも形にする価値があるか判断します。機会の見極めでは「これを作るべきか？」に答えます。Phase 1 では「具体的に何を作るのか？」に答えます。この2つを分けることで、早まった決断や、悪いアイデアを捨てられなくなるサンクコストバイアスを防ぎます。

このフェーズの進め方

ユーザーにアイデアを自由に説明してもらい、その過程で以下の材料を引き出します。

• このアイデアのきっかけは何か——個人的な悩み、市場の空白、技術的な可能性か？
• 現在、この問題を抱えているのは誰で、どのように対処しているか？
• この製品が存在することで、世の中はどう変わるか？
• ユーザーの他者にはない強みは何か——技術力、専門知識、既存のオーディエンスか？
• 失敗する、または重要でない可能性を示す最も強い理由は何か？

十分にアイデアを広げたら、中核となる賭けをまとめた機会ブリーフ（1ページ。templates/opportunity-brief.md に準拠）を作成します。「[対象ユーザー]には[問題]があり、[強み]があるため、[解決策]を構築できると考えます。」

中止の判断点

機会ブリーフをユーザーに提示し、正直に5分間検討するための、はい／いいえで答える3つの質問をします。いいえが1つでもあれば、このフェーズを終了します（中止または保留）。

1. 具体的に名前を挙げられるユーザーにとって、問題は現実に存在し、深刻か？
2. 今取り組むべき本当の理由があり、他者にはない自分の強みがあるか？
3. 最も強い反論を踏まえても計画は覆らず、その影響は後続の構築コストに見合うか？

早い段階で中止することは、このワークフローで最も ROI の高い判断です。決定はブリーフの「Decision」セクションに記録します。

• 進行 → Phase 1
• 中止 → 終了。ブリーフは記録として保存します
• 保留 → 再検討の条件を添えてブリーフを保存します

Phase 0 の出力

確定した機会ブリーフを opportunity セクションに書き込みます。保存先は、分割モードでは product/index.yaml、V1 モードでは product-context.yaml です。

事後条件： モードに対応する対象ファイルに opportunity セクションが存在し、中止の判断点での決定（進行／中止／保留）が記録されていること。

---

Phase 1：製品の定義

目標： 検証済みの機会を、後続のエージェントが曖昧さなく利用できる、明確な製品定義に落とし込みます。暗黙のまま残された前提はすべて、後続のエージェントが推測で補うことになります。このフェーズでは、それぞれの前提を明示します。

ステージ 1：発散

フェーズ 0 から会話を続け、プロダクトの具体的な内容を検討します。

• 問題の定義： さらに明確にします。「開発者にはより良いツールが必要」ではなく、「エッジプラットフォームを利用する個人開発者は、既存のソリューションが AWS/GCP を前提としているため、プロジェクトごとにエージェントのサンドボックス化に 4 時間以上を費やしている」とします。
• ペルソナ／JTBD： 主なユーザーは具体的に誰ですか？ このプロダクトにどのような仕事をさせるために採用しますか？ そのユーザーにとって、成功とはどのような状態ですか？
• MVP の境界： ユーザーが最初から最後まで完了できる、最も重要な単一のジャーニーは何ですか？ また、隣接していて魅力的に見えても、明確に対象外とするものは何ですか？
• ユーザーアクティビティ（ストーリーマップの背骨）： ユーザーが段階を追って何をするのかを、動詞句（「認証する」「プロフィールを作成する」「コンテンツを生成する」「進捗を追跡する」「出力をダウンロードする」）の左から右へのナラティブとして示します。レイヤーを定義する前に、この背骨を作成してください。レイヤーはこの背骨にまたがります。
• 技術的制約： 譲れない技術スタック、インフラストラクチャ、必須の依存関係。
• 品質の次元： エージェントでは判断できない、人間の判断が必要な次元はどれですか。「正しいが、しっくりこない」ことが起こりそうなものだけを選びます。7 つのテイストの次元（visual-design、ux-flow、copy-tone、api-surface、data-model、scope-direction、performance-quality）は /aep-calibrate の references/calibration-types.md にまとめられています。再列挙するのではなく、そこから宣言してください。object-model は別のものです。 これはテイストの調整ではなく構造上のゲートであり、/aep-map が自動でドラフトを作成し、/aep-model が承認します。UI に関わるプロダクト／機能では、デフォルトで object-model を宣言してください。 これにより、ビルドエージェントが「1 ステップにつき 1 画面」のウィザード UI を勝手に作るのを防げます（バックエンドのみ、または CLI のみの場合に限り省略します）。宣言した各次元について、調整が最初に必要になりそうなレイヤーと、その理由を記録します。
• レイヤー化された MVP の契約： レイヤー 0 はウォーキングスケルトンであり、背骨に沿って横方向に切り分けた、各アクティビティの最も薄いストーリーです。それ以降の各レイヤーでは機能を追加します（また、右方向に新しいアクティビティを加えて背骨を拡張する場合もあります）。.5 レイヤーは人間との調整レイヤーです。1 つ以上の品質の次元にわたって意図を調整するため、エージェントの実行を一時停止するポイントです（正式な定義は /aep-map の references/alignment-layers.md）。calibration.plan では、各レイヤーを想定されるチェックポイントに対応付けます。

ステージ 2：構成

すべての内容を Context Document（templates/context-document.md）に整理し、ドラフトを提示します。product.quality_dimensions を記入し、宣言した各次元について、次元、重要度、最初に調整するレイヤー、根拠を記録します。

品質基準：すべての記述は、検証条件に変換できなければなりません。「システムは高パフォーマンスであるべき」は不合格です。「API の p95 レイテンシーが 200ms 未満」は合格です。

ステージ 3：ストレステスト（独立したエージェント）

会話に参加していないエージェントに Context Document を渡します。3 つの観点から内容を事前知識なしでレビューし、それぞれが課題のリストを作成します。

1. プロダクトの実現可能性 — ユーザーや問題に関する前提は検証されていますか？ 最も有力な反論は何ですか？
2. 技術的実現可能性 — 技術選定は相互に互換性があり、目的に十分ですか？ 既知の制限はありますか？
3. スコープ管理 — MVP は本当に最小限ですか？ 削れるレイヤーはありますか？

ユーザーは、ドキュメントを改善するか、デフォルトの前提と見直しのトリガーを明記した open_question として記録するかを決め、各項目を解決します。結果は product.stress_test に記録します（このストレステストはビルド前の調整です。/aep-calibrate では、エージェントが出力を生成した後に初めて見える次元まで対象を広げます）。

フェーズ 1 の出力

分割モード：

1. コンテキストドキュメントを product/index.yaml に書き込みます。
   • opportunity（フェーズ 0 から）
   • personas（id、description、jtbd を含むリスト）
   • capabilities（1 件以上。1 つのユーザージャーニーのみの製品では 1 件）
   • product — コンテキストドキュメントのフィールド。templates/product-context-schema.yaml に記載されています。
2. 運用上の初期化情報を product-context.yaml に書き込みます。ヘッダー（schema: v1、project、version、updated_at、dispatch_epoch: 0）、calibration.plan（quality_dimensions からマッピング）、calibration.history: []、changelog エントリーを含めます。その他の運用セクションは空のままにします（/aep-map が入力します）。

V1 モード： templates/product-context-schema.yaml を構造上の参照として使用し、すべてを product-context.yaml に書き込みます。品質ディメンションが宣言されている場合は、calibration.plan も書き込みます。以降の実行では、該当するセクションを更新し、その他のセクション（例：architecture、stories、topology）は保持します。

事後条件： 上記の product セクションがモードに応じた対象ファイルに書き込まれ、（分割モードでは）product-context.yaml に calibration.plan と changelog エントリーが存在します。

ケイパビリティマップ（複数のユーザージャーニーがある製品の場合）

製品に異なるユーザージャーニーが 2 つ以上ある場合：capabilities[] に複数のエントリーがあることを確認し、各ケイパビリティについて、templates/product-context-schema.yaml のスキーマに従って product/maps/<capability-id>/frame.yaml（スコープ、境界、主要ユーザー、成果の契約）を作成します。ストーリーのスタブは後で /aep-map が入力します。ユーザージャーニーが 1 つのみの製品では、ケイパビリティのエントリーを 1 件にし、frame.yaml の作成を省略します。

コミット前：YAML を検証する

ゲートを実行します。チェックリスト全体とよくある修正方法については、references/yaml-guardrails.md を参照してください。

# Split mode
npx js-yaml product/index.yaml > /dev/null && npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"
# V1 mode
npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"

事後条件： コマンドが YAML OK を出力します（終了コード 0）。失敗した場合は、コミットする前に YAML を修正します。

コミット

/aep-git-ref の「Integration Branch」に従って $BASE を解決し、/aep-git-ref の「Control-Plane Commits」に従ってコミットします。

git add product-context.yaml product/ docs/
git commit -m "feat: add product context (opportunity brief + context document)"

事後条件： コミットが $BASE にプッシュされています。

---

イテレーションの場合

既存の製品を見直す場合（/aep-reflect またはユーザー自身の判断によるもの）：

1. 既存の定義を読み込みます（product/index.yaml、または V1 モードでは product-context.yaml）
2. 何が変わったかを特定します。新たな学び、無効になった前提、スコープの変更などです。
3. 該当するセクション（opportunity および／または product）を更新します。
4. 変更したセクションのみ、ストレステストを再実行します。
5. changelog に追記します。
6. 更新したバージョンをコミットします（バージョン履歴自体にも価値があります）。

境界 — /aep-envision と /aep-reflect： /aep-envision は新たな機会、または方向が変わった機会を定義します。基盤となる変更（アクティビティの追加・削除・並べ替え）や、製品の位置付けの変更（ペルソナ、JTBD、MVP の境界、無効になった機会の仮説）があった場合に実行します。/aep-reflect はリリース済みの作業へのフィードバックを分類します。エンビジョンには触れずに、再スライス（ストーリーをレイヤー間で移動する、ストーリーを追加する、優先順位を再設定する）を扱います。詳細については、docs/decisions/release-line-adjustments.md を参照してください。

---

次のステップ

製品の構想ができました。次は /aep-map に進みます。コンテキストドキュメントをシステムマップ、階層化されたストーリーグラフ、エージェントトポロジーに分解します。