product-development

产品开发生命周期

引导功能从构想到实施计划，贯穿产品开发生命周期。每个工作流都会产出特定成果，供后续工作流使用。工作流转换需经过人工审核，也可选择进行自动审核。

生命周期图

[Project Setup]                              ← one-time setup (scripts/init.sh)
  ↓
Foundation Stage
  ├─ Product Constitution approval
  ├─ Product Vision workflow (Vision Grill)
  ├─ additional product-anchor workflows (planned extension point)
  └─ Foundation Gate: approved, versioned constitution + approved, versioned vision before first PRD
  ↓
Discovery and Design
  ↓  [human approves design]
Requirements
  ├─ PRD  [human approves before TRD]
  └─ TRD  [human approves PRD + TRD]  → optional review pass
  ↓
User Stories
  ↓  [human approves stories]         → optional review pass
BDD Scenarios
  ↓  [human approves scenarios]       → optional review pass
Implementation Planning

基础阶段不会阻碍头脑风暴或设计探索。基础门槛会阻止创建首份 PRD。后续 PRD 必须在继续之前检查与章程及愿景的一致性。

工作流

项目设置

触发条件： 项目尚无 docs/product/ 目录，或用户要求“初始化产品文档”或“设置产品文档”。

流程： 运行初始化脚本（scripts/init.sh）以搭建文档结构。脚本使用带占位符的模板，自动检测项目上下文（名称、界面），并提示用户填写特定领域的值。完整工作流请参阅 references/initialization.md。

输出：

• docs/product/README.md — 文档层级和边界规则
• docs/product/AGENTS.md — 用于整理产品文档的 Agent 指引
• docs/product/features/ — 已准备就绪、可添加首个功能的空目录

此工作流在每个项目中仅运行一次。 如果 docs/product/README.md 已存在，则跳过。

基础阶段

触发条件： 缺少 docs/product/constitution.md 或 docs/product/vision.md，用户要求创建或更新产品锚点文档，或者 Agent 准备开始编写首份功能 PRD，必须在起草前验证基础门槛。

流程： 按以下层级建立产品锚点文档：

1. 产品章程工作流：创建、批准或修订已批准且带版本信息的 docs/product/constitution.md。有关 grill-with-docs 依赖行为、章程审议工作流、版本管理、修订行为和章程一致性检查，请参阅 references/product-constitution.md。
2. 产品愿景工作流：章程获批后，运行愿景审议。有关 grill-with-docs 依赖行为、上下文/ADR 协调和愿景版本管理，请参阅 references/product-vision.md。
3. 其他产品锚点工作流：为经批准后添加的产品锚点文档预留的扩展点。
4. 基础门槛：仅当已批准且带版本信息的 docs/product/constitution.md 和已批准且带版本信息的 docs/product/vision.md 均存在时，才算完成。

输出： 已批准且带版本信息的 docs/product/constitution.md；已批准且带版本信息的 docs/product/vision.md；以及在获批并使用时可选的 CONTEXT-MAP.md、docs/product/CONTEXT.md 和 ADR。

基础门槛： 在用户批准 docs/product/constitution.md、该文件包含版本元数据，且已批准且带版本信息的 docs/product/vision.md 存在之前，不要创建首份 PRD。

探索与设计

触发条件： 收到一个构想、功能请求或问题陈述。

流程： 调用 brainstorming 技能。该技能负责协作探索、方案提议和设计审批。

输出： 已批准的设计文档，路径为 docs/plans/YYYY-MM-DD-<topic>-design.md。

门槛： 设计获批前，不要进入需求阶段。

要求

触发条件： 设计文档已获批准。

必需输入： 已获批准的设计文档、已获批准且经过版本管理的 docs/product/constitution.md，以及已获批准且经过版本管理的 docs/product/vision.md。缺少基础文档、文档未经批准或未纳入版本管理，都会阻止首次 PRD 需求工作。

流程： 创建产品需求文档和技术需求文档。参阅 references/phase-2-requirements.md，了解结构、约定，以及与章程和愿景的一致性要求。

关卡： PRD 定义做什么；TRD 定义怎么做。编写 TRD 前，先提交 PRD 供人工审批。这样可以避免需求变更时浪费架构设计工作。

输出：

• docs/product/features/{feature}/PRD.md
• docs/product/features/{feature}/TRD.md

关卡： 两份文档均经过评审并获批准后，方可继续。运行已配置的评审流程（参见 Configuration）。

产物位于平台级——需求描述产品的功能，不受产品界面的影响。

用户故事

触发条件： PRD 和 TRD 已完成评审并趋于稳定。

流程： 将 PRD 中的需求分解为面向用户的叙述。参阅 references/phase-3-user-stories.md，了解格式、规模指导和验收标准约定。

输出： 故事文件位于 docs/product/features/{feature}/stories/。

关卡： 用户故事经过评审并获批准。运行已配置的评审流程。

故事位于平台级——描述用户意图，而非特定界面的交互方式。

BDD 场景

触发条件： 用户故事已定义验收标准。

流程： 使用 Gherkin 场景表达验收标准。参阅 references/phase-4-scenarios.md，了解边界规则、文件位置和编写约定。

输出：

• 平台级场景：docs/product/features/{feature}/scenarios/*.feature
• 特定界面的场景：apps/{surface}/docs/features/{feature}/scenarios/*.feature

关卡： 场景经过评审并获批准。运行已配置的评审流程。

边界规则： 如果 Given/When/Then 的表述不依赖特定界面，场景属于平台级。如果涉及特定交互模式（滑动、D-pad、凝视），则属于特定界面的场景。

实施规划

触发条件： 场景已完成评审，且涵盖验收标准。

流程： 将已批准的章程和愿景与经过评审的场景一同载入，然后调用 writing-plans 技能。该技能会创建详细的逐任务实施计划，其中包含 TDD 步骤、文件路径和验证标准。如果计划会违反 MUST NOT 表述、削弱章程原则、与已批准的愿景冲突或超出明确授权，则停止规划。

输出： 实施计划位于 docs/plans/YYYY-MM-DD-<topic>.md。

关卡与评审流程

关卡行为

在每个关卡：

1. Agent 将产物提交给人工评审
2. 如果此关卡配置了评审流程，则先运行这些流程，并在提交时一并提供评审结果
3. 人工批准、要求修改或拒绝
4. 批准后进入下一工作流；如需修改，则迭代并重新提交

可配置的评审流程

评审流程是可选的自动化检查，会在关卡的人工评审前运行。可按项目或用户进行配置（参见 Configuration）。例如：

• 章程一致性检查——验证 PRD 是否符合所有治理原则
• 可追溯性审计——验证每个 FR-* 是否均有对应故事，以及每个故事是否均有对应场景
• 代码评审 Agent——针对产物运行评审技能（例如 coderabbit:review）
• 自定义评审提示词——来自 AGENTS.md 的项目专属评审说明

如果某个关卡未配置评审流程，则该关卡仅进行人工评审。

配置

配置存放在两个位置，项目级配置优先于用户级配置：

• 用户级： ~/.config/prometheas-product-development-skill/
• 项目级： $PROJECT_ROOT/.config/prometheas-product-development-skill/

settings.toml

用于声明式配置哪些内容在哪里运行：

[review_gates.requirements]
reviews = ["constitution-check"]

[review_gates.user_stories]
reviews = ["traceability-audit"]

[review_gates.bdd_scenarios]
reviews = ["traceability-audit", "coderabbit:review"]

[workflows]
use_subagents = true      # Delegate heavy writing to sub-agents
prd_before_trd = true     # Human approves PRD before TRD

AGENTS.md

审查 Agent 接收的自然语言指令，作为上下文使用。对于无法纳入结构化配置的细致项目专属指导，请使用此文件：

## Review Context
When reviewing PRDs, ensure constitution alignment with particular
attention to Principle II (Privacy).

## Requirements Notes
All TRDs must follow the vendor-agnostic facade pattern.

合并行为

项目级 settings.toml 按键覆盖用户级配置。项目级 AGENTS.md 会追加在用户级 AGENTS.md 之后，因此项目专属指令在上下文中优先。

无配置

如果两个配置位置都不存在，技能将使用默认值运行：仅设置人工把关，不进行自动化审查，是否使用子 Agent 由 Agent 根据上下文大小自行决定。

上下文管理

需求、用户故事和 BDD 场景都需要大量撰写。为了让主上下文专注于编排和与人的协作，请将繁重的撰写工作委派给子 Agent。生命周期按顺序进行，绝不要并行运行工作流。

子 Agent 调度模式

对于每个撰写工作流，只向子 Agent 提供其所需的输入：

工作流	子 Agent 接收	子 Agent 返回
需求 PRD	设计文档、章程、愿景、references/phase-2-requirements.md、示例功能	写入磁盘的 PRD
需求 TRD	已批准的 PRD、章程、愿景、references/phase-2-requirements.md、示例功能	写入磁盘的 TRD
用户故事	已批准的 PRD、TRD、章程、愿景、references/phase-3-user-stories.md	写入磁盘的故事文件
BDD 场景	用户故事、TRD、章程、愿景、references/phase-4-scenarios.md	写入磁盘的 .feature 文件

主上下文会与人共同审查子 Agent 的输出，并在需要时迭代。

何时留在主上下文中

并非每个工作流都需要子 Agent。以下情况请留在主上下文中：

• 人希望通过交互协作完成产物
• 功能足够小，撰写内容可轻松放入上下文中
• 人明确要求一起完成

文档层级

所有产品文档都遵循三层层级。完整规范请参阅 docs/product/README.md。

层级	位置	内容
平台	docs/product/	PRD、TRD、用户故事、平台级场景
应用	apps/{surface}/docs/	特定界面的场景
代码	apps/{surface}/tests/	步骤定义（测试自动化）

工作流选择

并非每个功能都从头开始。请根据当前状态选择入口：

起点	进入阶段
没有 docs/product/ 目录	项目设置
首份 PRD 编写前，章程或愿景缺失、未获批准或未标注版本	基础阶段
想法模糊，对方案不清楚	探索与设计
需求明确，需要文档化	通过基础关卡后进入需求阶段
PRD 已存在，需要拆解	用户故事
故事已存在，需要可测试的验收标准	BDD 场景
场景已存在，需要实现	实现规划

只有通过基础关卡后，明确的需求才能跳过头脑风暴。如果这是首份 PRD，且 docs/product/constitution.md 或 docs/product/vision.md 缺失、未获批准或未标注版本，则应在需求阶段之前运行基础阶段。

技能委派

此技能负责编排整个生命周期，但会将首尾工作流委派给专门的技能：

• 探索与设计： 委派给 brainstorming 技能
• 需求、用户故事、BDD 场景： 遵循此技能中的参考文件
• 实现规划： 委派给 writing-plans 技能

规范演进

产品规范是持续演进的文档。不同类型的文档以不同的速度演进。完整方法论请参阅 docs/METHODOLOGY.md。摘要：

文档	策略
宪章、愿景	不可变 + 替代（semver）
PRD、TRD	带有变更日志的持续更新文档
用户故事	持续更新 — 添加、完成、归档
平台场景	持续更新 + 自验证
界面场景	持续更新 + 自验证

更新现有规范时，请在其变更日志中追加日期、变更内容和原因。如果变更幅度过大，以至于文档与原始版本面目全非，则应创建新文档来替代，而不是继续修改。

参考文件

各工作流的详细指南存放在参考文件中，以便精准控制上下文。phase-* 文件名是为兼容旧版而保留的路径；请通过下方的工作流名称加载：

• references/initialization.md — 项目初始化工作流、占位符、初始化后步骤
• references/product-constitution.md — 产品宪章工作流、基础门槛、宪章审查、版本控制、修订行为和一致性检查
• references/product-vision.md — 产品愿景工作流、基础门槛、愿景审查、版本控制以及上下文/ADR 协调
• references/phase-2-requirements.md — PRD 和 TRD 结构、约定、宪章和愿景检查
• references/phase-3-user-stories.md — 故事格式、验收标准、规模评估
• references/phase-4-scenarios.md — Gherkin 约定、边界规则、文件位置
• docs/METHODOLOGY.md — 规范演进策略、变更日志约定、替代规则

仅在需要精确的源内容时，通过 references/product-constitution.md 加载 references/source/product-constitution-guide.md。仅在需要精确的源内容时，通过 references/product-vision.md 加载 references/source/vision-document-guide.md。

脚本

• scripts/init.sh — 项目初始化脚本。从模板生成 docs/product/ 并替换占位符。支持交互式提示、CLI 参数和 --dry-run。

模板

• templates/README.md.tmpl — 文档层级模板
• templates/AGENTS.md.tmpl — Agent 指南模板