Vibe Product Development

一个面向 Codex 的产品开发 Skill：把模糊需求逐步收敛为可确认的 PRD、设计/接口基线、技术方案、垂直切片交付与可审计证据。

适用场景

• 从一句模糊需求开始的 Web、管理后台、小程序、移动端、桌面端、API、CLI、Worker、数据和模型项目；
• 已有 PRD 的版本演进、范围变更和基线漂移管理；
• 已确认 HTML/设计稿到原生组件项目的迁移；
• 需要根据风险程度控制文档数量和沟通成本的 Vibe Coding 项目。

不适用于孤立 Bug 修复、已经明确的小范围代码修改或普通技术问答。

核心原则

1. 第一次理解只生成 PRD v0.1，经过客户回放和批准后才形成正式 v1.0+ 基线。
2. 使用最低足够的 Profile：prototype、lite、standard、transactional、regulated。
3. Surface 可组合，不把技术栈写死：例如 mini-program + admin-web + api + worker。
4. 默认按当前 Gate 懒创建文档，避免提前生成大量空模板。
5. HTML/截图是设计证据，不直接当作生产代码；先冻结视觉契约，再迁移为目标技术栈的组件。
6. 已批准的产品、设计/契约和技术文件发生变化时，自动使下游 Gate 失效。

宏 Gate

生产项目：

Align → Baseline → Technical Ready → Delivery → Release

一次性原型：

Align → Prototype

Baseline 内部仍然执行：

Contract Draft → Formal Design / Interface Spec → Contract Freeze

目录结构

SKILL.md                         Skill 主入口
agents/openai.yaml               Codex 展示名称与默认提示词
assets/templates/                compact/full 两套项目模板
references/                      按需加载的流程、PRD、设计和技术参考
scripts/init_project.py          初始化项目状态
scripts/migrate_project.py       v2/v3 或 Profile/Surface 安全迁移
scripts/check_gates.py           Gate 校验、证据和漂移检测
scripts/snapshot_prd.py          生成不可变 PRD/产品快照
scripts/evidence.py              记录脱敏、限长、哈希后的执行证据
scripts/inventory_html.py        HTML 资源清单与外部引用检查
scripts/capture_baselines.mjs    使用目标项目 Playwright 做视觉基线
scripts/self_test.py              自动化回归测试

快速开始

1. 初始化一个 Lite Web 项目

python scripts/init_project.py <project-root> `
  --profile lite --product-type ui-web

默认只创建当前 Align Gate 所需的文件。需要完整脚手架时显式使用：

python scripts/init_project.py <project-root> `
  --profile lite --product-type ui-web --materialize all

2. 检查并记录当前 Gate

python scripts/check_gates.py <project-root> --gate current --record

通过后会自动创建下一 Gate 的缺失模板，不会覆盖已有工作。

3. 记录执行证据

python scripts/evidence.py run <project-root> `
  --gate delivery --label test --command <test-command>

4. 迁移已有项目

先预览：

python scripts/migrate_project.py <project-root> --to-profile standard

确认后应用：

python scripts/migrate_project.py <project-root> `
  --to-profile standard --apply

5. 运行自检

python scripts/self_test.py

UI/HTML 迁移流程

freeze/inventory
→ visual contracts
→ component DAG
→ target-native components
→ page assembly
→ geometry/screenshot checks
→ live adapters

固定 viewport、语言、主题、登录状态、Fixture、字体和图标后，再使用目标项目中安装的 Playwright 捕获基线：

python scripts/inventory_html.py <reference-dir> `
  --manifest <project-root>/docs/html-inventory.json `
  --fail-on-missing --fail-on-external

node scripts/capture_baselines.mjs <project-root>/docs/06-VISUAL-CASES.json

技术栈适配

Skill 只负责约束决策和验证顺序，不强制 React、Next.js 或某一种后端。用户指定的前端、后端、数据库、部署环境优先；未指定时才根据仓库约束、团队能力、集成、并发和交付目标比较候选方案。

风险控制

支付、PII、财务数据、库存、积分、佣金、退款、高权限操作、文件上传、外部 Webhook 和监管数据可以通过风险标志增加安全、审计、幂等、对账、回滚和发布证据，而无需盲目升级全部流程。

对话输出模式

• brief：只输出本轮变化、阻塞、证据、下一步；
• standard：补充当前 Gate 和主要风险；
• audit：用于评审和发布，输出完整状态、证据和漂移。

许可与贡献

本仓库用于 Codex Skill 和产品开发流程实验。提交变更时请保持模板、脚本和引用文档的一致性，并运行 scripts/self_test.py。