aep-envision

Envision

将模糊的产品想法转化为精确、可测试的产品定义。先验证这个机会是否值得追求（Phase 0），再以足够精确的方式定义产品，确保下游 Agent 不会产生歧义（Phase 1）。

适用场景：

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

• 会话： Main，与用户交互
• 输入： 产品想法（模糊或已细化）
• 输出： 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 回答“具体要开发什么？”——将两者分开可以避免过早投入，以及因沉没成本偏见而不愿放弃糟糕的想法。

如何执行此阶段

让用户自由描述想法，并在过程中提取原始信息：

• 是什么促使用户产生这个想法——个人痛点、市场空白，还是技术能力？
• 谁现在面临这个问题？他们目前如何解决？
• 如果这款产品存在，世界会发生什么变化？
• 用户有哪些不公平优势——技术技能、领域知识，还是现有受众？
• 这个想法最可能失败或无关紧要的原因是什么？

充分发散后，综合整理一份机会简报（一页，参见 templates/opportunity-brief.md），概括核心论点：“我相信[目标用户]有[问题]，而我能构建[解决方案]，因为我具备[优势]。”

终止判断点

将机会简报展示给用户，并提出三个是非挑战问题，进行一次诚恳的五分钟审视。任何一个回答为否，都应停止此阶段（终止或暂缓）：

1. 这个问题对某个具体且明确的用户而言，是真实且迫切的吗？
2. 是否存在真正的“为什么是现在”，以及属于你的不公平优势？
3. 最有力的反对理由是否不足以否定这个想法？其影响是否值得承担后续开发成本？

尽早终止是在此工作流中投资回报率最高的决策。在简报的 Decision 部分记录决定：

• 继续 → Phase 1
• 终止 → 停止；仍将简报保存为记录
• 暂缓 → 保存简报，并注明重新评估的条件

Phase 0 输出

将最终版机会简报写入 opportunity 部分——拆分模式下的 product/index.yaml，或 V1 模式下的 product-context.yaml。

后置条件： 模式对应的目标文件中存在 opportunity 部分，且已记录终止判断点的决定（继续／终止／暂缓）。

---

Phase 1：产品定义

目标： 将经过验证的机会转化为精确的产品定义，供下游 Agent 使用且不会产生歧义。任何未明确的假设都会迫使下游 Agent 靠猜测来解决——此阶段会将每个假设明确写出。

阶段 1：发散

从阶段 0 的对话继续，现在聚焦于产品细节：

• 问题陈述： 进一步明确。不要写成“开发者需要更好的工具”，而要写成“边缘平台上的独立开发者每个项目都会因现有解决方案默认采用 AWS/GCP，而在 Agent 沙盒化上浪费 4 个多小时”。
• 用户画像 / JTBD： 主要用户具体是谁？他们雇用这个产品来完成什么任务？对他们来说，怎样才算成功？
• MVP 边界： 用户能够端到端完成的最重要单一流程是什么？哪些内容明确不纳入范围，即使它们与核心流程相邻且很诱人？
• 用户活动（故事地图主干）： 用户逐步会做什么？以从左到右的动词短语叙述，例如“身份验证”“创建个人资料”“生成内容”“跟踪进度”“下载输出”。先构建这个主干，再定义分层——各层横跨主干。
• 技术约束： 不可妥协的技术栈、基础设施和硬依赖。
• 质量维度： 哪些维度需要人类判断，Agent 无法提供——仅限那些可能出现“正确但不合适”的维度。七个品味维度（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——它能防止构建 Agent 擅自设计“一步一屏”的向导式 UI（纯后端/CLI 项目除外）。对于每个声明的维度，记录最可能首次进行校准的层，以及原因。
• 分层 MVP 契约： 第 0 层是行走骨架——从每项活动中各取最精简的故事，沿主干横向切分。之后每一层都会增加能力（也可以通过向右延伸主干来增加新活动）。.5 层是人工对齐层：Agent 执行会在此暂停，以便围绕一个或多个质量维度校准意图（规范定义见 /aep-map 的 references/alignment-layers.md）。calibration.plan 将各层映射到预期的检查点。

阶段 2：组织结构

将所有内容整理到 Context Document（templates/context-document.md）中，并展示草案。填写 product.quality_dimensions——对每个声明的维度记录维度、关键程度、首次校准层和理由。

质量标准：每条陈述都必须能转化为验证条件。“系统应具备良好性能”不合格；“API p95 延迟 < 200ms”合格。

阶段 3：压力测试（独立 Agent）

将 Context Document 交给未参与对话的 Agent。它们从三个角度冷静审阅，各自生成一份质疑清单：

1. 产品可行性——关于用户和问题的假设是否经过验证？最有力的反驳是什么？
2. 技术可行性——技术选择是否相互兼容且足够适用？有哪些已知限制？
3. 范围控制——MVP 是否真正精简？能否删去任何一层？

用户逐项处理——修订文档，或将其标记为显式的 open_question，并注明默认假设和重新审视的触发条件。将结果记录在 product.stress_test 中。（此压力测试属于构建前校准；/aep-calibrate 会将其扩展到仅在 Agent 产出内容后才可见的维度。）

阶段 1 输出

Split 模式：

1. 将上下文文档写入 product/index.yaml：
   • opportunity（来自阶段 0）
   • personas（包含 id、description、jtbd 的列表）
   • capabilities（至少 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 部分已写入该模式对应的目标文件，且（在 Split 模式下）product-context.yaml 中存在 calibration.plan 和一条 changelog 记录。

能力地图（适用于多旅程产品）

如果产品有 2 个或更多不同的用户旅程：确保 capabilities[] 中有多个条目，并为每项能力创建 product/maps/<capability-id>/frame.yaml（包含范围、边界、主要用户、结果契约），遵循 templates/product-context-schema.yaml 中的架构。故事占位条目稍后由 /aep-map 填充。单旅程产品保留一个能力条目，并跳过 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 用于梳理新的或已发生变化的机会——当主干发生变化（新增、移除或重新排序活动），或产品定位发生变化（persona、JTBD、MVP 边界、已失效的机会假设）时，应触发该流程。/aep-reflect 用于对已发布工作的反馈进行归类——它负责重新切分（在层之间移动故事、添加故事、重新确定优先级），而不涉及 envision。详情：docs/decisions/release-line-adjustments.md。

---

下一步

产品已完成构想。继续执行 /aep-map——它会将上下文文档拆解为系统地图、分层故事图和 Agent 拓扑。