spec-product-demo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

spec-product-demo (R4: Generate Interactive Demo from Prototype)

概览

Overview

R4 的目标是把

{FEATURE_DIR}/requirements/prototype.md

的页面清单与交互说明落地为可运行、可交互的 Demo，用于走查/验证/对齐：

唯一页面来源：只能来自
```
prototype.md/页面/弹窗清单（P-xxx…）
```
（禁止自创页面）

共享工程模式：默认落到

{REPO_ROOT}/demo/prototypes/{CURRENT_BRANCH}/

先骨架后细节：先跑通路由/导航/跳转链路，再补字段/状态/校验/错误处理
数据可 Mock：后端未就绪允许 Mock，但要把“真实数据接入”当作明确替换点

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

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

The goal of R4 is to implement the page list and interaction instructions in

{FEATURE_DIR}/requirements/prototype.md

into a runnable, interactive Demo for walkthrough/validation/alignment:

Single Source of Pages: Only come from
```
prototype.md/Page/Popup List (P-xxx…)
```
(custom pages are prohibited)

Shared Project Mode: Default to

{REPO_ROOT}/demo/prototypes/{CURRENT_BRANCH}/

Skeleton First, Details Later: First get the routing/navigation/jump links working, then add fields/states/validation/error handling
Mockable Data: Mock data is allowed if the backend is not ready, but "real data integration" must be marked as a clear replacement point

Announce at the start: "I am using the spec-product-demo skill to generate an interactive Demo based on prototype.md."

The core value of R4 is "turn wireframes into clickable, runnable demos", not to replace design drafts, nor to freely add new requirements in the Demo.

何时使用 / 不使用

When to Use / Not to Use

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

When to Use
- R3 has been completed, and
```
{FEATURE_DIR}/requirements/prototype.md
```
  exists
- Higher-fidelity walkthrough is needed (usability validation/stakeholder alignment/consistency check between R&D and testing understanding)
Do Not Use
- ```
spec-context
```
  fails → Stop immediately
- ```
{FEATURE_DIR}/requirements/prototype.md
```
  is missing → Stop and return to
  using-aisdlc
  (route to R3:
```
spec-product-prototype
```
  )
- No runnable Demo project root directory exists in the repo, and the user has not provided
```
DEMO_PROJECT_ROOT
```
  → Stop and request the path

输入 / 输出（落盘约定）

Input / Output (Storage Convention)

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

Mandatory Input:
```
FEATURE_DIR
```
(must be obtained from
```
spec-context
```
)
Read
- ```
{FEATURE_DIR}/requirements/prototype.md
```
  (required, SSOT for page list/interaction instructions)
Optional Input
- ```
DEMO_PROJECT_ROOT
```
  : Runnable Demo project root directory (contains
```
package.json
```
  with at least one start script)
Write
- Demo code: Default to
```
{REPO_ROOT}/demo/prototypes/{CURRENT_BRANCH}/
```
  (shared project mode)

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

Gatekeepers (Must Pass First, Otherwise Stop)

1) REQUIRED SUB-SKILL：先满足

spec-context

门禁并回显

FEATURE_DIR=...

（允许

(reuse)

）

1) REQUIRED SUB-SKILL: First meet the

spec-context

gatekeeper and echo

FEATURE_DIR=...

(allow

(reuse)

)

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

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

```
spec-context
```
fails → Stop
```
{FEATURE_DIR}/requirements/prototype.md
```
does not exist → Stop (do not "create a placeholder Demo first")

Violating gatekeepers = violating the spirit: Regardless of "boss review in 10 minutes / make it first then supplement / run it on main first", skipping context and input files is prohibited.

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

2) Demo Project Root Directory Location (Must Comply; Stop if Not Found)

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

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

定位规则（从高到低）：

优先使用输入：用户提供
```
DEMO_PROJECT_ROOT
```
→ 以其为准（仍需满足可运行判定）

未提供则自动查找：

```
{REPO_ROOT}/demo/
```

{REPO_ROOT}/prototype/

或

{REPO_ROOT}/prototypes/

{REPO_ROOT}/apps/demo/

、

{REPO_ROOT}/packages/demo/

查找失败就停止：以上路径均不存在或不满足可运行判定 → 停止 R4，并要求用户提供
DEMO_PROJECT_ROOT

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

Minimum criteria for determining a "runnable Demo project root directory":

Directory exists
```
package.json
```
exists
```
package.json
```
contains at least one start script (e.g.,
```
dev
```
/
```
start
```
/
```
preview
```
)

Location rules (from highest to lowest priority):

Prioritize User Input: If user provides
```
DEMO_PROJECT_ROOT
```
→ use it (still must meet runnability criteria)

Auto-search if Not Provided:

```
{REPO_ROOT}/demo/
```

{REPO_ROOT}/prototype/

{REPO_ROOT}/prototypes/

{REPO_ROOT}/apps/demo/

{REPO_ROOT}/packages/demo/

Stop if Search Fails: If none of the above paths exist or meet runnability criteria → Stop R4 and request the user to provide
DEMO_PROJECT_ROOT

Strictly Prohibited: When no runnable Demo project root directory is found, initialize a new frontend project (Vite/Next.js/CRA, etc.) without permission to "get it running first". This will pollute the repo and destroy process traceability.

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

Core Process (From Prototype to Runnable Demo)

0) 输出目录固定：只写到

prototypes/{CURRENT_BRANCH}/

0) Fixed Output Directory: Only write to

prototypes/{CURRENT_BRANCH}/

在

DEMO_PROJECT_ROOT

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

OUTPUT_DIR = {DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/

规则：

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

Create an independent namespace for the current requirement under

DEMO_PROJECT_ROOT

OUTPUT_DIR = {DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/

Rules:

Requirement implementation must be in
OUTPUT_DIR
: Pages/components/styles/Mock/interaction logic, etc., must be written in
```
OUTPUT_DIR
```
to avoid polluting other requirements
Allow minimal glue changes: Minimal changes can be made to the Demo root project to "mount the current requirement" (e.g., route registration, entry menu, general layout), but modifying other requirements'
```
prototypes/*
```
directories is prohibited
Directory name must exactly match
```
CURRENT_BRANCH
```
(handwriting or aliases are prohibited)

1) 从

prototype.md

生成页面任务清单（不落盘）

1) Generate Page Task List from

prototype.md

(No Storage)

以

prototype.md/页面/弹窗清单

为唯一页面来源（SSOT）：

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

禁止：为“看起来更完整”而新增登录页/设置页/通用布局页等未在

prototype.md

声明的页面。需要新增页面 → 回流 R3 更新

prototype.md

后再做 R4。

Take

prototype.md/Page/Popup List

as the only page source (SSOT):

At least 1 task entry per
```
P-xxx
```
(can be subdivided)
Each entry must include:
- Page route/entry, page objective
- Main controls/fields and default values
- Key states (normal/loading/empty/error/no permission) and tips copy points
- Mapping to task flow nodes (T-xxx) and AC (reference location in
```
prototype.md
```
  )

Prohibited: Adding pages not declared in

prototype.md

such as login page/settings page/general layout page to "look more complete". To add pages → return to R3 to update

prototype.md

before proceeding with R4.

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

2) Build the Skeleton First (Must Be Runnable First)

先完成：

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

此阶段允许：

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

Complete first:

Route or entry placeholders for all pages/popups
Navigation entries and key jump links (at least cover the main core task flow)

This phase allows:

Rendering only with static/Mock data
Only implementing key buttons and jumps (fields/validation can be added later)

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

3) Fill in Details (By Priority)

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

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

数据依赖未就绪时：

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

Fill in by "core main link first":

Fields and validation (including error prompt points)
States and exception branches (loading/empty/failure/no permission)
Interaction details (cancel/return/secondary confirmation/restore path)

When data dependencies are not ready:

Use Mock data/Mock API to make interactions runnable
Mark "real data integration" as a clear replacement point (avoid treating Mock as final implementation)

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

4) Run and Smoke Test (Completion Check)

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

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

完成后：回到

using-aisdlc

路由下一步（通常进入走查/回流，或继续后续阶段）。

Minimum completion criteria (all required):

Demo project can be started
Can navigate to the page set in
```
OUTPUT_DIR
```
Key links can be traversed (at least cover the main core task flow in
```
prototype.md
```
)

After completion: Return to

using-aisdlc

for next routing (usually enter walkthrough/feedback, or continue to subsequent stages).

完成后输出（供

using-aisdlc

自动推进读取）

Post-Completion Output (For

using-aisdlc

Automatic Progress Reading)

在回答末尾追加以下两段（不要省略）：

「本阶段产物已落盘。请回到
```
using-aisdlc
```
进行下一步路由（如未触发人工门禁，Router 可自动续跑）。」
```
ROUTER_SUMMARY
```
：

yaml

ROUTER_SUMMARY:
  stage: R4
  artifacts:
    - "{DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "Demo 建议人工走查；若发现偏差按 R1/R2/R3 回流修订"

Append the following two paragraphs at the end of the answer (do not omit):

"The artifacts of this phase have been stored. Please return to
```
using-aisdlc
```
for next routing (if no manual gatekeeper is triggered, Router can automatically continue)."
```
ROUTER_SUMMARY
```
:

yaml

ROUTER_SUMMARY:
  stage: R4
  artifacts:
    - "{DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "Demo 建议人工走查；若发现偏差按 R1/R2/R3 回流修订"

Quick reference（高频规则速查）

Quick Reference (High-Frequency Rules Cheat Sheet)

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

Must
- Run
```
spec-context
```
  first, only use its output
```
FEATURE_DIR/CURRENT_BRANCH/REPO_ROOT
```
- ```
{FEATURE_DIR}/requirements/prototype.md
```
  must exist
- Page list only comes from
```
prototype.md
```
  (no additional pages)
- If Demo root directory is not found/not runnable → Stop immediately and request
```
DEMO_PROJECT_ROOT
```
- Requirement implementation is written in
```
{DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/
```
  ; only minimal glue changes (route/entry) are allowed in the Demo root project
Prohibited
- Hardcode R4 on main (or non
```
{num}-{short-name}
```
  branches)
- Replace missing
```
prototype.md
```
  with "placeholder Demo first"
- Unauthorized initialization of new projects with
```
npm create vite@latest
```
  /
```
npx create-next-app
```
  when Demo project root directory is not found
- Creating custom pages/routes and claiming "common in demos"

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

Red Flag List (Stop and Correct if Any Appears)

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

Starting to look for/write
```
requirements/*.md
```
or demo directories without running
```
spec-context
```
Proceeding even though
```
{FEATURE_DIR}/requirements/prototype.md
```
does not exist
Unauthorized initialization of a Vite/Next.js project when Demo project root directory is not found
Adding pages not defined in
```
prototype.md
```
to the Demo (login/settings/random pages)
Output directory is not
```
prototypes/{CURRENT_BRANCH}
```
(written to root directory, wrong branch name, or other requirement directories)

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

A Good Example (How to Correctly Stop When Demo Root Directory is Not Found)

借口（压力来源）	常见违规行为	必须的反制动作
“老板 10 分钟后要看，先在 main 上做一版”	跳过 `spec-context` ；在 main 上写 demo	门禁不过就停止：先切到合法 spec 分支并跑 `spec-context` ；否则只能交付“阻断原因 + 需要的输入/下一步”
“prototype 还没写/找不到，就先做个占位 Demo”	自创页面与流程，导致不可追溯	`prototype.md` 缺失 → 回到 `using-aisdlc` 路由到 R3；R4 禁止替代 R3 的交互决策
“仓库里没有 demo/，我先初始化一个 Vite/Next.js 工程”	在未知位置创建新工程污染仓库	停止并要求 `DEMO_PROJECT_ROOT` ；只有在已存在可运行 demo 工程时才允许继续
“顺便加登录页/设置页，demo 常见”	自创页面，偏离 SSOT	拒绝加页并回流 R3：先把页面写进 `prototype.md` 的页面清单（含编号、说明、AC 映射）

When

DEMO_PROJECT_ROOT

is not provided and auto-search fails, output a conclusion similar to:

Block reason: No runnable Demo project root directory found in the current repo (missing
```
demo/
```
or missing
```
package.json
```
/start script)
Need user to provide:
```
DEMO_PROJECT_ROOT
```
(e.g.,
```
E:\\path\\to\\demo
```
), and explain that it must be runnable

Next step: After obtaining

DEMO_PROJECT_ROOT

, generate the Demo in

{DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/

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

—

当未提供

DEMO_PROJECT_ROOT

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

阻断原因：当前仓库未发现可运行的 Demo 工程根目录（缺
```
demo/
```
或缺
```
package.json
```
/启动脚本）
需要用户提供：
```
DEMO_PROJECT_ROOT
```
（例如
```
E:\\path\\to\\demo
```
），并说明其必须可启动

下一步：拿到

DEMO_PROJECT_ROOT

后，在

{DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/

生成 Demo

—

spec-product-demo

Original

Translation

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

spec-product-demo (R4: Generate Interactive Demo from Prototype)

概览

Overview

何时使用 / 不使用

When to Use / Not to Use

输入 / 输出（落盘约定）

Input / Output (Storage Convention)

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

Gatekeepers (Must Pass First, Otherwise Stop)

1) REQUIRED SUB-SKILL：先满足
`spec-context`
门禁并回显
`FEATURE_DIR=...`
（允许
`(reuse)`
）

1) REQUIRED SUB-SKILL: First meet the
`spec-context`
gatekeeper and echo
`FEATURE_DIR=...`
(allow
`(reuse)`
)

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

2) Demo Project Root Directory Location (Must Comply; Stop if Not Found)

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

Core Process (From Prototype to Runnable Demo)

0) 输出目录固定：只写到
`prototypes/{CURRENT_BRANCH}/`

0) Fixed Output Directory: Only write to
`prototypes/{CURRENT_BRANCH}/`

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

1) Generate Page Task List from
`prototype.md`
(No Storage)

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

2) Build the Skeleton First (Must Be Runnable First)

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

3) Fill in Details (By Priority)

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

4) Run and Smoke Test (Completion Check)

完成后输出（供
`using-aisdlc`
自动推进读取）

Post-Completion Output (For
`using-aisdlc`
Automatic Progress Reading)

Quick reference（高频规则速查）

Quick Reference (High-Frequency Rules Cheat Sheet)

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

Red Flag List (Stop and Correct if Any Appears)

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

A Good Example (How to Correctly Stop When Demo Root Directory is Not Found)

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

spec-product-demo

Original

Translation

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

spec-product-demo (R4: Generate Interactive Demo from Prototype)

概览

Overview

何时使用 / 不使用

When to Use / Not to Use

输入 / 输出（落盘约定）

Input / Output (Storage Convention)

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

Gatekeepers (Must Pass First, Otherwise Stop)

1) REQUIRED SUB-SKILL：先满足 spec-context 门禁并回显 FEATURE_DIR=...（允许 (reuse)）

1) REQUIRED SUB-SKILL: First meet the spec-context gatekeeper and echo FEATURE_DIR=... (allow (reuse))

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

2) Demo Project Root Directory Location (Must Comply; Stop if Not Found)

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

Core Process (From Prototype to Runnable Demo)

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

0) Fixed Output Directory: Only write to prototypes/{CURRENT_BRANCH}/

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

1) Generate Page Task List from prototype.md (No Storage)

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

2) Build the Skeleton First (Must Be Runnable First)

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

3) Fill in Details (By Priority)

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

4) Run and Smoke Test (Completion Check)

完成后输出（供 using-aisdlc 自动推进读取）

Post-Completion Output (For using-aisdlc Automatic Progress Reading)

Quick reference（高频规则速查）

Quick Reference (High-Frequency Rules Cheat Sheet)

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

Red Flag List (Stop and Correct if Any Appears)

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

A Good Example (How to Correctly Stop When Demo Root Directory is Not Found)

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

1) REQUIRED SUB-SKILL：先满足
`spec-context`
门禁并回显
`FEATURE_DIR=...`
（允许
`(reuse)`
）

1) REQUIRED SUB-SKILL: First meet the
`spec-context`
gatekeeper and echo
`FEATURE_DIR=...`
(allow
`(reuse)`
)

0) 输出目录固定：只写到
`prototypes/{CURRENT_BRANCH}/`

0) Fixed Output Directory: Only write to
`prototypes/{CURRENT_BRANCH}/`

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

1) Generate Page Task List from
`prototype.md`
(No Storage)

完成后输出（供
`using-aisdlc`
自动推进读取）

Post-Completion Output (For
`using-aisdlc`
Automatic Progress Reading)