aep-map

Map

将上下文文档拆解为系统地图（模块 + 接口）、分层故事图（工作项 + 依赖关系 + 执行切片）和 Agent 拓扑（角色 + 交接约定）。这是最难的阶段——模块边界划分错误，会导致数十个 Agent 生成彼此不兼容的代码。

适用阶段：

/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 模式）中的产品定义 输出： 更新后的 product-context.yaml，其中包含 architecture、stories、waves、topology、layer_gates、cost 和 changelog 部分

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/index.yaml（拆分模式）或 product-context.yaml（v1 模式）读取产品定义（机会、角色、product.*）；从 product-context.yaml 读取运行状态，并将所有输出写入其中。

如果缺少产品定义（任一文件中都没有 product 部分），请先运行 /aep-envision。

---

第 1 步：系统地图（单个 Agent + 人工审核）

根据上下文文档生成系统地图（参见 templates/system-map.md）：

• 模块： 职责边界清晰的主要组件。每个模块的“不负责什么”与“负责什么”同样重要。为每个模块设置 kind（ui | backend | shared）——ui 模块负责渲染面向用户的界面，这决定了 /aep-model、调度和启动使用的面向 UI 的故事触发条件。
• 接口约定： 为每个模块间连接定义精确的 API 表面——端点、数据结构、错误约定。这些不是文档，而是由契约测试执行的可执行规范。
• 数据流： MVP 契约中每个用户旅程的信息在系统中的流转方式。
• 第三方边界： 外部服务集成点及其故障模式。

将系统地图写入 product-context.yaml 的 architecture 部分。

当系统地图揭示多步骤协议、多个状态机、不同故障类别，或跨越模块边界的信任边界时，请阅读 references/technical-spec-triggers.md，并建议在拆解前编写技术规格说明。

人工审核关卡

用户必须审核并批准系统地图。 在整个流水线中，架构决策的出错代价最高。展示地图并明确征求批准。如果用户要求修改，请修订后重新展示；只有在用户明确批准后，才能继续拆解故事。

后置条件： architecture 部分已写入 product-context.yaml，且用户已批准系统地图。

---

步骤 2：故事拆解（并行 Agent）

确认系统地图后，将其拆解为故事：

• **每个模块对应一个拆解 Agent：**接收上下文文档、系统地图和该模块的定义。输出标注层级的故事（0 = 行走骨架，1+ = 丰富层）。
• **一个集成故事 Agent：**查看系统地图中的模块连接关系。输出将模块连接起来的故事，即跨越模块边界的端到端流程。这些故事在第 0 层尤为关键。

添加 Agent 之前，先梳理清楚模糊或重叠的拆解；增加 Agent 只会放大拆解中的不明确之处，而非解决问题。

每个故事都遵循 故事规范 格式（见 templates/story-spec.md），并且必须包含：

• 完成后会发生什么变化（可观察的行为）
• 可自动化为测试的验收标准
• 层级分配（0 = 行走骨架，1+ = 丰富层）
• 模块分配
• 依赖声明
• 接口义务（涉及模块边界时）
• 可能受影响的文件（用于冲突检测）
• business_value（1-10，或设为 null 以根据优先级推导）
• compile_mode（默认为 single_change；紧密耦合的故事使用 grouped_change，基础设施使用 shared_enabler）

**所有故事的初始状态均为 status: pending。**故事状态遵循产品上下文架构；/aep-dispatch 会在执行期间管理状态转换。

活动映射

拆解 Agent 输出故事后，将每个故事映射到 product.activities 中的一项用户活动（在拆分模式下，将 story.capability 设为所属 capabilities[] 的 id——这样调度/启动流程之后就能找到该故事的对象地图；在 v1/单旅程模式下留空，因为默认 capability 为项目 slug）：

• 直接实现面向用户的功能的故事，应关联其服务的活动（例如，“创建预签名上传 URL” → create-profile，因为它支持用户上传自拍照）。
• **无法映射到任何特定用户活动的基础设施/基础故事，应将 activity 留空。**这些是实现层面的支撑项——它们会显示在架构视图中，但不会出现在用户旅程故事地图中，因为该地图展示的是用户视角。
• 集成故事应关联其端到端验证的主要用户活动。

行走骨架（第 0 层）

**第 0 层是最重要的一层。**它是横跨活动主干的一个水平切片——每项用户活动中最精简的故事串联起来，让用户能够完成上下文文档第 0 层 MVP 合约所定义的最基础端到端旅程。

“先搭建一个能走路的骨架，再打造完美的腿。”

product.activities 中每个 layer_introduced: 0 的活动都应至少有一个第 0 层故事。先证明端到端路径可行，再深入任何模块——在骨架走起来之前就先深挖模块，是这一工作流中代价最高的错误。

**后置条件：**每个故事都已填写层级、模块和 status: pending；每个 layer_introduced: 0 的活动都有 ≥1 个第 0 层故事。

---

第 3 步：依赖解析与波次（单 Agent）

一个专用 Agent 会接收所有故事，并生成：

• 故事图： 按层组织的有向无环图，展示依赖关系和并行机会。
• 波次（执行切片）： 在每一层内，将故事分组为可批量派发的波次。一个波次是一组彼此没有依赖关系、可以完全并行运行的故事。（YAML 字段为 stories[].slice；面向用户的术语是“波次”。）
• 每层的关键路径： 最长依赖链，决定完成该层所需的最短时间。
• 层级关卡： 在进入下一层之前必须通过的集成测试定义。每个关卡还会列出其计划的 journeys:（skills/e2e-test/journeys/<NN-slug>.md，每个能力领域一个；当 dogfood_target == none 时为空）——journeys: 是计划，evidence.journeys 记录实际运行的内容。由谁编写这些 journeys，以及它们何时执行，以 /aep-e2e-skill-scaffolding → references/layer-gate-loop.md 为准；承担成本的实时测试部分由 skills/e2e-test/policy.md 中的 live_policy 定价，因此在提出里程碑层时，请使用可以列入其中的名称。

将所有故事写入 product-context.yaml 的 stories 部分。同时填充 waves 部分，按层和波次对故事分组。

成果契约

对于定义了 outcome_contract 的每一层（见 product.layers[].outcome_contract），确保层级关卡测试定义与成功指标一致。如果某一层没有成果契约，可以考虑添加一个——Jeff Patton 强调，层应以成果为锚点，而不仅仅是功能完整性。

层完成后，/aep-reflect 会评估成果契约。它回答的是：“这一层是否实现了我们的假设？”

遥测绑定（可观测性）

项目在此处决定其遥测来源——先依据指标，再进行盘点。根据 references/telemetry-ingestion.md（§1.5 覆盖规则；§1 metric_map/endpoint/token_env 绑定的来源配置），将每个定量 success_metric 和所有受监控的 health_signals 绑定到一个来源。将结果写入 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，而 /aep-map 不会修改 product/index.yaml（它只会读取该文件）。

这是附加步骤——如果不存在能力地图，请跳过此步骤。

对齐层（.5 层）

定义完每个实现层后，规划 .5 对齐层，在执行过程中暂停以校准人类意图。检查 calibration.plan（或每层涉及的质量维度），并阅读作为 .5 层概念权威来源的 references/alignment-layers.md，了解重型与轻型维度规则、层级进展，以及经批准的 Object Map 如何为视觉设计和 UX 流程简报提供依据。重型维度需要设置 .5 层，并包含标记了 calibration_type 的故事；轻型维度则需要在进入下一个整数层之前设置 /aep-calibrate 检查点。

对象映射草案（面向 UI 的能力）

故事分解完成后，为每项面向 UI 的能力（声明为 object-model、visual-design/ux-flow 或用户面向的故事）生成一份以名词为先的草案对象映射。这将以动词为先的故事映射衔接到 UI。阅读 references/object-map-drafts.md，了解 ORCA 推导方法以及草案／已批准／过时规则，然后将 product/object-model.yaml 和 product/maps/<capability>/object-map.yaml 写入，并设为 status: draft——批准工作由 /aep-model 负责。对于没有面向 UI 的能力、纯后端／CLI 项目，完全跳过此步骤。

反馈循环

分解 Agent 可能会发现模块边界有误。它们会向系统映射提交修订提案。当修订累积到 3 项或更多，或任何单项修订影响接口契约时，继续之前先与用户进行一次架构审查。

后置条件：stories 和 waves 部分已写入；每一层都有一个 layer_gates 条目（含计划中的 journeys:）；每项面向 UI 的能力都有一个 status: draft 对象映射。

---

第 4 步：Agent 拓扑设计

拓扑是一项分解决策——它决定 /aep-launch 如何配置工作区，以及 /aep-build Agent 会收到哪些上下文，因此必须在执行前定义。使用 Agent 拓扑模板定义 Agent 角色、交接契约和路由规则（参见 templates/agent-topology.md）。每次 Agent 之间的交接都必须由架构定义，不能使用自由文本——在并行 Agent 之间，歧义会呈指数级累积。

Agent 角色定义

对于执行流水线中的每个角色，定义：

• **角色名称：**此类 Agent 的名称（例如 implementer、contract-verifier、integration-tester）
• **职责边界：**此 Agent 负责和不负责的事项。遵循单一职责原则。
• **输入契约：**此 Agent 收到的工作对象的确切结构。由架构定义，不能使用自由文本。
• **输出契约：**此 Agent 生成的工件的确切结构。由架构定义。
• **上下文窗口组成：**此 Agent 的上下文包含哪些内容——上下文文档的哪些部分、系统映射的哪些部分，以及哪些依赖工件。无关上下文会降低性能。
• **成本预算：**每次调用的预期令牌用量和耗时。

交接契约

对于每次 Agent 之间的交接：

• **触发条件：**导致交接的事件
• **负载：**传递的工件及其架构
• **验证：**接收 Agent 启动前对负载执行的检查

路由规则

• **分派策略：**如何从就绪队列分配故事
• **并发上限：**并行 Agent 的最大数量（起步时保持保守：5–10 个）
• **冲突检测：**修改相同文件的故事应分到不同批次
• **重试路由：**同一 Agent 重试 2 次 → 更换 Agent 并附上失败日志重试 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 — 带有 waves 的分层故事图（所有故事的初始状态均为 status: pending）
• waves — 按层级和 wave 分组的故事，用于批量调度
• topology — Agent 角色、交接契约、路由规则
• layer_gates — 每层的集成测试定义（与已定义的结果契约保持一致），每项均包含计划中的 journeys:（当 dogfood_target == none 时为空列表）。哪些门禁会消耗真实 dogfood 资源，由 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

如果项目包含面向用户界面的功能，请先批准 Object Map 草稿，再调度 UI 故事：

/aep-model

/aep-model 会展示 Object Map 草稿，供人工进行简短审核，然后将其状态设为 approved。接着开始执行故事：

/aep-dispatch

/aep-dispatch 会从 product-context.yaml 读取故事图，并推动故事在状态机中流转，依次通过 /aep-design → /aep-launch → /aep-build → /aep-wrap 进行路由。