anian0/requirements-workshop

需求讨论与完善

将用户想法快速转化为完整需求文档，强调 MVP、业务架构先行、功能闭环、前后端一体。

<HARD-GATE> 未产出并经用户确认需求文档之前，不要进入实现阶段：不要写代码、不要建项目结构、不要调用下游skill。 </HARD-GATE>

版本号约定（贯穿本套5个skill）

文中 1.X 是工作版本目录占位符，X 为整数。

• 首次启动：workplace/1/；大版本迭代新建 workplace/2/，旧版本归档
• 同一版本内的需求、技术方案、计划、测试代码共享同一 X
• 写文件、跑命令时必须把 1.X 替换为实际数字，不要在真实路径里保留 1.X 字面量

执行前先扫描 workplace/ 已有子目录确认当前版本号。

核心原则：前后端联合考虑 + 推导式架构设计

任何用户感知的功能都必须配套：用户入口（页面/按钮）、界面反馈（成功/失败/加载/空/异常态）、数据展示（结果 UI 形态）。

仅讨论后端逻辑会导致前端模块在后续阶段缺失。本 skill 在功能清单与页面清单两层强制覆盖前端。

中大型需求必须先做业务架构再拆功能——但架构设计不是需求场景的重新分组。架构是从需求中推导出来的设计决策：理解核心运转机制→识别设计问题→做决策→得出模块组织。

本步骤聚焦业务架构（核心机制、共性层提取、AI节点规划与Agent/LLM选型、风险分级、模块组织），不涉及技术实现细节（技术选型、API设计、数据库表、服务拆分），后者由 tech-design skill 负责。

文档结构（核心输出）

| 章节 | 内容 | 检验 | |------|------|------| | 价值与可行性 | 用户痛点、不做的后果、技术/资源/兼容可行性 | 能说出具体用户和具体痛点 | | 业务架构 | 核心机制、设计问题与决策、模块划分 | 中大型需求必填；小需求可标注"不适用" | | 功能清单 | 每个功能的描述、用户入口、输入输出、闭环 | 每个功能能自我闭环且有界面入口；按模块组织 | | 页面/界面清单 | 所有页面、路由、状态、对应功能 | 前端可据此明确实现范围 | | 时序图 | 业务流程与数据流转（含前端） | 完整用户旅程可视化 | | 验收标准 | 验证方法与成功指标（含前端可见性） | 有可执行的验证步骤 | | 附录 | 特别关注点、风险清单、范围确认 | 特别关注点非空且具体 |

工作流程（5 步）

1. 理解需求（一次性问清场景、用户、痛点、期望、价值与可行性）→ 确认
2. 业务架构设计（中大型需求必做；小需求跳过）
3. 梳理功能清单（每个功能含用户入口与闭环，按模块组织）
4. 梳理页面清单 + 时序图
5. 产出文档 + 自检 + 用户确认 → 确认后进入 tech-design

业务架构步骤触发条件：满足以下任一条件时，第2步不可跳过——

• 涉及新模块或新子系统
• 需要修改现有数据模型
• 涉及跨模块交互（3个以上模块）
• 影响范围超过3个功能点
• 用户提到"系统""架构""扩展""重构"等词

小需求（单页面CRUD、纯UI调整、单接口新增）跳过第2步，功能清单中标注"本需求不涉及业务架构调整"即可。

---

第一步：理解需求（合并背景/价值/可行性）

先快速扫描项目结构与已有相关文档，再按下列要点一组问完（不需逐题等待，可在同一轮中给出 3-5 个问题）：

场景与用户

• 什么场景下想到要做这个？目标用户是谁？现状怎么解决，有什么不满？

价值判断

• 不做会怎样？现有方案为什么不够？这是雪中送炭还是锦上添花？

可行性

• 技术：现有技术栈能否支持？是否需要引入新技术或外部服务？
• 资源：预估投入？外部依赖？
• 兼容：是否会改动现有数据模型 / 与已有功能冲突？

价值分级：

• 核心价值（影响主任务）→ 优先级高
• 效率价值（提升效率）→ 视资源决定
• 体验价值（美观/便利）→ 低优先级

MVP 界定：列子功能 → 分核心/辅助/优化 → MVP 只保留核心，能完成完整任务即可。

<PRINCIPLE> 用用户语言提问，避免技术术语。需求模糊时追问具体场景与具体用户，不要让用户用"可能/大概"。 </PRINCIPLE>

---

第二步：业务架构设计（中大型需求必做）

这一步不是给需求场景重新分组，而是做顶层设计——从需求中推导出系统应该怎么构建、怎么组织。

架构设计应该产出设计洞察，而不是需求的另一种排列。好的架构设计读完让人说"原来应该这样组织"，而不是"这就是需求换个说法"。

2.1 理解核心机制

先搞清楚这个系统/能力本质上是怎样运转的。不是罗列功能，而是理解运作机制——它靠什么原理工作、关键环节之间怎么咬合。

需要回答：

• 这个需求的核心命题是什么？一句话说清它在做什么事
• 要实现这个命题，系统需要哪些关键能力？这些能力各自解决什么问题？
• 这些能力之间的关系是什么？谁依赖谁的产出？谁触发谁？
• 数据/信息在系统中怎么流转？从哪里来、经过什么处理、到哪里去

怎么才算理解了机制：能说出"这个系统本质上是一个XXX"——比如"一个反馈控制循环"、"一个管道式处理链"、"一个事件驱动的协作网络"。如果能说出这个抽象，说明你看到了本质；如果只能说"它有4个功能"，说明你还停留在表面。

<PRINCIPLE> 核心机制描述应该让不懂技术的人也能理解"这个系统是怎么运转的"。用业务语言，不要用技术术语。重点说"它怎么工作"，不要说"它有哪些功能"。如果发现自己在罗列功能而不是描述运转方式，停下来重新想——机制是运作原理，不是功能清单。 </PRINCIPLE>

2.2 设计问题与决策

基于核心机制，识别需要做出的关键设计决策。这是架构设计的核心——架构就是一系列设计决策的结果。

设计问题不是从模板里挑的，而是从核心机制中涌现的。当你理解了系统怎么运转，自然会遇到"这个地方该怎么设计"的问题。下面的维度是审视的视角，不是填表的清单——每个维度只有在确实产生了设计问题时才展开，没有问题的维度不要硬写。

共性识别：多个环节是否在做"结构相同、数据不同"的事？如果是，差异在哪里——是处理流程不同，还是只是输入数据不同？如果流程同构、仅数据不同，值得抽取为中间层。判断关键——共性是"结构相同"而非"看起来相似"，两个环节都用了LLM不叫共性，但"获取上下文→LLM推理→产出结构化建议"这种流程同构就是。

独立性确认：哪些能力只服务于单一环节、逻辑与特定业务强绑定？这些不应该强行抽象——强行抽象会让简单问题变复杂，新增场景时反而要绕弯。

AI节点规划：核心机制中哪些环节需要AI参与？对每个环节想清楚：

• AI的任务类型——分类器（从有限选项判断）、生成器（产出新内容）、审核者（判断是否合格）、分析师（发现模式/异常）、规划者（分解目标为步骤）。这只是说明它在做什么类型的任务

• 选Agent还是LLM——默认倾向Agent。原因：Agent可以自主检索上下文，新增AI节点时只需给它工具和目标，不需要为每个节点专门开发上下文组装功能。选LLM意味着每次新增节点都要开发和维护"把什么数据喂给LLM"的上下文管道，这个隐性成本会随节点增多而持续增长。只有在输入完全确定且极其简单（如单条消息的分类判断）时，才考虑用LLM省掉工具调用的开销

• Agent角色定义（Agent节点必填，LLM节点不需要）——每个Agent节点不是通用AI，而是有明确身份的专家。定义角色定位才能决定它的思考视角、工具需求、决策边界和协作方式：

  • 角色定位：它在这个环节中扮演什么身份？比如"资深运维工程师"而非"问题发现器"——前者有经验判断的视角，后者只是机械执行。角色定位决定了它看问题的角度和做决策的倾向
  • 思考边界：它应该考虑什么、不应该考虑什么？比如诊断Agent应该深入分析根因但不应该越权提出修复方案——那是优化Agent的事。边界不清的Agent会越界，导致职责混乱
  • 需要的工具：基于角色定位和思考边界，这个Agent需要访问哪些数据、调用哪些能力？工具定义了Agent的行动范围——给了什么工具，它就在什么范围内自主决策
  • 决策自主度：哪些决策它可以自主做出、哪些必须上报或等待确认？风险等级影响自主度——低风险的判断可以自主，高风险的变更必须人工确认

风险分级：不同AI节点的错误后果不同。生成器产出直接生效会搞坏线上（高风险），分类器误判只是漏掉或误报（低风险），审核者过度否决会丢失优化机会（中风险）。风险不同→兜底策略不同→架构上区别对待。高风险节点必须有人工审核+自动化验证双重兜底，低风险节点不需要额外机制。

数据流与控制流：信息怎么流转？哪些环节串行（A的输出是B的输入）、哪些可并行？是否存在需要协调的环节（如多条路径的产出需要合并）？

决策的表达方式：每个决策用"问题→可选方案→选择→理由"的结构。理由要说清楚为什么，不能只说"更好"——要让读的人理解权衡过程。如果多个决策之间有关联（比如决策1选了A导致决策2只能选B），要说明关联关系。

2.3 模块划分

基于2.1的核心机制和2.2的设计决策，形成最终的模块组织。模块不是"功能分组"，而是设计决策的落地——每个模块的存在都应该有设计决策支撑。

每个模块说明：

• 职责（一句话）
• 层次（共性中间层 / 业务专属层）——共性层模块的存在一定有2.2的决策支撑
• 包含的AI节点（如有）——引用2.2的规划，Agent节点标注角色定位、工具需求、决策自主度
• 与其他模块的关系
• 本期范围 vs 未来扩展

2.4 架构验证

与用户一起确认：

• 核心机制的理解是否准确？有没有看偏？
• 设计决策是否有据？有没有遗漏的关键决策？
• 共性层是否抽取得当（不遗漏也不过度抽象）？
• AI节点选型是否合理？选LLM的节点是否有充分理由（输入完全确定且极简），而不是为了"可控"而牺牲扩展性？
• Agent节点的角色定位是否清晰？有没有职责重叠或边界模糊的Agent？
• 模块划分是否清晰？每个模块的存在都能追溯到设计决策吗？

---

第三步：梳理功能清单

每个功能用如下结构描述。功能按第二步的模块分组，同一模块的功能放在一起：

### [模块名]

#### 功能N：[功能名]

**触发条件**：[使用场景]

**用户入口（前端）**：
- 页面/路由：[页面名 + 路由]
- 触发元素：[按钮/菜单/快捷键]
- 可见性：[何种角色/状态可见]

**输入**：[字段 + 界面元素（表单/选择器/上传）]

**处理逻辑**：[系统做什么]

**输出**：
- 业务结果：[数据/状态]
- 界面呈现：[列表/详情/弹窗/Toast]
- 加载/空/错误态：[各状态界面表现]

**闭环**：触发入口 → 操作路径 → 完成终点 → 结果反馈（成功/失败的具体界面）→ 异常处理

**测试关注**（简要标记，供技术方案阶段拆分功能点）：
- 用 `[后端]` 标记需要后端验证的点（数据写入、参数校验、权限控制、业务逻辑分支）
- 用 `[前端]` 标记需要前端验证的点（页面渲染、交互反馈、状态转换、错误展示）
- 每个功能至少标记一个 `[后端]` 和一个 `[前端]` 关注点
- 不展开详细测试步骤，只标记"需要测什么"

示例：
```markdown
**测试关注**：
- [后端] 正常流程数据写入数据库
- [后端] 参数校验（空值、重复、格式错误）
- [前端] 成功反馈（Toast + 页面跳转）
- [前端] 失败反馈（表单错误标红 + 错误信息）
- [前端] 加载状态（按钮loading + 防重复提交）
```

闭环必检：每个功能必须能回答"用户从哪里进入 / 怎么操作 / 看到什么完成 / 失败怎么提示"，缺一即不完整。

跨模块功能标注：如果一个功能涉及多个模块的协作，在功能描述中标注涉及的模块和交互方式。

---

第四步：页面清单 + 时序图

页面/界面清单（汇总所有功能的用户入口）：

| 页面/视图 | 路由 | 所属模块 | 主要功能 | 关键组件 | 状态（loading/空/错误/成功） | 权限 | |----------|------|----------|----------|----------|------------------------------|------| | 工单列表 | /tickets | 工单模块 | 功能1、功能3 | 列表、筛选、分页 | 加载中 / 无数据 / 加载失败 | 已登录 |

校验：功能清单中每个"用户入口"页面必须出现在本表；本表每个页面必须至少对应一个功能。

时序图（Mermaid sequenceDiagram）展示业务流程与前后端交互：

sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant B as 后端
    participant D as 数据库
    U->>F: 触发操作
    F->>B: 发送请求
    B->>D: 查询/写入
    D-->>B: 返回
    B-->>F: 响应
    F-->>U: 展示结果

对于涉及多模块交互的流程，时序图中用不同 participant 区分各模块。

---

第五步：产出文档 + 自检 + 用户确认

命名：YYYY-MM-DD-需求标题.md 位置：workplace/1.X/requirements/（路径中 X 替换为实际数字）

文档模板

# [需求名称]

## 一、价值与可行性

### 1.1 用户与痛点
- 目标用户：[角色]
- 触发场景：[场景]
- 现状痛点：[描述]
- 价值判断：[核心/效率/体验]

### 1.2 不做的后果
[损失/持续痛点]

### 1.3 与现有方案的差异
[新方案解决了什么]

### 1.4 可行性
- 技术：[方案/风险]
- 资源：[投入/依赖]
- 兼容：[与现有功能/数据关系]
- 结论：完全可行 / 条件可行 / 暂时不可行

## 二、业务架构

> 小需求可写"本需求不涉及业务架构调整"，跳过以下各节。

### 2.1 核心机制
[描述系统/能力的核心运作机制——它怎么运转，关键能力是什么，能力之间的关系和数据流转]

### 2.2 设计问题与决策
[从核心机制中涌现的设计问题，逐个决策。维度：共性识别、独立性确认、AI节点规划（任务类型+Agent/LLM+Agent角色定义）、风险分级、数据流与控制流。每个决策：问题→可选方案→选择→理由。只展开确实产生设计问题的维度]

### 2.3 模块划分
[基于设计决策的模块组织，每个模块说明职责、层次、AI节点、依赖、本期vs扩展]

## 三、功能清单
（按模块分组，按第三步结构描述每个功能）

## 四、页面/界面清单
（按第四步表格汇总）

## 五、时序图
（Mermaid sequenceDiagram）

## 六、验收标准

| 维度 | 验证方法 | 成功标准 |
|------|----------|----------|
| 功能正确（后端） | [接口/逻辑测试步骤] | [指标] |
| 功能正确（前端） | [界面操作步骤] | [可见性/交互正确] |
| 性能 | [测试方法] | [响应时间] |
| 架构一致性 | [业务模块边界/协作验证] | [无协作断点、边界清晰] |

## 七、附录

### 7.1 特别关注点

> 讨论过程中用户强调的约束、风险或偏好，后续阶段务必注意。

- [各关注点]

### 7.2 风险清单
[识别的风险与应对——从第一步可行性分析和第二步设计决策中提取]

### 7.3 范围确认
- 本期功能：[本次需求确定要实现的所有功能，只列确定要做的]
- 不在本期：[明确排除的功能，说明原因（如：依赖其他模块、需后续迭代）]

**原则**：需求文档只包含确定要开发的内容。如果用户提到某些功能"以后再做"或"看情况"，不要写入需求文档，而是记录在"不在本期"中并说明原因。

附录填写说明：

• 7.1 特别关注点：从讨论过程中提取用户明确强调的约束、风险或偏好（非全部需求，仅用户特别指出需注意的内容）
• 7.2 风险清单：从第一步可行性讨论中提取技术/资源/兼容风险，从第二步设计决策中提取架构风险（如有）
• 7.3 范围确认：从第一步 MVP 界定和讨论中提取——"核心"功能列入本期，"辅助/优化"功能与用户确认后列入本期或"不在本期"

自检（一次 subagent 审查）

读取 references/doc-reviewer-prompt.md，将 [SPEC_FILE_PATH] 替换为实际路径后派发 subagent。

| 状态 | 处理 | |------|------| | 通过 | 进入用户确认 | | 发现问题 | 修复后无需重审 |

用户确认

需求文档已完成，保存至 <路径>。请确认：

• 价值判断是否准确？
• 业务架构是否合理？核心机制理解是否准确？设计决策是否有据？
• 功能清单是否完整、闭环？
• 页面清单是否覆盖所有功能入口？
• 验收标准是否可执行？

确认后宣布进入 tech-design，并产出交接清单：

需求文档已完成并确认。进入 tech-design 时请携带以下信息：

交接清单：

• 需求文档路径：workplace/1.X/requirements/YYYY-MM-DD-xxx.md
• 功能数量：N个（列出编号）
• 每个功能的测试关注标记数量：后端X个，前端Y个（供技术方案阶段拆分功能点）
• 页面数量：M个（列出路由）
• 关键验收标准：[摘要]
• 特别关注点：[从需求文档附录 7.1 节提取用户强调的内容]

tech-design 第一步应确认对这些内容的理解，在分析变更时基于测试关注标记创建功能点（FP-N），在制定测试策略时创建测试点（TC-N）。

---

特殊情况

• 需求过大：建议拆分子项目，先选一个讨论
• 需求模糊：要求用户举具体例子
• 价值不足：明确告知属于体验价值，确认是否仍要做
• 不可行：记录阻碍，讨论替代方案或推迟
• 架构分歧：给出2-3个设计方案，列出各自优劣和设计决策的差异，让用户选择
• AI选型拿不准：默认选Agent。Agent自主检索上下文的能力让新增节点只需给工具和目标，不需要为每个节点开发上下文组装——这是系统级的扩展性优势。只在输入完全确定且极简时才考虑用LLM

关联 skill

| Skill | 关系 | |-------|------| | tech-design | 本 skill 的下游：需求文档确认后，由 tech-design 基于需求产出技术方案 |