Spec Product Demo

spec-product-demo（R4：基于原型生成可交互 Demo）

概览

R4 的目标是把 {FEATURE_DIR}/requirements/prototype.md 的页面清单与交互说明落地为可运行、可交互的 Demo，用于走查/验证/对齐：

• 唯一页面来源：只能来自 prototype.md/页面/弹窗清单（P-xxx…）（禁止自创页面）
• 共享工程模式：默认落到 {REPO_ROOT}/demo/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/
• 先骨架后细节：先跑通路由/导航/跳转链路，再补字段/状态/校验/错误处理
• 数据可 Mock：后端未就绪允许 Mock，但要把“真实数据接入”当作明确替换点

开始时宣布：「我正在使用 spec-product-demo 技能基于 prototype.md 生成可交互 Demo。」

R4 的核心价值是“把线框变成可点可跑”，不是替代设计稿，也不是在 Demo 里自由发挥新增需求。

何时使用 / 不使用

• 使用时机
  • 已完成 R3，且存在 {FEATURE_DIR}/requirements/prototype.md
  • 需要更高保真走查（可用性验证/干系人对齐/研发与测试理解一致性校验）
• 不要用在
  • spec-context 失败 → 立刻停止
  • {FEATURE_DIR}/requirements/prototype.md 缺失 → 停止并回到 using-aidlc（路由到 R3：spec-product-prototype）
  • 仓库里没有可运行的 Demo 工程根目录，且用户未提供 DEMO_PROJECT_ROOT → 停止并要求提供路径

输入 / 输出（落盘约定）

• 硬门禁输入：FEATURE_DIR（必须由 spec-context 获取）
• 读取
  • {FEATURE_DIR}/requirements/prototype.md（必读，页面清单/交互说明 SSOT）
• 可选输入
  • DEMO_PROJECT_ROOT：可运行的 Demo 工程根目录（存在 package.json 且包含可启动脚本）
• 写入
  • Demo 代码：默认 {REPO_ROOT}/demo/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/（共享工程模式）

门禁（必须先过，否则停止）

1) REQUIRED SUB-SKILL：正在执行 spec-context 获取上下文，并回显 FEATURE_DIR=...（允许 (reuse)）

• spec-context 失败 → 停止
• {FEATURE_DIR}/requirements/prototype.md 不存在 → 停止（不得“先做个占位 Demo”）

违反门禁=违反精神：无论“老板 10 分钟后评审/先做出来再补/在 main 上先跑一版”，都禁止跳过上下文与输入文件。

2) Demo 工程根目录定位（必须遵守；找不到就停止）

判定“可运行 Demo 工程根目录”的最低标准：

• 目录存在
• 存在 package.json
• package.json 至少包含可启动脚本（例如 dev / start / preview 其一）

定位规则（从高到低）：

1. 优先使用输入：用户提供 DEMO_PROJECT_ROOT → 以其为准（仍需满足可运行判定）
2. 未提供则自动查找：
   • {REPO_ROOT}/demo/
   • {REPO_ROOT}/prototype/ 或 {REPO_ROOT}/prototypes/
   • {REPO_ROOT}/apps/demo/、{REPO_ROOT}/packages/demo/
3. 查找失败就停止：以上路径均不存在或不满足可运行判定 → 停止 R4，并要求用户提供 DEMO_PROJECT_ROOT

硬禁止：在“未找到可运行 Demo 工程根目录”时，擅自初始化新的前端工程（Vite/Next.js/CRA 等）来“先跑起来”。这会污染仓库、破坏流程可追溯性。

核心流程（从 prototype 到可跑 Demo）

0) 输出目录固定：只写到 prototypes/{SPEC_NUMBER}-{SHORT_NAME}/

在 DEMO_PROJECT_ROOT 下为当前需求创建独立命名空间：

• OUTPUT_DIR = {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/

规则：

• 需求实现必须落在 OUTPUT_DIR：页面/组件/样式/Mock/交互逻辑等都写在 OUTPUT_DIR 内，避免污染其他需求
• 允许最小粘合改动：可在 Demo 根工程做最小改动用于“挂载当前需求”（例如路由注册、入口菜单、通用 layout），但禁止修改其他需求的 prototypes/* 目录
• 目录名必须精确等于 {SPEC_NUMBER}-{SHORT_NAME}（禁止手写或另起别名）

1) 从 prototype.md 生成页面任务清单（不落盘）

以 prototype.md/页面/弹窗清单 为唯一页面来源（SSOT）：

• 每个 P-xxx 至少 1 个任务条目（可再细分）
• 每个条目必须包含：
  • 页面路由/入口、页面目标
  • 主要控件/字段与默认值
  • 关键状态（正常/加载/空/错误/无权限）与提示文案要点
  • 与任务流节点（T-xxx）及 AC 的映射（引用 prototype.md 位置）

禁止：为“看起来更完整”而新增登录页/设置页/通用布局页等未在 prototype.md 声明的页面。需要新增页面 → 回流 R3 更新 prototype.md 后再做 R4。

2) 先搭骨架（必须先跑通）

先完成：

• 所有页面/弹窗的路由或入口占位
• 导航入口与关键跳转链路（至少覆盖核心任务流主链路）

此阶段允许：

• 仅用静态/Mock 数据渲染
• 仅实现关键按钮与跳转（字段/校验可后补）

3) 再补细节（按优先级）

按“核心主链路优先”补齐：

• 字段与校验（含错误提示要点）
• 状态与异常分支（加载/空/失败/无权限）
• 交互细节（取消/返回/二次确认/恢复路径）

数据依赖未就绪时：

• 用 Mock 数据/Mock API 让交互可跑
• 把“真实数据接入”作为明确替换点（避免把 Mock 当最终实现）

4) 运行与冒烟（完成检查）

最小完成标准（缺一不可）：

• Demo 工程可启动
• 可导航到 OUTPUT_DIR 的页面集合
• 关键链路可走通（至少覆盖 prototype.md 的核心任务流主链路）

完成后：立即调用 using-aidlc 路由下一步（通常进入走查/回流，或继续后续阶段）。

完成后输出与自动路由（必须执行）

Demo 落盘至 {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/ 后，必须完成以下动作（按顺序，不可省略）：

1. 输出 ROUTER_SUMMARY（YAML 形态，供 Router 决策）：

ROUTER_SUMMARY:
  stage: R4
  artifacts:
    - "{DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/"
  needs_human_review: false
  blocked: false
  block_reason: ""
  notes: "软检查点：Demo 建议走查；如不触发硬中断 Router 可继续自动推进"

2. 立即执行 using-aidlc：将上述 ROUTER_SUMMARY 作为路由输入传递给 using-aidlc，由 Router 判定下一步并自动推进（无需等待用户说「继续」）。

   • 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill（如 D0、I1 等）
   • 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步

3. 对话输出：在调用 using-aidlc 前，可简短说明「本阶段产物已落盘，正在调用 using-aidlc 路由下一步。」

Quick reference（高频规则速查）

• 必须
  • 先执行 spec-context 获取上下文，只用其输出的 FEATURE_DIR/REPO_ROOT/SPEC_NUMBER/SHORT_NAME
  • 必须存在 {FEATURE_DIR}/requirements/prototype.md
  • 页面清单只来自 prototype.md（不加页）
  • Demo 根目录找不到/不可运行 → 立即停止并要求 DEMO_PROJECT_ROOT
  • 需求实现写在 {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/；Demo 根工程只做最小粘合改动（路由/入口）
• 禁止
  • 在 main（或非 {num}-{short-name} 分支）上硬做 R4
  • 用“先做占位 Demo”替代缺失的 prototype.md
  • 未找到 Demo 工程根目录时擅自 npm create vite@latest / npx create-next-app 初始化新工程
  • 自创页面/路由并声称“demo 常见”

红旗清单（出现任一条：停止并纠正）

• 没跑 spec-context 就开始找/写 requirements/*.md 或 demo 目录
• {FEATURE_DIR}/requirements/prototype.md 不存在，却仍要继续
• Demo 根目录不存在/不可运行，却仍要“先初始化一个 Vite 工程”
• 在 Demo 里新增 prototype.md 未定义的页面（登录/设置/随便加页）
• 输出目录不是 prototypes/{SPEC_NUMBER}-{SHORT_NAME}（写到根目录、写错 spec 目录名、或写到别的需求目录）

常见借口与反制（基线测试中的高频点）

一个好例子（找不到 Demo 根目录时如何正确停止）

当未提供 DEMO_PROJECT_ROOT 且自动查找失败时，应当输出类似结论：

• 阻断原因：当前仓库未发现可运行的 Demo 工程根目录（缺 demo/ 或缺 package.json/启动脚本）
• 需要用户提供：DEMO_PROJECT_ROOT（例如 E:\\path\\to\\demo），并说明其必须可启动
• 下一步：拿到 DEMO_PROJECT_ROOT 后，在 {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/ 生成 Demo