anian0/requirements-workshop-v2

需求澄清 v2

把模糊功能想法整理成短需求简报，保留设计和实施真正需要的信息。优先保证范围、用户路径和决策清晰，而不是追求文档完整感。

先读取

起草前读取这些引用：

• ../project-development-v2-common/references/question-policy.md
• ../project-development-v2-common/references/delivery-contract.md
• references/requirements-confirmation-gates.md
• references/requirements-analysis-gates.md
• references/requirements-brief-template.md
• 如用户要求评估、审查、进入下一阶段前把关，使用 project-development-review-v2。

核心规则

• 保持简短。默认目标：1 到 3 页。
• 输出必须先给“审查摘要”和“功能概览”，把要做什么功能、服务谁、从哪里进入、以什么形态呈现、成功/失败如何反馈、现状证据、范围、关键决策、风险和待确认问题集中放在文档前 1/3；正文只能展开这些结论，不能让重要信息散落在多个章节后才出现。
• 需要向用户提问时，问题必须是回复最后一个区块；不得把问题夹在背景、推导或交付说明中间。
• 只问有决策价值的问题。能安全假设时，写明假设，不要提问。
• 需求讨论阶段必须先看项目现状。只要当前会话有仓库或本地上下文，就先检查已有文档、路由、页面、API、数据模型、配置和相似功能；无法检查时必须说明原因和风险。
• 先做需求推导，再写简报。不能把用户给的模块名、功能名直接整理成需求列表。
• 先定义功能概览，再展开业务机制和对象边界。功能概览必须用产品/业务语言说明“这个需求要给用户或系统增加什么能力”，不能只写模块、服务或内部组件。
• 需求阶段必须经过固定确认闸门。闸门确认优先级高于“少问问题”策略。
• 区分已确认范围、假设和待决策项。
• 先描述用户可见行为，再讨论内部结构。
• 中大型需求必须说明核心业务机制、关键实体、边界和决策依据。
• 中大型触发条件：新子系统、跨模块协作、事实源变化、AI/Agent 节点、重构、三条以上用户路径、影响持久化数据或权限时，必须展开业务机制和关键决策。
• 每个 R-* 必须有用户可见闭环：入口、操作、成功可见结果、失败反馈、结果或状态如何被看到；纯后端能力必须声明“无 UI”并说明可观察入口。
• 需求包含页面、入口、日志、状态或反馈时，必须提供页面/入口覆盖表；无 UI 时必须显式声明。
• 每个本期功能必须写清呈现形态：页面/视图、按钮/菜单、配置项、API、后台任务、日志/事件、CLI 或无 UI 可观察入口；不允许只写“实现能力”。
• 每个 A-* 必须标注验收关注点，例如后端事实、前端可见性、失败/异常、数据追溯、兼容或隔离。
• 必须明确范围边界：本期范围、后续候选、不做范围；不要把“以后可能做”混入本期需求。
• 不做范围 必须具体，默认不少于 3 条；不足 3 条时必须说明为什么范围天然很小。
• Agent/AI 类需求必须描述 AI 节点的任务类型、Agent/LLM 选择理由、角色边界、工具需求、自主度和失败风险。
• 用户明确强调的约束、风险或偏好必须进入特别关注点，并交接给后续阶段。
• 不写技术方案、数据库结构、API 契约、任务计划或实现步骤。
• 需求简报保存并由用户确认前，不进入 tech-design-v2。
• 需求简报交付前必须完成需求审查自检；存在阻塞级审查发现时，不得建议进入 tech-design-v2。

流程

1. 执行项目现状探查：读取仓库结构、已有需求/方案、路由/页面、API、数据实体、配置和相似功能；输出“现状证据摘要”，列出已看到的文件/模块和仍未知的部分。除非用户明确只要纯概念讨论，否则不得跳过。
2. 基于现状证据判断已有能力、缺口、复用点和冲突点；不能确认的内容记录为假设或待决策项。
3. 先产出功能概览：功能名称、目标用户/调用方、功能目标、呈现形态、主要入口、核心操作、成功结果、失败反馈、结果可见位置。
4. 按 references/requirements-analysis-gates.md 做需求推导：现状问题、功能概览、目标用户、范围边界、核心机制、关键实体、边界和风险。
5. 执行确认闸门 G1：问题、目标和功能概览确认。提问时必须放在回复末尾。
6. 识别主用户路径和关键分支路径：入口、操作、成功结果、失败反馈。
7. 为每个本期 R-* 写用户可见闭环；含 UI 时补页面/入口覆盖表，无 UI 时写明可观察入口。
8. 提炼关键对象、边界和关键决策：哪些是已确认，哪些需要用户确认，哪些只是安全假设。
9. 对 Agent/AI 类需求，补 AI 节点需求：任务类型、Agent/LLM 选择、角色边界、工具需求、自主度和失败风险。
10. 执行确认闸门 G2：用户路径、呈现形态、页面/入口、关键对象和边界确认。提问时必须放在回复末尾。
11. 定义范围：

• 本期范围：现在必须实现的需求。
• 后续候选：有价值但不进入本期的能力。
• 不做范围：明确排除的内容。
• 假设：无需提问即可采用的安全默认。

12. 为每个 A-* 标注验收关注点，确保能支撑后续 V-* 拆解。
13. 提取特别关注点和技术阶段必须确认的问题。
14. 执行确认闸门 G3：范围、验收标准、验收关注点、特别关注点和待决策项确认。提问时必须放在回复末尾。
15. 按 references/requirements-brief-template.md 写需求简报，先写审查摘要，再写正文。
16. 按 delivery-contract.md 解析真实版本目录，保存到 workplace/<version>/requirements/YYYY-MM-DD-<slug>.md；实际路径不得保留 <version>、1.X 等占位符。
17. 按 project-development-review-v2 的需求审查口径做交付前自检，记录阻塞问题或已接受风险。
18. 最终只请求用户确认是否可进入 tech-design-v2；确认问题必须放在最终回复末尾。

提问门槛

提问前检查：

• 答案会改变要做什么吗？
• 答案无法从代码、文档或上下文推断吗？
• 假设错误会导致返工、用户可见错误、数据损坏、安全风险或明显成本吗？

任一答案为“否”，就不要问，改为记录假设。

输出标准

需求简报必须包含：

• 审查摘要：目标、现状证据、范围边界、关键决策、风险/假设、待确认问题集中展示。
• 功能概览：功能名称、目标用户/调用方、功能目标、呈现形态、主要入口、核心操作、成功结果、失败反馈、结果可见位置。
• 现状证据摘要：检查过的项目文件/模块、已有能力、相似功能、缺口和未知项。
• 确认记录。
• 需求推导摘要：为什么要做、当前痛点、功能目标、核心机制。
• 关键实体和边界：系统中真正被管理、流转或追踪的对象。
• 需求编号：R-001、R-002 ...
• 验收编号：A-001、A-002 ...
• 包含成功、失败和关键分支反馈的用户路径。
• 用户可见闭环和页面/入口覆盖表，或明确“无 UI”声明。
• 验收关注点：后端事实、前端可见性、失败/异常、数据追溯、兼容或隔离。
• 范围边界：本期范围、后续候选、不做范围。
• 本期不做范围：默认至少 3 条，或说明为什么不足 3 条。
• Agent/AI 节点需求，如适用。
• 特别关注点。
• 本期范围和不做范围。
• 只有确实需要用户输入时才保留的待决策项。
• 给 tech-design-v2 的交接信息。

交付前自检

检查：

• G1 到 G3 均有确认记录，或明确记录用户要求跳过哪一项及其风险。
• 每个本期需求至少有一条验收标准。
• 功能概览能在 1 分钟内回答“做什么功能、谁用、在哪里用、以什么形态呈现、成功/失败看到什么”。
• 每条验收标准都可观察或可测试。
• 每条需求都能追溯到痛点、用户路径、核心机制或关键决策。
• 每个本期 R-* 都有入口、操作、成功可见结果、失败反馈和结果可见性；无 UI 时有可观察入口说明。
• 有页面或入口时，页面/入口覆盖表逐项覆盖本期需求。
• 每个本期功能都有呈现形态；无 UI 时有可观察入口，不把内部模块当成功能呈现。
• 每个 A-* 都有验收关注点，能让技术方案拆出验证场景。
• 本期范围没有混入后续候选或不做范围。
• 不做范围具体且可防止范围蔓延；少于 3 条时有明确理由。
• Agent/AI 类需求已说明节点任务、Agent/LLM 选择理由、角色边界、工具需求、自主度和失败风险。
• 特别关注点已记录且具体。
• 待决策项少且重要。
• 没有泄漏技术实现计划。
• 没有把模块清单冒充需求推导。
• 没有跳过项目现状探查；如跳过，已记录用户要求、原因和风险。
• 所有需要用户回答的问题都出现在回复末尾，而不是文档或说明中间。
• 没有只因模板存在而保留的空泛章节。
• 没有遗漏“技术阶段必须确认的问题”，例如兼容接口、事实源、失败隔离、关键字段、迁移范围和验收口径。
• 没有把未经用户确认的关键设计选择伪装成需求结论。

交接

用户确认后，给出：

• 需求简报路径。
• 需求数量和验收标准数量。
• 功能概览和呈现形态摘要。
• 页面/入口数量，或无 UI 声明。
• 验收关注点摘要。
• 待决策项，如有。
• 高风险假设，如有。
• 特别关注点，如有。