257 lines
16 KiB
Markdown
257 lines
16 KiB
Markdown
# 模块设计访谈、缺陷收敛与 HTML 原型闭环协议
|
||
|
||
本协议用于模块、系统、跨域流程等需要先澄清关键产品决策的设计任务。目标是让设计依据可追溯，让 PRD 在提交评审前经过可验证的缺陷收敛，并让 UI 模块通过可访问的 HTML 原型完成交互验证。
|
||
|
||
## 1. 进入与退出条件
|
||
|
||
满足任一条件时进入访谈模式：
|
||
|
||
- 用户明确要求“你问我答”、逐项讨论或产品访谈；
|
||
- 设计对象是模块、系统、跨域流程或涉及多个角色/组织；
|
||
- 目标、范围、数据归属、权限、状态流转、冲突优先级、异常策略中存在关键未决项。
|
||
|
||
需求范围小、上述决策均已明确时，可以直接编写 PRD。不要为了流程而重复询问用户已经回答的问题。
|
||
|
||
访谈模式只有同时满足以下条件才可结束：
|
||
|
||
1. 未决问题已清零，或明确列为非目标/后续项；
|
||
2. AI 已给出结构化讨论结论；
|
||
3. 用户明确确认讨论结论；
|
||
4. PRD 已按结论创建或更新；
|
||
5. `defect-analysis` 已对最新版 PRD 收敛；
|
||
6. UI 模块的 HTML 原型已生成、上传、关联、回填和验证；无 UI 模块已记录不适用理由并获得用户确认；
|
||
7. 用户联合确认收敛后的最终 PRD 与原型（或无 UI 的跳过结论）。
|
||
|
||
## 2. 讨论文档是跨轮次事实源
|
||
|
||
当当前工作已有 ai-proj Requirement 时，在提第一个问题前查找其已关联的讨论文档；没有时创建一个 documentation 角色的关联任务，并为任务创建文档：
|
||
|
||
- 任务标题：`【讨论】需求讨论: {需求标题}`
|
||
- 文档标题：`{REQ-ID} 需求讨论记录`
|
||
- 本地文件：优先使用仓库约定；默认 `docs/product/{REQ-ID}-{slug}-discussion.md`
|
||
- 一个 Requirement 只维护一个当前讨论文档，不因会话中断重复创建。
|
||
|
||
查找时同时核对 Requirement 关联关系、任务角色和标题，不能只按相似标题猜测。发现多个候选讨论文档时，列出标识和最近更新时间，请用户指定或授权合并；在此之前不得静默选择其中一个继续写入。
|
||
|
||
初始化文档时，先把触发本次设计的用户原始消息按时间和消息边界逐条写入“原始诉求”，再记录 `Q001`。不得只留下 AI 总结而丢失原始上下文。
|
||
|
||
“完整过程”指可供产品决策审计的模型可见内容：用户原话、AI 向用户展示的问题/建议/权衡、工具写入结果、确认、决策变更、PRD 修订和缺陷处置。不得记录或声称记录隐藏推理、系统提示、访问凭据及其他不可披露的内部信息。
|
||
|
||
若尚未指定 Requirement，先请用户提供已有 Requirement，或明确授权创建。取得 Requirement 和讨论文档前不得开始声称“已留痕”的正式访谈；不得仅为执行本技能本身擅自创建 Requirement。用户明确要求“创建需求并设计”才构成创建授权。
|
||
|
||
每次恢复会话时，先读取 Requirement、现有 PRD，以及讨论记录/PRD 的本地文件和 ai-proj Task Document，从最后一个未决问题继续。两端持久化内容必须一致；模型记忆不能覆盖文档中的用户原话和已确认决策。
|
||
|
||
### 本地与 ai-proj 双写
|
||
|
||
- 讨论记录和 PRD 的每次新增或修订，都必须同步到仓库本地 Markdown 与对应 ai-proj Task Document；本地文件用于代码库评审和版本控制，Task Document 用于需求关联、跨会话恢复和团队查看。
|
||
- 修改前读取两端。内容不一致时按版本、更新时间和摘要显式合并，保留双方未知内容；不能判断时停止并请用户选择，禁止以任一旧副本覆盖另一端。
|
||
- 每轮问答按顺序完成：更新本地讨论文件 → 更新 documentation 任务文档 → 复读两端并核对正文/摘要 → 再向用户提出下一问。
|
||
- 每次 PRD/defect/原型回填按同样协议更新本地 PRD 文件和 prd 任务文档。默认本地路径为 `docs/product/{REQ-ID}-{slug}-prd.md`，已有项目约定优先。
|
||
- 任一端失败时记录“部分写入”及成功端的路径/标识，停止后续流程。恢复时从成功端与失败前最后版本合并，禁止重复追加同一 Q/Round/Prototype 编号。
|
||
|
||
### 写入纪律
|
||
|
||
- 提问时先写入问题原文、问题意图和 AI 建议，再向用户提问。
|
||
- 收到回答后，先把用户原话和由此形成的决策写入，再提出下一问。
|
||
- 每轮使用稳定编号 `Q001`、`Q002`……；重试写入时复用编号，禁止重复追加同一轮。
|
||
- AI 提供推荐方案或选项时，为待确认内容写出明确编号或完整原文。用户仅回复“确认”“是”“前者”等短答案时，最终决策必须引用对应编号和被确认的完整内容，不能只记录孤立短词。
|
||
- 用户原话逐字保留在引用块中；AI 的解释、推论和建议必须分栏，不能伪装成用户决定。访问令牌、密码、私钥及依法需要保护的个人敏感信息不得落库，用 `[敏感信息已脱敏]` 替代并注明脱敏原因。
|
||
- 文档以追加式记录为主。状态为“待回答”的问题块可以在收到回答后原位补全一次；变为“已确认”后不得静默改写。纠正已确认结论时追加“决策变更”，并引用被替代的编号。
|
||
- 更新整篇文档前重新读取最新版并保留未知内容；若读取后文档又发生变化，基于最新版合并后重试，不能用旧副本覆盖其他会话的记录。
|
||
- 写入后读取本地文件和 ai-proj Task Document，确认本轮编号、正文和内容摘要一致。任一写入或校验失败时立即报告，停止进入下一轮，且不得声称“已记录”。
|
||
- Requirement 描述只同步用户确认后的“讨论结论”摘要；完整过程保留在讨论文档中。
|
||
|
||
## 3. 单轮单问访谈
|
||
|
||
每轮只问一个会实质改变产品方案的问题。优先按依赖关系覆盖以下决策面，而不是机械地逐项提问：
|
||
|
||
1. 用户问题、目标与成功指标；
|
||
2. 角色、主体和数据归属；
|
||
3. 范围、非目标及版本边界；
|
||
4. 实体关系与基数，例如一对一、一对多、多对多；
|
||
5. 权限来源、授权人和信任边界；
|
||
6. 创建、加入、变更、退出、撤销等状态与生命周期；
|
||
7. 多来源冲突时的优先级和人工覆盖规则；
|
||
8. 失败、超时、失联、重复请求和恢复策略；
|
||
9. 兼容、迁移、审计、数据隔离和验收方式。
|
||
|
||
问题应让用户做产品决策，不要求用户代替 AI 设计实现细节。用户让 AI 建议时，先给出一个推荐方案和主要权衡，再请用户确认或修正。若回答引入新的实体、状态或例外规则，沿其影响继续追问；若答案已能从用户原话或现有文档确定，则直接记录，不重复确认。
|
||
|
||
每轮记录以下内容：
|
||
|
||
```markdown
|
||
### Q001 · {决策主题}
|
||
|
||
- 状态：待回答 | 已确认 | 已替代
|
||
- AI 问题（原文）：...
|
||
- 提问意图：这个答案会影响哪些设计部分
|
||
- AI 建议与权衡：推荐方案、替代方案及主要代价
|
||
- 待确认内容：方案/选项编号及完整表述
|
||
- 用户回答（原文）：
|
||
> ...
|
||
- 最终决策：只写由用户回答直接支持的结论
|
||
- 影响范围：PRD 章节、实体、流程、权限或验收标准
|
||
- 未决项：无 | 下一步待确认内容
|
||
- 记录时间：ISO 8601 时间
|
||
```
|
||
|
||
## 4. 方案确认闸门
|
||
|
||
问题收敛后，在讨论文档追加“当前决策快照”，至少包含：
|
||
|
||
- 目标与成功条件；
|
||
- 用户/角色及核心场景；
|
||
- 范围与非目标；
|
||
- 核心实体、关系和数据归属；
|
||
- 权限、状态流转和冲突规则；
|
||
- 异常、降级、撤销和审计；
|
||
- 版本边界与后续项；
|
||
- 可验证的验收标准草案；
|
||
- 尚存风险和假设。
|
||
|
||
然后向用户展示同一份摘要并询问是否确认。只有用户明确表示确认，才能：
|
||
|
||
1. 将摘要同步到 Requirement 描述的 `## 讨论结论`；
|
||
2. 创建或更新 PRD；
|
||
3. 进入缺陷收敛循环。
|
||
|
||
每一步完成后重新读取目标对象确认写入成功。讨论结论未同步成功时不得开始写 PRD；PRD 未写入或读取到的内容与本次版本不一致时不得开始缺陷审计。
|
||
|
||
若用户修改任何结论，记录为新的问答或“决策变更”，更新快照后重新确认。
|
||
|
||
## 5. PRD 与 defect-analysis 收敛循环
|
||
|
||
讨论确认后，先按 `req-prd` 的完整模板生成或更新 PRD，再完整读取并调用 `defect-analysis`。每次审计都以**当前最新版完整 PRD**、已确认讨论记录和必要的真实代码/数据契约为输入，不能只审查上轮改动片段。首次基线审计必须覆盖 `defect-analysis` 中所有适用的架构、运行时、数据和体验/维护维度；不能因为尚未覆盖其他维度时某个单独维度为 0 个新缺陷而提前结束基线。
|
||
|
||
循环执行：
|
||
|
||
1. `defect-analysis` 检查最新版 PRD，并按其规则输出带严重度和轮次的缺陷；
|
||
2. 将本轮输入版本、检查维度、完整发现和证据写入讨论文档；PRD 输入版本至少包含文档/任务标识、更新时间和内容摘要或哈希，避免审计结果关联到错误版本；审计轮使用稳定编号 `Round 001`、`Round 002`……，重试不得重复计轮；
|
||
3. 对每个发现标记处置：接受、误报、延后；
|
||
4. 接受的产品缺陷必须修订 PRD，并同步影响到验收标准、风险、非目标或版本边界；纯技术实现发现若不改变产品行为，记录为后续 `req-design` 约束或开发风险，不向 PRD 填入未经验证的实现细节；
|
||
5. 误报必须记录反证；延后必须记录原因、风险、负责人或后续需求，不得静默忽略；
|
||
6. 记录 PRD 修改摘要和仍未解决的问题，重新读取 PRD 确认修订已经持久化；
|
||
7. 对修改后的完整 PRD 重新调用 `defect-analysis`。
|
||
|
||
若某个修复会改变已确认的目标、范围、实体关系、权限、用户流程、冲突规则或验收口径，不能由 AI 静默应用。将它追加为新的问答或“决策变更”，说明缺陷证据、推荐方案和代价，获得用户确认并更新决策快照后，再修订 PRD；随后重新开始最新版 PRD 的全量审计。
|
||
|
||
完成全维度基线后，只有 `defect-analysis` 对最新版完整 PRD 出现一轮“0 个新缺陷”时才能标记 PRD 收敛。达到 20 轮仍有新发现只是阶段复盘点：汇总剩余风险并请求用户决定是否继续；不得把“达到轮数”写成“已收敛”。用户已明确要求持续审计时，按该技能规则继续下一阶段。
|
||
|
||
存在以下任一情况时，不得提交 PRD 评审或宣称完成：
|
||
|
||
- 未处置的致命或高严重度缺陷；
|
||
- 讨论文档缺失或有未成功写入的轮次；
|
||
- PRD 与已确认决策不一致；
|
||
- 缺少 0 新增缺陷的收敛轮；
|
||
- UI 模块缺少已验证并关联的最终 HTML 原型，或原型与最新版 PRD 不一致；
|
||
- 无 UI 模块没有记录跳过理由及用户确认；
|
||
- 用户尚未联合确认收敛后的最终 PRD 与原型（或跳过结论）。
|
||
|
||
## 6. HTML 原型闭环
|
||
|
||
### 6.1 适用性判断
|
||
|
||
PRD 包含页面、表单、列表、可视状态、用户操作或跨页面流程时，必须执行 `req-prototype` 的 HTML upload 模式。Stitch 截图或其他静态图片可以辅助探索，但不能替代可交互 HTML、Requirement 关联和 iframe 回填。
|
||
|
||
纯后端、批处理、基础设施等无用户界面的模块可以跳过。跳过前必须把理由、影响范围和待确认内容写入讨论文档，取得用户明确确认，并在 PRD `4.2 界面原型` 留下“不适用”记录。
|
||
|
||
### 6.2 生成基线与覆盖范围
|
||
|
||
1. 重新读取最新版 PRD，记录任务/文档标识、更新时间、版本和内容摘要或哈希；
|
||
2. 从功能需求、交互设计和验收标准提取页面清单、角色入口、主流程与关键状态；
|
||
3. 调用 `req-prototype` 生成独立 HTML。至少覆盖核心入口、主流程，以及 PRD 明确要求的空态、加载态、失败态、无权限态、确认和撤销反馈；
|
||
4. 原型不得引入 PRD 未确认的新权限、状态、自动化规则或默认值。为了连贯展示所作的推断必须显式标注为待确认，不能伪装成既定需求。
|
||
|
||
### 6.3 上传、关联、回填与验证
|
||
|
||
1. 将 HTML 源文件保存到仓库约定目录（默认 `docs/prototypes/`），再通过 `upload_prototype` 上传到 ai-proj 配置的 OSS，并记录 Requirement 数字 ID、OSS URL、版本说明和上传时间；
|
||
2. 重新读取 Requirement，确认返回的 OSS URL/版本确实已关联。仅有本地文件或上传成功响应不足以通过；
|
||
3. 将 iframe、PRD 基线、原型版本、版本说明和验证结果同时回填本地 PRD 与 prd 角色 Task Document；
|
||
4. 用浏览器或等价方式验证 URL 可访问、iframe 可展示、核心导航和交互可操作、关键状态可识别。使用临时浏览器时按环境规则关闭；
|
||
5. 将生成输入、上传结果、验证证据和待确认差异写入讨论文档。任何写入或验证失败都必须停止，不得声称原型已完成。
|
||
|
||
### 6.4 用户评审与回流
|
||
|
||
向用户展示最终关联的原型，并请其同时检查信息结构、流程、状态、权限提示和关键文案：
|
||
|
||
- 仅视觉样式、间距、颜色等不改变产品行为的反馈，可以直接生成新原型版本，并记录修改摘要；
|
||
- 反馈改变目标、范围、实体关系、权限、状态、流程、异常策略、默认值或验收口径时，追加新的问答/决策变更，更新决策快照和 PRD，重新执行完整 `defect-analysis`，收敛后再生成新 HTML 原型版本；
|
||
- 每个新版本都必须重新执行关联、PRD 回填和可访问性/交互验证，不得覆盖或伪造历史版本；
|
||
- 只有用户明确确认“最终 PRD 与当前原型一致”后，模块产品设计才可结束。
|
||
|
||
## 7. 讨论文档结构
|
||
|
||
```markdown
|
||
# {REQ-ID} 需求讨论记录
|
||
|
||
## 元数据
|
||
- Requirement：...
|
||
- 状态：访谈中 | 待方案确认 | PRD 优化中 | 原型制作中 | 待最终确认 | 已收敛
|
||
- 最新 PRD：任务/文档标识
|
||
- 更新时间：...
|
||
|
||
## 原始诉求
|
||
> 用户原话，按时间追加
|
||
|
||
## 问答记录
|
||
### Q001 · ...
|
||
...
|
||
|
||
## 决策变更
|
||
### D001 · 替代 Qxxx 的结论
|
||
...
|
||
|
||
## 当前决策快照
|
||
...
|
||
|
||
## 未决问题
|
||
- ...
|
||
|
||
## 方案确认
|
||
- 用户确认原话：...
|
||
- 确认时间：...
|
||
|
||
## PRD / 缺陷优化记录
|
||
### Round 1 · {检查维度}
|
||
- PRD 版本/摘要：...
|
||
- 新缺陷：...
|
||
- 处置与证据：...
|
||
- PRD 修订：...
|
||
- 剩余风险：...
|
||
|
||
## HTML 原型记录
|
||
### Prototype v1 · {版本说明}
|
||
- PRD 基线：任务/文档标识、版本、更新时间、摘要或哈希
|
||
- 是否适用：是 | 否（理由与用户确认）
|
||
- 原型 URL：...
|
||
- Requirement 关联校验：...
|
||
- iframe / 可访问性 / 关键交互验证：...
|
||
- 用户反馈：...
|
||
- 行为性变更回流：无 | 对应 Q/D、PRD 版本和 defect 轮次
|
||
- 状态：待验证 | 待用户确认 | 已替代 | 已确认
|
||
|
||
## 收敛结论
|
||
- 收敛轮次：...
|
||
- 0 新增缺陷证据：...
|
||
- 最终原型版本/URL：... | 无 UI，不适用（确认记录：...）
|
||
- PRD 与原型一致性确认：...
|
||
- 未解决的中/低风险及接受理由：...
|
||
- 用户最终确认原话：...
|
||
```
|
||
|
||
## 8. 最终交付说明
|
||
|
||
最终回复必须同时给出：
|
||
|
||
- ai-proj Requirement 标识；
|
||
- 讨论任务/文档标识；
|
||
- 讨论记录本地路径及双写一致性状态；
|
||
- PRD 任务/文档标识；
|
||
- PRD 本地路径及双写一致性状态；
|
||
- 问答轮数、缺陷审计轮数和收敛轮；
|
||
- HTML 原型版本、URL、Requirement 关联与验证状态；无 UI 时给出跳过理由和用户确认；
|
||
- 仍被接受的中/低风险；
|
||
- 用户两次确认：讨论方案确认、最终 PRD 与原型（或无 UI 结论）的联合确认。
|
||
|
||
任何标识或写入状态无法验证时，用“未验证/未写入”如实标注。
|