aep-map

マップ

コンテキストドキュメントを、システムマップ（モジュール＋インターフェース）、レイヤードストーリーグラフ（作業項目＋依存関係＋実行スライス）、エージェントトポロジー（役割＋引き継ぎ契約）に分解します。これは最も難しいフェーズです。モジュール境界を誤ると、数十のエージェントが互換性のないコードを生成することになります。

このフェーズの位置づけ：

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

セッション： Main。ユーザーとの対話形式（システムマップには人間によるレビューが必要です） 入力： product/index.yaml（分割モード）または product-context.yaml（v1 モード）の製品定義 出力： architecture、stories、waves、topology、layer_gates、cost、changelog の各セクションを更新した product-context.yaml

YAML スキーマ： 構造とフィールド定義の全容については、templates/product-context-schema.yaml を参照してください。

---

開始前

製品コンテキストがどちらのモードかを確認します。

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

モードの意味は references/file-resolution.md で規定されています。Map は製品定義（機会、ペルソナ、product.*）を product/index.yaml（分割モード）または product-context.yaml（v1）から読み込み、運用状態を読み取って、すべての出力を product-context.yaml に書き込みます。

製品定義がない場合（どちらのファイルにも product セクションがない場合）は、まず /aep-envision を実行してください。

---

ステップ 1：システムマップ（単一エージェント＋人間によるレビュー）

コンテキストドキュメントからシステムマップ（templates/system-map.md を参照）を作成します。

• モジュール： 明確な責任範囲を持つ主要コンポーネントです。各モジュールが「行うこと」と同じくらい、「行わないこと」の定義も重要です。各モジュールの kind を (ui | backend | shared) から設定します。ui モジュールはユーザー向けの画面を描画し、これにより /aep-model、dispatch、launch が使用する UI 向けストーリートリガーが決まります。
• インターフェース契約： モジュール間の接続ごとに、エンドポイント、データ形式、エラー契約など、正確な API の仕様を定義します。これらはドキュメントではなく、契約テストによって適用される実行可能な仕様です。
• データフロー： MVP 契約に含まれる各ユーザージャーニーについて、システム内で情報がどのように移動するかを示します。
• サードパーティとの境界： 障害モードを含む外部サービスとの統合ポイントです。

システムマップを product-context.yaml の architecture セクションに書き込みます。

システムマップで、複数ステップのプロトコル、複数のステートマシン、異なる障害クラス、またはモジュール間の信頼境界が明らかになった場合は、references/technical-spec-triggers.md を読み、分解の前に技術仕様書を作成することを提案してください。

人間によるレビューゲート

ユーザーはシステムマップをレビューし、承認する必要があります。 アーキテクチャ上の判断は、パイプライン全体で最も大きなエラーコストを伴います。マップを提示し、明示的に承認を求めてください。ユーザーが変更を希望する場合は、修正して再提示します。ユーザーが明示的に承認した後でのみ、ストーリーの分解に進んでください。

事後条件： architecture セクションが product-context.yaml に書き込まれ、ユーザーがシステムマップを承認していること。

---

ステップ 2：ストーリーの分解（並列エージェント）

システムマップが確定したら、ストーリーに分解します。

• モジュールごとに分解エージェントを 1 つ割り当てます： コンテキストドキュメント、システムマップ、および担当モジュールの定義を受け取ります。レイヤー（0 = ウォーキングスケルトン、1+ = 拡張レイヤー）を付与したストーリーを作成します。
• 統合ストーリーエージェントを 1 つ割り当てます： システムマップにおけるモジュール間の接続を確認します。モジュールをつなぐストーリー、つまりモジュール境界を越えるエンドツーエンドのフローを作成します。レイヤー 0 では、これらが特に重要です。

エージェントを追加する前に、曖昧な分解や重複した分解を明確にしてください。エージェントを増やすと、曖昧さが解消されるのではなく、増幅されます。

各ストーリーは ストーリー仕様形式（templates/story-spec.md を参照）に従い、次の内容を含める必要があります。

• 完了時に何が変わるか（観察可能な動作）
• テストで自動化できる受け入れ基準
• レイヤーの割り当て（0 = ウォーキングスケルトン、1+ = 拡張）
• モジュールの割り当て
• 依存関係の宣言
• インターフェース上の義務（モジュール境界に関わる場合）
• 影響を受ける可能性のあるファイル（競合検出用）
• business_value（1～10、または優先度から導出する場合は null）
• compile_mode（デフォルトは single_change。密接に結合したストーリーには grouped_change、インフラストラクチャには shared_enabler を使用します）

すべてのストーリーは status: pending で開始します。 ストーリーの状態はプロダクトコンテキストのスキーマに従います。実行中の遷移は /aep-dispatch が管理します。

アクティビティのマッピング

分解エージェントがストーリーを作成したら、各ストーリーを product.activities のユーザーアクティビティにマッピングします（分割モードでは、story.capability に所有する capabilities[] の ID を設定します。これは、後でディスパッチ／起動時に、そのストーリーのオブジェクトマップを特定するために使用されます。v1／単一ジャーニーでは、デフォルトのケイパビリティがプロジェクトのスラッグであるため、null のままにします）。

• ユーザー向けのケイパビリティを直接実現するストーリーには、それが役立つアクティビティを割り当てます（例：「Create presigned upload URL」→ ユーザーが自撮り写真をアップロードできるようにするため、create-profile）。
• 特定のユーザーアクティビティにマッピングされないインフラストラクチャ／基盤ストーリーは、activity を null のままにします。 これらは実装を支えるストーリーです。アーキテクチャビューには表示されますが、ユーザーの視点を示すユーザージャーニーのストーリーマップには表示されません。
• 統合ストーリーには、エンドツーエンドで検証する主要なユーザーアクティビティを割り当てます。

ウォーキングスケルトン（レイヤー 0）

レイヤー 0 は最も重要なレイヤーです。 アクティビティの基幹を横断する薄いスライスです。各ユーザーアクティビティから最も薄いストーリーをつなぎ合わせ、コンテキストドキュメントのレイヤー 0 MVP 契約に基づいて、ユーザーが可能な限り粗いエンドツーエンドのジャーニーを完了できるようにします。

「完璧な脚を作る前に、歩ける骨格を作りましょう。」

layer_introduced: 0 の product.activities 内のすべてのアクティビティには、レイヤー 0 のストーリーが少なくとも 1 つ必要です。モジュールを深く掘り下げる前に、エンドツーエンドの経路が機能することを証明してください。骨格が歩き出す前に深さを優先するのは、このワークフローで最もコストのかかる失敗です。

事後条件： すべてのストーリーにレイヤー、モジュール、status: pending が設定されていること。layer_introduced: 0 の各アクティビティに、レイヤー 0 のストーリーが 1 つ以上あること。

---

ステップ 3：依存関係の解決とウェーブ（単一エージェント）

専用エージェントがすべてのストーリーを受け取り、次の成果物を作成します。

• ストーリーグラフ： レイヤー別に整理された有向非巡回グラフです。依存関係と並列化の機会を示します。
• ウェーブ（実行スライス）： 各レイヤー内で、ストーリーをバッチとしてディスパッチできるウェーブにまとめます。ウェーブは相互依存のないストーリーの集合で、すべてを完全に並列実行できます。（YAML フィールドは stories[].slice で、ユーザー向けの用語は「ウェーブ」です。）
• レイヤーごとのクリティカルパス： 最長の依存関係チェーンで、そのレイヤーの完了に必要な最短時間を決定します。
• レイヤーゲート： 次のレイヤーに進む前に合格しなければならない統合テストの定義です。各ゲートには、計画済みの journeys:（skills/e2e-test/journeys/<NN-slug>.md、機能領域ごとに 1 つ。dogfood_target == none の場合は空）も記載します。journey の作成者と実行タイミングについては、/aep-e2e-skill-scaffolding → references/layer-gate-loop.md が正式な定義です。コストが発生するライブ実行の半分の費用を定める live_policy は skills/e2e-test/policy.md にあるため、マイルストーンレイヤーを提案する際は、そこに記載できる名称を付けてください。

すべてのストーリーを product-context.yaml の stories セクションに記述します。また、waves セクションにレイヤーとウェーブごとにストーリーをまとめて記入します。

成果契約

outcome_contract が定義されている各レイヤー（product.layers[].outcome_contract を参照）について、レイヤーゲートのテスト定義が成功指標と一致していることを確認します。レイヤーに成果契約がない場合は、追加を検討します。Jeff Patton は、レイヤーは機能の完成度だけでなく、成果に基づいて定義すべきだと強調しています。

成果契約は、レイヤー完了後に /aep-reflect が評価します。これは「このレイヤーは、仮説としていた成果を達成したか？」に答えるものです。

テレメトリの紐付け（可観測性）

ここで、プロジェクトのテレメトリソースを決定します。まずメトリクスを基準にし、その後に一覧を確認します。定量的な success_metric と、監視対象の health_signals をすべて、references/telemetry-ingestion.md（§1.5 のカバレッジルール、metric_map／endpoint／token_env の紐付けに関する §1 のソース設定）に従ってソースに紐付けます。結果を topology.routing.telemetry_sources（および health_signals）に記述します。

/aep-reflect、/aep-watch、/aep-autopilot は、自動パスを信頼する前にこれを対象として coverage_check() を実行します。紐付けが不完全な場合、自動処理はブロックされます。何もせずに処理が通ることはありません。

ケイパビリティマップ（複数のジャーニーを持つプロダクト）

product/index.yaml が存在する場合（複数のジャーニーを持つプロダクト向けに /aep-envision が作成）、ケイパビリティごとの map.yaml ファイルも記述します。

• product/maps/<capability>/map.yaml — このケイパビリティの基幹アクティビティ、レイヤー、ストーリーの草案
• map.yaml のストーリー草案はスケッチです。product-context.yaml の完全なストーリーが運用上の正式版です。

分割モードに関する注意： 分割モードでは、ケイパビリティマップの map.yaml にあるストーリー草案は説明用のスケッチです。完全なストーリーは product-context.yaml に記述され、product/index.yaml は /aep-map によって変更されません（読み取りのみ行います）。

これは追加の手順です。ケイパビリティマップが存在しない場合は、この手順を省略します。

アラインメントレイヤー（.5 レイヤー）

各実装レイヤーを定義した後、人間の意図を調整するために実行を一時停止する .5 アラインメントレイヤーを計画します。calibration.plan（または各レイヤーが扱う品質の次元）を確認し、重い／軽い次元のルール、レイヤーの進行、および承認済みの Object Map がビジュアルデザイン／UX フローのブリーフにどう反映されるかについて、.5 レイヤーの正式な定義元である references/alignment-layers.md を読みます。重い次元には calibration_type タグ付きのストーリーを含む .5 レイヤーを設け、軽い次元には次の整数レイヤーに進む前に /aep-calibrate のチェックポイントを設けます。

オブジェクトマップのドラフト（UI 向け機能）

ストーリーを分解した後、UI 向け機能ごとに、名詞を先頭にしたドラフトのオブジェクトマップを作成します（object-model、visual-design／ux-flow として宣言された機能、またはユーザー向けストーリー）。これは、動詞を先頭にしたストーリーマップと UI をつなぐものです。ORCA の導出方法、およびドラフト／承認済み／古くなった状態のルールについては、references/object-map-drafts.md を読み、その後 product/object-model.yaml と product/maps/<capability>/object-map.yaml を status: draft にして作成します。承認は /aep-model が担当します。UI 向け機能のない純粋なバックエンド／CLI プロジェクトでは、完全に省略してください。

フィードバックループ

分解エージェントは、モジュールの境界が適切でないことを発見する場合があります。その場合、System Map への修正案を提出します。修正案が 3 件以上蓄積された場合、または単一の修正案がインターフェース契約に影響する場合は、続行する前にユーザーとアーキテクチャレビューを実施してください。

事後条件： stories セクションと waves セクションが記述され、各レイヤーに layer_gates エントリー（計画済みの journeys: を含む）があり、UI 向け機能ごとに status: draft のオブジェクトマップが作成されています。

---

ステップ 4：エージェントトポロジーの設計

トポロジーは分解に関する決定事項です。/aep-launch がワークスペースをどのように設定するか、また /aep-build エージェントがどのようなコンテキストを受け取るかを決めるため、実行前に定義します。エージェントトポロジーのテンプレート（templates/agent-topology.md を参照）を使って、エージェントの役割、引き継ぎ契約、ルーティングルールを定義してください。エージェント間の引き継ぎはすべてスキーマで定義し、自由記述にはしません。曖昧さは、並列エージェント間で指数関数的に増幅します。

エージェントの役割定義

実行パイプラインの各役割について、次の項目を定義してください。

• 役割名： このエージェントの種類の名称（例：implementer、contract-verifier、integration-tester）
• 責任範囲： このエージェントが行うことと、行わないこと。単一責任を原則とします。
• 入力契約： このエージェントが受け取る作業オブジェクトの厳密な構造。自由記述ではなく、スキーマで定義します。
• 出力契約： このエージェントが作成する成果物の厳密な構造。スキーマで定義します。
• コンテキストウィンドウの構成： このエージェントのコンテキストに含める内容（Context Document のどのセクション、System Map のどの部分、どの依存成果物か）。無関係なコンテキストはパフォーマンスを低下させます。
• コスト予算： 呼び出しごとの想定トークン使用量と所要時間。

引き継ぎ契約

エージェント間の移行ごとに、次の項目を定義してください。

• トリガー： 引き継ぎを発生させるイベント
• ペイロード： 渡される成果物と、そのスキーマ
• 検証： 受信側のエージェントが開始する前にペイロードに対して実行するチェック

ルーティングルール

• ディスパッチポリシー： 準備完了キューからストーリーを割り当てる方法
• 並行処理の上限： 並列で実行するエージェントの最大数（まずは控えめに 5～10 から開始）
• 競合検出： 同じファイルを変更するストーリーは、別々のスライスに割り当てます。
• 再試行時のルーティング： 同じエージェントで再試行（2 回）→ 失敗ログを添えて新しいエージェントで再試行（1 回）→ 人間にエスカレーション

トポロジーを product-context.yaml の topology セクションに記述してください。また、layer_gates セクションと cost セクションも初期化してください。

事後条件： topology セクションが記述され、layer_gates セクションと cost セクションが初期化されています。

---

出力

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

コミット前に検証してください（チェックリストは references/yaml-guardrails.md を参照）。

npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"

検証に失敗した場合は、references/yaml-guardrails.md に従って YAML を修正してからコミットしてください。

コミット

/aep-git-ref の「Control-Plane Commits」に従って、コミットしてプッシュします。git add product-context.yaml product/ を実行し、コミット（feat: add system map, story graph, and agent topology）を作成して、$BASE にプッシュします（/aep-git-ref の「Resolving $BASE」に従って $BASE を解決してください）。

記述するセクション：

• architecture — システムマップ（モジュール、インターフェース、データフロー）
• stories — ウェーブを含む階層型ストーリーグラフ（すべてのストーリーの開始時の status: pending）
• waves — バッチディスパッチ用に、レイヤーとウェーブごとにグループ化したストーリー
• topology — エージェントの役割、引き継ぎ契約、ルーティングルール
• layer_gates — レイヤーごとの統合テスト定義（定義されている場合は成果契約に準拠）。それぞれに計画済みの journeys: を含めます（dogfood_target == none の場合は空のリスト）。ライブドッグフードを実施するゲートは policy.md の live_policy で定められ、ここには保存しません。
• cost — 初期コスト予算と追跡構造
• changelog — 追加内容を記録するエントリーを追記

必ず changelog セクションに追記してください。

事後条件： npx js-yaml が終了コード 0 を返し、コミットが $BASE に反映されていること。

---

イテレーションについて

マップを更新する場合（/aep-reflect または新しい要件によって開始）：

1. 既存のプロジェクト定義（分割モードでは product/index.yaml、v1 モードでは product-context.yaml）と、product-context.yaml の運用状態を読み込みます
2. 変更点（新しいモジュール、改訂されたインターフェース、新しいストーリー）を特定します
3. 影響を受けるセクション（architecture、stories、topology）を更新します
4. インターフェース契約が変更された場合 → 依存するストーリーを再検証します
5. changelog セクションに追記します
6. 更新版をコミットします

---

次のステップ

分解は完了です。プロジェクトがまだ存在しない場合：

/aep-scaffold

プロジェクトに UI 対応機能がある場合は、UI ストーリーをディスパッチする前に Object Map のドラフトを承認します。

/aep-model

/aep-model は Object Map のドラフトを提示し、短い人間によるレビューゲートを経て approved に切り替えます。その後、ストーリーの実行を開始します。

/aep-dispatch

/aep-dispatch は product-context.yaml からストーリーグラフを読み込み、各ストーリーを /aep-design → /aep-launch → /aep-build → /aep-wrap の順にルーティングしながら、状態マシンに沿ってストーリーを進めます。