DemandSpec

DemandSpec

将业务想法、会议纪要、口述需求、已有 PRD、系统截图或 AI 场景设想，转化为写入工作区、可评审、可追踪、可验证的需求资产。不要只在对话中给建议或输出空模板。

Core Workflow

Intake -> Clarify -> Diagnose -> Model -> Prototype -> Specify -> Validate -> Handoff -> Archive

Execution Workflow

1. 检查现状。 First inspect the workspace：查找 demandspec/、demands/、changes/、现有 PRD、会议纪要、原型、接口文档、测试和业务规则。优先复用真实材料，不凭空补全。

2. 判断入口。 确定需求成熟度 L0-L6、类型（普通、AI、UI、跨系统、高风险）以及是新需求、已有 PRD 修订还是变更包。

3. 分离信息。 将内容分为：

   • 已确认事实：有来源支撑，可直接进入规格。
   • 当前假设：为推进工作暂时采用，必须标注验证方式。
   • 阻塞项：不确认就无法定义范围、规则或验收标准。

4. 创建或定位需求包。 CLI 可用时执行：

   demandspec init --project .
   demandspec new "<需求名称>" --type  --owner "<负责人>"
   demandspec change new "<变更名称>" --domain  --type  --owner "<负责人>"
   

   CLI 不可用时，按 Output Layout 手工创建同等目录和 Markdown 文件。

5. 只读取本次需要的模板。 先看 模板填写指南，再读取 templates/ 中对应模板。不要一次生成所有文档；输出应与成熟度和交付目标匹配。

6. 填入具体内容并落盘。 使用真实角色、动作、字段、规则、阈值、异常、来源和责任人，write the files 到目标需求目录。禁止留下无解释的空标题、通用占位语或只复制模板。

7. 建立追踪关系。 为需求分配稳定 ID，例如 CRM-VISIT-001。同一 ID 必须出现在 Delta Spec、PRD/设计、验收标准、测试用例和研发任务中。

8. 验证并修正。 对变更包执行：

   demandspec change validate  --strict
   

   修复结构、必填内容和追踪错误后再次执行，直到通过。没有 CLI 时，至少按 templates/review-checklist.md 检查完整性、一致性、可实现性和可验收性。

9. 报告完成结果。 列出写入文件、成熟度、关键结论、未决问题、验证命令和验证结果，不把“文档已生成”当成“需求已确认”。

Quick Paths

需求仍处于 L0-L2 时，不要直接伪造完整 PRD。先产出足以推动确认的材料，并明确下一步负责人。

Output Layout

完整需求档案：

demands//
  00_intake/
  01_clarify/
  02_diagnose/
  03_model/
  04_prototype/
  05_spec/
  06_validate/
  07_handoff/
  08_archive/

OpenSpec 风格变更包：

changes//
  metadata.yaml
  proposal.md
  design.md
  specs//spec.md
  acceptance.md
  tasks.md
  approval.md

如果仓库已有其他约定，匹配现有路径，不为统一目录而移动用户文件。

Maturity Levels

Template Usage

模板是检查清单，不是成品。按 references/template-filling-guide.md 的最低完成条件填写。核心规则：

• 事实写明来源；未知项写“待确认：问题 / 负责人 / 截止时间”。
• 范围必须同时写 In Scope、Out of Scope 和边界条件。
• 功能要求使用“系统 MUST/SHALL + 可观察行为”，避免“支持、优化、智能化”等无验收口径的词。
• 验收标准使用 GIVEN / WHEN / THEN，并覆盖正常、异常、权限、数据和非功能场景。
• AI 场景必须定义输入、输出、效果指标、业务指标、低置信度处理、人工确认和失败回退。
• UI 场景必须定义页面、组件、交互、空态、加载态、成功态、失败态和权限态。

Worked Example

需要了解如何执行或内容应写到什么粒度时，读取 拜访单自动生成完整案例。案例展示：

• 从一句话输入判断为 AI/full 需求；
• 将事实、假设和阻塞项分离；
• 使用 CRM-VISIT-001 串联规格、验收和研发任务；
• 定义低置信度字段的人工确认与提交阻断；
• 执行严格验证并报告结果。

Common Mistakes

• 只复制模板。 有标题没有决策、数据或验收口径，不算完成。
• 跳过澄清直接写 PRD。 未确认内容会被伪装成事实。
• 只写理想流程。 漏掉空数据、重复提交、接口失败、权限不足和人工回退。
• AI 只写模型方案。 没有业务收益、基线、阈值、人工确认和错误成本。
• 原型只列页面名。 没有组件、状态、交互和跳转，无法交付设计或前端。
• 验收与任务不带需求 ID。 无法证明需求已被测试和实现。
• 验证失败仍宣布完成。 应列出失败项并继续修复，或明确阻塞原因。
• 只回复对话不写文件。 除非用户明确只要建议，否则必须将资产写入工作区。

Completion Report

最终回复使用以下结构：

完成：
- 成熟度：Lx -> Ly
- 需求类型：...
- 新增/修改文件：...
- 关键决策：...
- 待确认项：...
- 验证：`demandspec change validate ... --strict` -> 通过/失败

不得把假设、模板生成或未通过验证的内容描述为已获业务确认。