需求文档

Trigger: ~prd [description]

执行 ~prd 时，不读取 ~plan 的 command skill；只有当前流程明确需要时，才继续读取对应的 hello-* 技能。 执行 ~prd 时，通用阶段边界按当前已加载的 HelloAGENTS 规则执行；本 skill 负责补充规格探索、PRD 写入与继续执行要求。 .helloagents/ 在本 skill 中统一按项目级存储路径理解：状态文件只使用 state_path；会话证据使用当前 state_path 所在目录下的 artifacts/*.json；若 project_store_mode=repo-shared，知识库、DESIGN.md 与 plans/ / archive/ 按当前上下文中已注入的项目知识/方案目录解析。

铁律

• 在用户确认方案之前，禁止编写任何实现代码、创建任何文件、或执行任何实现操作。
• 每个维度的选项必须体现当前前沿水准。若当前已加载的 HelloAGENTS 规则含审美/体验要求则遵循其要求；否则至少给出具体、可执行、非泛化的视觉特征，不确定时主动搜索查阅。
• 用户说"跳过"某维度 → 跳过，不生成该文件。不强迫用户讨论不关心的维度。
• 大项目检测：涉及多个独立子系统时，先帮用户分解为子项目，每个子项目走独立的 ~prd 循环。
• 若当前任务来自 ~auto，则 PRD / 任务 / 契约写入后默认继续执行；只有真实阻塞时才停在规格阶段。
• 涉及 UI 时，prd/03-ui-design.md 负责记录本次产品/功能的 UI 决策；项目级稳定设计契约同步写入 .helloagents/DESIGN.md（按当前项目存储模式解析）

PRD 维度清单

按编号排列，每个维度对应一个模板文件（templates/plans/prd/）：

维度激活矩阵

根据项目类型自动判断维度优先级（必选/推荐/可选）：

流程

1. 上下文收集

已有项目：

• 按当前已加载的 HelloAGENTS 规则恢复上下文，并遵循“.helloagents/ 文件读取优先级”和“项目文件”要求；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 state_path，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实确认当前任务
• 在进入维度探索前，至少确认 .helloagents/context.md、.helloagents/guidelines.md，并只扫描与当前产品范围直接相关的代码和配置
• 若 .helloagents/context.md 已有领域语言，PRD 中统一沿用；发现术语冲突或歧义时，先澄清再写入

全新项目（无 .helloagents/ 目录）：

• 跳过，直接进入项目定位

2. 项目定位（快速，1-2 轮）

目标：快速锁定项目类型和 PRD 范围。

a. 理解用户的初始描述 b. 确认项目类型（Web App / Mobile / API / CLI / Library / 桌面 / 游戏 / 混合） c. 根据维度激活矩阵，列出本项目的必选/推荐/可选维度 d. 询问用户：推荐维度是否需要？可选维度是否需要？ e. 确定最终的维度列表

3. 维度探索（头脑风暴，核心阶段）

按维度编号顺序，逐个展开讨论。每个维度的交互模式：

a. AI 先给出该维度的行业最佳实践参考和推荐方案 b. 用户确认/修改/补充 c. AI 总结该维度的决策结果，进入下一个维度

交互原则：

• 每个维度内，每次只问一个问题，偏好选择题
• 用户说"跳过" → 跳过该维度，不生成对应文件
• 用户说"默认" → AI 按推荐方案填充，快速过
• 用户说"展开" → 深入讨论该维度的子项
• 维度之间可以回溯：用户说"回到 03" → 重新讨论 UI/UX 设计
• 涉及项目特有概念时，确认标准术语、避免用语和关键关系；不要把泛化技术词写入领域语言

选项质量要求：

• 涉及视觉/交互/体验的问题时，选项必须体现当前前沿设计水准
• 不确定当前前沿趋势时，主动搜索查阅最新设计案例和技术能力后再给出选项
• 每个选项必须包含具体的视觉特征描述，不接受泛化标签

4. 写入方案包

将讨论结果写入本地项目：

• 按当前已加载的 HelloAGENTS 规则建立 .helloagents/ 与最小流程状态；这是方案包写入的前置操作，不受 kb_create_mode 开关控制
• 创建 .helloagents/plans/YYYYMMDDHHMM_{feature}/prd/（按当前项目存储模式解析）
• 按 templates/plans/prd/ 的模板格式，仅写入用户未跳过的维度文件
• 生成 tasks.md（每个任务默认是端到端垂直切片，标注 AFK / HITL、依赖、具体文件路径、预期变更、完成标准与验证方式；任务独立可验证）
• 在 tasks.md 中保留 “Codex /goal 执行入口”，让 Codex 按 /goal -> ~auto -> ~qa 执行已拆分任务、验收边界和 contract.json；不要把完整 PRD 原文直接当作 /goal 目标
• 生成 decisions.md（贯穿全程的决策日志）
• 生成 contract.json（至少包含 qaMode、qaFocus；涉及 UI 时补 ui.required、ui.designContract、ui.sourcePriority；仅在确需先明确审美方向时再补 ui.styleAdvisor.required、ui.styleAdvisor.reason、ui.styleAdvisor.focus；仅在确需视觉验收时再补 ui.visualValidation.required、ui.visualValidation.reason、ui.visualValidation.screens、ui.visualValidation.states；仅在确需独立 advisor 时，再补 advisor.required、advisor.reason、advisor.focus、advisor.preferredSources）
• 使用 scripts/plan-contract.mjs write 写 contract.json，不要只把验证路径留在自然语言说明里
• 涉及 UI 的项目：生成或更新 .helloagents/DESIGN.md（按当前项目存储模式解析）；若原文件不存在，先按模板建立最小设计契约，再同步已确认的稳定 UI 决策
• 重写 state_path，其中“主线目标”写本次 PRD 要完成的产品 / 功能目标，不保留其他任务的内容

输出 PRD 完整度摘要：已覆盖 N/13 个维度，建议后续补充的维度（如有）。

5. 执行决策

展示 PRD 摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：

• 开始执行 → 重写 state_path（“主线目标”保持当前 PRD 目标，下一步设为第一个任务的具体动作）
• 修改 PRD / 补充维度 → 回到对应维度继续讨论
• 暂不执行，保留方案 → 重写 state_path（“主线目标”保持当前 PRD 目标，下一步设为“方案已确认；执行需用户明确启动”）

如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，可直接进入执行，或按需先补一轮 ~plan 明确实现方案。 如果当前任务来自 ~auto，且 PRD 已整理成可执行任务、也未命中阻塞判定，则默认继续进入 ~build，必要时先补一轮轻量 ~plan，不再额外询问一次“是否开始执行”。 如果当前任务是显式 ~prd，且尚未获得执行授权，最终回复按通用输出格式使用等待输入态：正文说明 PRD / 任务 / 契约结果，🔄 下一步 写清待确认动作。

6. 继续执行

按 tasks.md 逐项完成，每项进入当前已加载的 HelloAGENTS 统一执行流程，完成后同步重写 state_path。 任务状态标记仅写入 tasks.md、验收清单或验证结果；普通说明、方案解释、状态汇报不用 [√] / [-] / [ ]。 所有任务完成后进入当前已加载的 HelloAGENTS QA / CONSOLIDATE 收尾阶段。 可并行的任务标记后用子代理并行执行（不同子代理不改同一文件）。 执行过程中遇到阻塞（依赖缺失、指令不清、验证反复失败）→ 立即停下询问用户，不猜测。 执行过程中遇到高风险操作（删除文件/修改配置/数据库变更）→ 暂停确认。

方案包结构

~prd 生成的方案包结构：

plans/YYYYMMDDHHMM_{feature}/
├── prd/                    # PRD 文档（按维度生成）
│   ├── 00-overview.md
│   ├── 01-user-stories.md  # 仅用户未跳过的维度
│   ├── 02-functional.md
│   └── ...
├── contract.json           # 机器可消费的验证 / 审查契约
├── tasks.md                # 端到端垂直切片任务
└── decisions.md            # 决策日志

文档限制

• 只记录决策和约束，不记录讨论过程
• 用表格和列表，不用段落叙述
• 单文件超限 → 拆分为子文件（如 02-functional-api.md），主文件保留摘要和链接