prototype-to-product git:20261105.993e405A

Immutable. This exact content never changes and is served at /api/v1/blob/f045c71eb1db7ff8.

---
name: prototype-to-product
description: 将已确认的 HTML、Tailwind、Figma 导出或代码原型路由为当前仓库的正确工程交付：直接实现生产代码，或交接到项目采用的 OpenSpec、Superpowers 或其他工程治理流程。适用于需要在交付前识别并遵循项目实际框架、路由、组件库、设计令牌、数据模式、测试、代码检查、`AGENTS.md` 和本地约定的场景。
---

# 原型交付路由与产品化

先为已确认原型选择正确交付路径，再实施或交接。不得将原型本身当作应用架构；直接实现时，应将它的视觉和交互契约适配到当前仓库的既有约定中。

## 交付路由

默认 `delivery_mode: auto`。允许用户显式指定 `direct`、`openspec`、`superpowers` 或项目内另有名称的工程流程；用户指定优先。

在 `auto` 模式下，按以下顺序判断：

1. 读取所有适用的 `AGENTS.md`、贡献指南和项目文档，寻找强制的变更、计划、规格或审查流程。
2. 检测已配置的工程治理工具和目录，例如 OpenSpec 的 `openspec/`，Superpowers 相关 Skill / 指引，或项目明确声明的等价流程。只使用当前项目实际存在且被要求使用的工具；不得凭名称猜测模板或命令。
3. 即使仓库未强制要求，只要变更涉及 API 契约、数据模型 / 迁移、权限、跨模块流程、多人并行或高风险发布，也应建议进入项目的工程治理流程；工具选择不明确时停止并请用户或开发负责人确认。
4. 仅在没有强制流程且变更为局部、低风险、可由现有组件 / 路由 / 测试直接覆盖时选择 `direct`。

路由结果：

- **direct**：按本 Skill 的“实现”章节适配并验证生产代码。
- **openspec / superpowers / 其他已配置流程**：生成或更新该流程要求的交接工件，引用产品输入，然后停止在等待开发实施的边界。不得绕过该流程直接修改业务代码，除非用户明确授权且项目规则允许。
- **不确定**：不要假定 `direct`；记录检测结果并请求一个交付路径决定。

工程治理工件必须引用而非复制以下产品输入：功能 `prd.md`、`design.md`、已确认 `prototype.html`、`demo.md`（如有）以及对应端的产品体验基线。

## 必要的前置调研

编辑前按以下顺序检查：

1. 读取从仓库根目录到目标目录的每个适用 `AGENTS.md`；子目录使用最具体的文件。
2. 从清单和配置文件识别项目根目录、包管理器锁文件、框架、语言、构建命令、代码检查/类型检查/测试命令和运行要求。
3. 定位目标路由或页面及其最接近的现有同级页面；检查该页面的组件边界、导入、数据加载、加载/错误/空态、样式系统、测试和无障碍模式。
4. 定位共享 UI 层：令牌、主题、排版、图标、表单控件、布局基础组件以及任何组件库封装。
5. 查找 `docs/product/` 中当前项目、当前端（`c-end/` 或 `admin/`）的产品体验基线；读取产品术语、信息架构、页面模式和已确认的组件规则。基线缺失时记录缺口，不得假定原型中的模式已是产品标准。
6. 阅读原型及相关的 `design.md` / `DESIGN.md`、`demo.md`；只识别需要保留的视觉契约：布局层级、令牌、字阶、组件结构、内容优先级、已记录状态和响应式行为。
7. 完成“交付路由”判断，并将结果、证据、风险和交接边界写入功能目录的 `delivery.md`；项目已有等价工件时更新该工件，不重复创建平行文档。

改动源文件前阅读 [references/adaptation-contract.md](references/adaptation-contract.md)。

## 解决冲突

遵循以下权威顺序：

1. 仓库的 `AGENTS.md`、安全指引和项目约定。
2. 现有应用架构、共享组件和既定路由/数据模式。
3. 已确认的产品体验基线。
4. 已确认的产品需求与已记录行为。
5. 已批准原型和设计规格，用于视觉契约。

保留原型的视觉意图，而非其偶然的实现选择。不得把 CDN 脚本、独立 CSS 重置、临时模拟集成、重复 UI 基础组件或不同框架复制到产品中。原型和既有组件冲突时，先使用令牌或支持的变体来适配组件；无法避免视觉差异时，说明原因。

## 直接实现

仅当路由结果为 `direct` 时执行。

1. 规划最小且完整的变更集合：路由/页面、可复用组件、样式/令牌、模拟数据或 API 绑定，以及测试；先把模式分类为“复用既有”“功能局部”或“候选晋升”。
2. 在创建组件前复用项目基础组件；只有模式已在产品体验基线中确认可复用且没有适用现有组件时，才新增基础组件。单次功能中出现的新模式保持局部，不得自动晋升为全局组件。
3. 将原型标记转换为项目组件模型；如果本地模式如此要求，领域数据和副作用应置于展示组件之外。
4. 将原型占位符替换为项目拥有的内容、资源、路由和状态处理；不得虚构后端 API、认证、支付、分析或第三方集成。
5. 实现所有已记录的 UI 状态；状态缺少产品行为时，使用项目的标准降级方案或明确标记为待定依赖。
6. 使用项目断点保留响应式行为；原型没有移动端证据时，遵循既有响应式模式，并说明这项推断。
7. 保留无障碍能力：语义地标、真实标签、键盘操作、焦点可见性、非颜色状态提示与减少动态效果支持。

## 验证

### Direct 路径

1. 运行已发现脚本中范围最小的相关检查：按情况执行类型检查、代码检查、定向测试和构建。
2. 本地预览可用时，在相关路由检查桌面和移动端断点、加载/错误/空态和键盘导航。

### 工程治理路径

1. 按项目实际工具的要求校验工件格式、规格覆盖范围和任务完整性。
2. 确认工件可追溯到 PRD、设计证据、原型、评审结论和产品体验基线。
3. 检查无法运行时，说明确切环境阻碍，并完成静态验证；不得声称未执行的检查已成功。
4. 保持无关文件不变；不得替换用户工作或格式化无关代码。

## 交付说明

报告以下内容：

- 选择的交付路径、判断证据，以及是否发现 OpenSpec、Superpowers 或其他项目工程流程。
- `direct` 时：已实现的路由和改动文件。
- 工程治理路径时：已生成或更新的交接工件，以及等待开发实施的边界。
- 所遵循的项目约定和复用基础组件。
- 保留的原型/设计规格规则，以及有意偏离之处。
- 已执行的测试或检查、结果和限制。
- 尚未解决的产品决策、集成或缺失状态。
- 使用的产品体验基线，以及“功能局部”或“候选晋升”模式的判断和理由。