DemandSpec

Use when analyzing, clarifying, specifying, reviewing, validating, approving, or archiving product and business requirements, including PRDs, AI scenarios, p...

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

Core Workflow

text

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 可用时执行：

   bash

   demandspec init --project .
   demandspec new "<需求名称>" --type <normal|ai|ui|cross-system|high-risk> --owner "<负责人>"
   demandspec change new "<变更名称>" --domain <domain> --type <type> --owner "<负责人>"
   

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

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

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

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

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

   bash

   demandspec change validate <change-id> --strict
   

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

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

Quick Paths

用户输入	推荐路径	最小输出
只有一句话想法	Intake -> Clarify -> Scope	需求卡片、澄清问题、范围边界
已有 PRD 需要补全或评审	Inspect -> Review -> Repair -> Validate	修订后的 PRD、评审清单、验收标准
AI 场景	Intake -> Clarify -> AI Fit -> Model -> Validate	需求卡片、AI 评估、数据/规则、人工兜底、AI 验收
页面或交互需求	Scope -> Process -> Prototype -> Acceptance	范围、流程、页面/状态/交互、验收标准
OpenSpec 风格变更	Proposal -> Delta Spec -> Acceptance -> Tasks -> Validate	proposal.md、Delta Spec、acceptance.md、tasks.md

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

Output Layout

完整需求档案：

text

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

OpenSpec 风格变更包：

text

changes/<change-id>/
  metadata.yaml
  proposal.md
  design.md
  specs/<domain>/spec.md
  acceptance.md
  tasks.md
  approval.md

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

Maturity Levels

Level	可观察状态	下一步
L0 原始想法	只有一句话或零散材料	形成需求卡片
L1 问题描述	有痛点，目标和用户不清	澄清问题与成功指标
L2 需求雏形	有目标和场景，边界不完整	范围、流程、假设
L3 可建模需求	角色、流程、数据基本明确	原型、规则、AI 评估
L4 可成文需求	可生成 PRD 和原型说明	验收与评审
L5 可交付需求	需求、验收、任务可追踪	审批、实施、验证
L6 可沉淀需求	已上线并有反馈或指标	归档与复盘

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

最终回复使用以下结构：

markdown

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

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