From 629dbc05a4194d6d742c4547e134e6826c9fd53a Mon Sep 17 00:00:00 2001 From: wdh-home <243823965@qq.com> Date: Fri, 15 May 2026 16:42:38 +0800 Subject: [PATCH] docs: refine PRD draft layering rules --- SKILL.md | 34 +++- references/prd-draft-document-spec.md | 51 +++++- references/prd-draft-format-template.md | 197 ++++++++++++++++++++++-- 3 files changed, 264 insertions(+), 18 deletions(-) diff --git a/SKILL.md b/SKILL.md index 6a0d755..b550fa0 100644 --- a/SKILL.md +++ b/SKILL.md @@ -31,20 +31,38 @@ description: Use when 用户输入 /ks-prd-draft，或需要围绕任意项目 ## 会话锚点 - 如果用户明确提供了一个需求文档路径，将该文件作为唯一可写锚点。 +- 如果用户明确提供的是需求主题目录，先定位目录下唯一主草案：优先使用已有 `*-prd.md`；没有时再按项目既有约定使用 `prd.md`；新建草案包时使用 `-prd.md`。 - 如果当前会话已经建立需求文档路径或需求主题，后续短指令默认继续使用该锚点。 - 如果用户未提供路径且会话没有锚点，按项目说明和已有文档目录匹配主题；常见候选可以包括 `docs/`、`specs/`、`requirements/`、`prd/`、`.ai-specs/` 或项目自定义目录，但不要写死任何一种。 - 如果只有一个强匹配候选文件，说明所选文件和匹配原因，然后继续。 - 如果存在多个候选文件，停止并请用户确认目标文件路径。 - 未经用户明确确认，不切换主题或文件锚点。 +## 文档组织原则 + +- 具体文档结构、草案包目录、引用路径和模板选择以 `references/prd-draft-document-spec.md` 为准；创建或重建正文时再读取 `references/prd-draft-format-template.md`。 +- 主草案始终是唯一需求口径，写业务目标、范围、流程、业务规则、数据含义、权限、边界、异常和待确认项。 +- `decisions.md` 只记录确认结论、冲突、取舍、待确认事项和覆盖记录；`references/` 只存放外部协议、客户材料、性能建议、接口草稿或来源摘录等参考材料。 +- 关联文档必须使用相对当前文档的可迁移路径；不要把用户机器绝对路径写入 PRD 正文。 +- 项目已有同类文档风格时优先沿用；没有项目风格时，再按模板选择流程文档、要求文档或通用骨架。 + +## 方案分层判定 + +- 当用户讨论“方案”“逻辑方案”“性能方案”“优化方案”时，先判断内容是在定义业务判定，还是在指定实现手段。 +- 业务逻辑方案必须进入主草案：触发条件、开始和结束边界、有效和失效口径、状态流转、分支异常、成功失败结果、验收口径。例如“同一连接轮次如何开始、结束、失效”属于业务判定，不应留给下游自由解释。 +- 技术实现方案不得写成主草案的确定需求：具体中间件、缓存、队列、索引、部署形态、服务内存状态、任务调度、代码结构等只可作为 `references/` 参考来源或 `decisions.md` 决策背景。 +- 主草案可以引用参考材料，但正文必须写成业务目标和约束，例如响应时限、高峰期可用性、一致性、重复提交处理、异常恢复结果；不要写“使用某技术实现”。 +- 如果一个方案同时包含业务判定和实现手段，拆开处理：业务判定进入主草案，取舍背景进入 `decisions.md`，实现建议摘要进入 `references/`。 + ## 工作模式 ### 新建需求 - 当用户要创建新需求，且当前上下文和项目既有需求文档中没有对应草案时，优先沿用项目已有需求文档目录和命名风格。 - 如果项目没有可判断的需求文档位置或命名规则，先询问用户目标路径；不要擅自发明项目规范。 -- 文件名优先沿用项目既有命名风格；没有明显风格且用户允许创建时，使用可读的短横线英文主题名，例如 `book-comment.md`。 -- 新文档正文优先沿用项目已有模板；项目没有模板时，使用 `prd-draft-format-template.md` 的通用骨架。 +- 如果项目已有 `.ai-transition/prd-draft` 过渡区，且用户没有指定更具体的项目规范，按文档规范中的草案包结构创建或定位 `-prd.md`。 +- 文件名优先沿用项目既有命名风格；没有明显风格且用户允许创建时，使用可读的短横线英文主题名，例如 `.md`。 +- 新文档正文优先沿用项目已有模板；项目没有模板时，按文档类型使用 `prd-draft-format-template.md` 的整篇文档模板或通用骨架。 ### 更新需求 @@ -52,6 +70,7 @@ description: Use when 用户输入 /ks-prd-draft，或需要围绕任意项目 - 用户用实现语言表达需求时，先转成业务需求语言：表、字段、model、结构体归一为业务数据对象和数据项；API、Service、任务、页面组件归一为业务能力、流程、交互或集成需求。 - 对简单缺失细节，写入草案并明确标记 `需补` 或 `待确认`，不要因为非阻塞细节缺失而停止整理。 - 用户只是讨论备选方案时，不要把未确认选项写成确定结论。 +- 同一轮编辑、同一次未提交 diff 或同一轮对话推演中，临时方案被提出后又被否定时，不把它写成“不要”“不支持”“取消”等否定事实；直接移除临时方案，只保留最终确认需求。只有该方案已经出现在已提交、已确认、已评审或已对外同步的基线版本中，或需要防止需求外溢时，才写入变更说明、范围外或决策记录。 - 发现需求与既有事实冲突、逻辑不闭环、明显不合常理、存在业务 bug 风险或会引入不必要复杂度时，先指出问题并要求确认；如果问题已经足以构成修正讨论，不只说明问题本身，还要同步整理 3 个可执行方案，并明确给出 AI 推荐的最优方案和推荐理由。 ### 检查需求 @@ -60,7 +79,7 @@ description: Use when 用户输入 /ks-prd-draft，或需要围绕任意项目 - 默认只检查并反馈，不直接修改文档；只有用户明确要求“修复”“按方案改”“直接更新文档”时才写入。 - 检查对象是当前锚定的需求草案，并结合本轮会话中用户刚确认但尚未落盘的信息。 -- 按 `prd-draft-document-spec.md` 检查完整性、逻辑闭环、业务合理性、既有资产复用、未确认事项和越界实现细节。 +- 按 `prd-draft-document-spec.md` 检查完整性、逻辑闭环、业务合理性、既有资产复用、文档引用路径、未确认事项和越界实现细节。 - 检查是否还有阻塞进入下一阶段的 `需补`、`待确认`、事实冲突或未闭环事项。 - 检查输出时，问题定位和方案建议必须成对出现；除非用户明确要求只列问题，否则不要只报告问题而不给修正路径。 @@ -89,6 +108,8 @@ description: Use when 用户输入 /ks-prd-draft，或需要围绕任意项目 - 数据是否完整：需要维护、读取、展示、统计或传递的数据是否有业务含义、来源、生成规则和使用场景。 - 权限是否合理：谁能看、谁能改、谁能触发，越权和不可见场景是否说明。 - 边界是否充分：空数据、重复提交、失败、撤销、历史数据、并发或生命周期结束后的处理是否合理。 +- 引用是否可迁移：关联文档是否使用相对当前文档的路径或语义引用，是否避免用户机器绝对路径和项目根目录绑定路径。 +- 分层是否清楚：业务逻辑方案是否写成主草案规则，技术实现方案是否只作为参考、决策背景或业务约束来源。 - 常理是否成立：是否符合主流产品习惯、正规业务流程、行业常识和最小必要复杂度。 ## 边界 @@ -108,6 +129,7 @@ description: Use when 用户输入 /ks-prd-draft，或需要围绕任意项目 - 不把 API path、HTTP method、request/response schema、SQL DDL、field type、index、unique constraint、migration script、class、struct、service、router、component 或文件结构设计写入 PRD 草案。 - 不为了满足模板而创建空分区、伪造业务对象、伪造数据项、编造状态值或把未确认事项写成确定结论。 - 不在未检查既有资产的情况下，把用户功能需求写成新建模块、新增数据表、新增接口或新增页面。 +- 不把 Redis、MQ、缓存、索引、分库分表、异步任务等性能或实现方案写成 PRD 的确定需求；只能转译为业务约束或放入参考材料、决策记录。 ## 交互与完成 @@ -119,8 +141,8 @@ description: Use when 用户输入 /ks-prd-draft，或需要围绕任意项目 示例： ```text -/ks-prd-draft docs/prd/book-comment.md 增加书籍评论功能 -/ks-prd-draft 修改书籍评论审核规则 -/ks-prd-draft 增加书籍评论功能 +/ks-prd-draft docs/prd/.md 增加 <主题> 需求 +/ks-prd-draft 修改 <主题> 规则 +/ks-prd-draft 增加 <主题> 需求 检查 ``` diff --git a/references/prd-draft-document-spec.md b/references/prd-draft-document-spec.md index 998032a..0f531be 100644 --- a/references/prd-draft-document-spec.md +++ b/references/prd-draft-document-spec.md @@ -18,11 +18,49 @@ - 文档路径和文件名优先沿用项目既有约定；没有约定时，由用户确认目标路径。 - 一个需求文档应描述一个清晰业务主题；主题过宽时先建议拆分。 -- 标题、元信息、章节结构优先沿用项目模板；没有模板时，可使用 `prd-draft-format-template.md` 的通用骨架。 +- 标题、元信息、章节结构优先沿用项目模板；没有模板时，按文档类型使用 `prd-draft-format-template.md` 的整篇文档模板或通用骨架。 - 不为了套模板创建空章节、空表格、伪造对象或重复内容。 - 不把同一批数据项、规则或流程在多个章节中重复抄写。 - 未确认事项必须保留在相关需求语境中，标记为 `需补` 或 `待确认`。 +## 草案包结构 + +- 当项目使用 `.ai-transition/prd-draft` 作为需求草案过渡区，且用户未指定具体文件时，复杂需求默认按业务能力域和需求主题组织为草案包： + +```text +.ai-transition/prd-draft/// + -prd.md + decisions.md + acceptance.md + references/ +``` + +- `` 表示业务能力域或协议域，例如 `order`、`workflow`、`integration`、`notification`；不得用来源项目名、语言、框架、技术层或具体技术组件命名。 +- `` 表示需求主题，使用小写英文、数字和短横线；不得使用 `new-feature`、`misc`、`test` 等泛名。 +- `-prd.md` 是唯一主需求草案；文件名必须包含业务主题，目录名过宽时使用更具体的业务短横线名，例如 `erp-integration-prd.md`。如果用户明确提供单个文件路径，则该文件继续作为锚点，不强制迁移为草案包。 +- `references/` 用于存放外部协议、客户材料、历史说明、性能建议、接口草稿、来源摘录等强依赖参考材料；材料必须脱敏、裁剪或摘要化，不得只保留本机绝对路径。性能或优化建议可摘要为 `./references/performance-notes.md`。 +- `decisions.md` 用于记录确认结论、冲突、取舍、待确认事项和覆盖记录；不得扩写成技术设计、实现计划或任务拆解。 +- `acceptance.md` 用于记录验收补充和边界补充；简单需求可以保持为“以主草案为准”，不得重复扩写主需求。 +- 默认不创建 `flows/`、`rules/` 等额外目录；只有主草案明显过长、辅助文档能减少重复或用户明确要求拆分时，才在同一草案包内新增辅助文档。 +- 主草案内的关联材料必须使用相对主草案的路径，例如 `./references/external-protocol.md`；不得在正文中写用户机器绝对路径。 + +## 文档类型 + +- 需求以触发、步骤、链路、状态流转、分支异常为核心时，优先写成流程文档。 +- 需求以适用对象、执行约束、交付约束、验收约束、禁止事项为核心时，优先写成要求文档。 +- 流程文档必须能看出从触发到结果的完整链路；要求文档必须能看出每条规则是否可执行、可判断、可验收。 +- 选择模板时只使用抽象占位和用户已确认信息，不带入具体业务、具体页面、具体模块或未经确认的示例。 +- 项目已有同类文档风格时，优先沿用项目风格，不强行改成通用骨架。 + +## 文档引用 + +- 用户提供的本机路径或项目内路径只用于定位文件；写入 PRD 正文时必须转成可迁移引用。 +- `关联协议`、`关联主流程`、`关联文档`、`参考文档` 等引用优先使用相对当前文档的路径；同目录写成 `./xxx.md`，上级或兄弟目录写成 `../xxx/yyy.md`。 +- Markdown 正文路径使用 `/` 分隔，不使用 Windows `\` 分隔。 +- 不把 `C:\...`、`D:\...`、`/Users/...`、`/home/...` 等用户机器绝对路径写入 PRD 正文。 +- 除非项目规范明确要求，不从项目根目录写路径；需要脱离项目目录共享时，优先写“同目录《文档标题》”或相对当前文档的短路径。 +- 检查或更新既有文档时，发现不可迁移引用路径，应作为 `建议修正` 给出相对当前文档的替代写法。 + ## 需求表达 - 用业务语言描述需求：目标、参与方、触发条件、输入、处理规则、输出、状态、边界、异常、权限和生命周期。 @@ -30,8 +68,13 @@ - 表、字段、列、属性、model、struct 转为业务数据对象和数据项。 - API、Service、任务、队列、缓存、页面组件 转为业务能力、流程、交互、集成或展示需求。 - 索引、唯一约束、字段类型、请求响应结构 转为业务唯一性、校验规则、数据含义或交互约束。 +- 外部非业务方案应转译为业务约束或参考材料：例如“用 Redis 解决性能问题”只可在 `references/` 或 `decisions.md` 中作为来源背景，在主草案中应表达为响应时限、高峰期可用性、一致性、重复提交处理等可验收业务要求。 +- 业务逻辑方案不等同于技术方案。凡是在定义业务判定口径、触发和结束边界、状态有效性、分支结果、异常归类或验收标准的内容，必须写入主草案，不能下放给下游技术方案自由定义。 +- 技术实现方案必须从业务规则中剥离。具体中间件、缓存、队列、索引、部署形态、服务内存状态、任务调度、代码结构等，只能作为参考来源、决策背景或待下游设计处理。 +- 如果同一段方案同时包含业务逻辑和实现建议，应拆分记录：主草案保留业务判定和结果约束，`decisions.md` 记录已确认取舍，`references/` 保存实现建议或性能建议摘要。 - 如果某个技术名词本身就是项目通用业务术语，可以保留术语，但不要扩展成实现设计。 - 备选方案只能写成备选或待确认，不写成已确认结论。 +- 同一轮编辑、同一次未提交 diff 或同一轮对话推演中，临时方案被提出后又被否定时，不写入正文作为“不要”“不支持”“取消”等否定事实；正文只保留最终确认需求。只有该方案已经出现在已提交、已确认、已评审或已对外同步的基线版本中，或确实需要声明范围边界以防需求外溢时，才写入变更说明、范围外或决策记录。 ## 数据表达 @@ -56,8 +99,12 @@ - 完整性：目标、范围、参与方、触发、输入、处理、输出、权限、边界、异常、状态和生命周期是否齐全。 - 闭环：用户或系统从触发到结果是否能走通；成功、失败、取消、重复、历史数据和异常中断是否有合理结果。 - 数据：业务数据对象、数据项、来源、生成规则、使用场景、值域和状态是否完整。 +- 文档类型：流程文档是否突出完整链路，要求文档是否突出可执行约束，是否错误套用了不适合的通用骨架。 +- 草案包：复杂需求是否把主需求、参考材料、决策和验收补充分清；`-prd.md` 是否仍是唯一主草案。 +- 分层：业务逻辑方案是否进入主草案，技术实现方案是否已转译为业务约束或放入参考材料和决策背景。 - 合理性：是否符合主流产品习惯、正规业务流程、行业常识、权限常识和最小必要复杂度。 - 复用：是否已检查既有资产，是否误写成新增表、新增接口、新增页面或新增模块。 +- 引用：关联协议、关联主流程、关联文档或参考文档是否使用可迁移引用，是否避免用户机器绝对路径和项目根目录绑定路径。 - 边界：是否遗漏空数据、重复提交、并发、撤销、回退、历史兼容、不可见、无权限和生命周期结束场景。 - 未确认项：是否还存在阻塞进入下一阶段的 `需补`、`待确认`、事实冲突或未闭环事项。 - 越界项：是否混入 API 路径、请求响应结构、SQL、字段类型、类名、文件结构、任务拆解或代码实现。 @@ -91,6 +138,8 @@ - 禁止为了套模板编造业务对象、数据项、字段清单、状态值、字典值或空章节。 - 禁止把未确认事项写成确定结论。 - 禁止把用户的功能需求在未检查既有资产前直接推导为新建表、新增接口、新建页面或新模块。 +- 禁止把用户机器绝对路径或不必要的项目根目录绑定路径写成 PRD 正文中的关联文档引用。 +- 禁止把 Redis、MQ、缓存、索引、分库分表、异步任务、服务部署等实现或性能方案写成 PRD 的确定实现要求；需求草案只能保留其业务目标、约束、验收口径或参考来源。 ## 模板 diff --git a/references/prd-draft-format-template.md b/references/prd-draft-format-template.md index 0152610..543270e 100644 --- a/references/prd-draft-format-template.md +++ b/references/prd-draft-format-template.md @@ -2,6 +2,92 @@ 创建新需求草案、重建正文结构或需要参考需求项写法时使用本文件。项目已有模板时优先使用项目模板；本文件只作为通用兜底模板和写法示例。硬性规则以 `prd-draft-document-spec.md` 为准。 +## 草案包目录模板 + +适用场景：目标落点是 `.ai-transition/prd-draft`，且需求包含复杂业务闭环、外部协议、客户材料、非业务方案、性能建议或多轮决策记录。 + +```text +.ai-transition/prd-draft/// + -prd.md + decisions.md + acceptance.md + references/ +``` + +- `-prd.md`：唯一主需求草案，文件名应包含可检索的业务主题；目录名过宽时使用更具体的业务短横线名，例如 `erp-integration-prd.md`。 +- `decisions.md`：确认结论、冲突、取舍、待确认事项和覆盖记录。 +- `acceptance.md`：验收补充和边界补充；简单需求可写“以主草案为准”。 +- `references/`：外部协议、客户材料、历史说明、性能建议、接口草稿、来源摘录等强依赖参考材料。 +- 默认不创建 `flows/`、`rules/` 等额外目录；确需拆分时，在同一草案包内新增辅助文档，并从主草案使用相对路径引用。 + +## 草案包配套文件模板 + +### decisions.md + +````md +# decisions + +## 已确认 +- 无 + +## 待确认事项 +- 无 + +## 冲突与取舍 +- 状态：none +- 冲突：无 +- 影响：无 +- 当前结论：无 + +## 覆盖记录 +- 允许覆盖：否 +- 确认人：无 +- 确认时间：无 +- 覆盖范围：无 +- 确认依据：无 +```` + +### acceptance.md + +````md +# acceptance + +## 验收补充 +- 无；以主草案的验收或业务闭环要求为准。 + +## 边界补充 +- 无 +```` + +### references/README.md + +````md +# references + +本目录存放当前需求草案强依赖的外部协议、客户材料、历史说明、性能建议、接口草稿或来源摘录。 + +- 材料必须脱敏、裁剪或摘要化。 +- 不把用户机器绝对路径作为唯一依据。 +- 非业务方案只能作为参考来源，不代表 `../-prd.md` 已确认对应实现。 +```` + +### references/performance-notes.md + +````md +# performance-notes + +## 来源摘要 +- 来源：<客户材料、历史说明、评审结论或会话讨论> +- 背景：<为什么提出性能、容量、稳定性或恢复要求> + +## 可转译业务约束 +- <响应时限、同步完成时限、高峰期可用性、一致性、重复提交处理或异常恢复结果> + +## 非确定实现参考 +- <方案名称或来源摘录>：<只保留逻辑思路、适用前提和主要取舍，不扩写成技术设计> +- 本节不代表主草案已确认具体实现；主草案只引用已转译的业务目标、约束或验收口径。 +```` + ## 通用正文骨架 ````md @@ -10,11 +96,13 @@ - **阶段** 需求草案阶段 - **状态** 制定中 - **锚点** <需求文档路径或需求主题> +- **关联文档** <如需要引用其他文档，使用相对当前文档的路径，例如 `./protocol.md` 或 `../main-flow.md`；不要写用户机器绝对路径> +- **关联材料** <草案包中优先写 `./references/.md`；没有则写“无”> ## 目标与范围 - 目标：<本需求要解决的业务问题和成功状态> - 范围内：<明确包含的业务对象、流程、角色或场景> -- 范围外：<明确不处理的内容，避免需求外溢> +- 范围外：<明确不处理的内容，避免需求外溢；不记录同一轮未确认推演中被否定的临时方案> ## 业务闭环 - 参与方：<用户、管理员、系统、外部方等> @@ -29,9 +117,79 @@ ## 需求项 - <需求项名称>：<已确认需求内容> - 数据项 <名称>：<业务含义、来源、生成方式、使用规则> +- 业务约束 <名称>：<由外部非业务方案转译来的业务目标、响应时限、一致性或可用性要求；不写 Redis、MQ、缓存等实现方案> - 待确认：<不阻塞主链路但后续需要确认的问题> ```` +## 整篇文档模板 + +### 流程文档模板 + +适用场景：需求主题以触发、步骤、链路、状态流转、分支异常为核心。只填用户已确认的信息，不带入具体业务、具体页面、具体模块或未经确认的示例。 + +````md +# <主题>流程需求草案 + +适用对象：<阅读或执行对象> +关联文档：`./<关联文档>.md` + +## 流程目标 +- <流程需要达成的业务结果> + +## 参与方 +- <参与方>：<职责> + +## 前置条件 +- <流程开始前必须满足的条件> + +## 主流程 +1. <步骤 1> +2. <步骤 2> +3. <步骤 3> + +## 分支与异常 +- <条件或异常>：<处理结果> + +## 状态与生命周期 +- <状态或阶段>：<进入条件、退出条件和结果> + +## 边界要求 +- <重复、失败、取消、历史、权限或其他边界> + +## 禁止事项 +- 禁止 <会破坏流程闭环的行为> + +## 待确认 +- 待确认：<不阻塞主流程但后续需要明确的事项> +```` + +### 要求文档模板 + +适用场景：需求主题以适用对象、执行约束、交付约束、验收约束、禁止事项为核心。少写背景解释，多写可执行、可判断、可验收的规则。 + +````md +# <主题>要求 + +适用对象：<执行或交付对象> +关联文档：`./<关联文档>.md` + +## <要求分组 1> +- 必须 <可执行、可判断、可验收的要求> +- 不允许 <不可接受的行为或结果> + +## <要求分组 2> +- <要求内容> + +## 边界与异常 +- <边界或异常场景>：<要求结果> + +## 禁止事项 +- 禁止 <明确不允许的行为> + +## 待确认 +- 待确认：<不影响当前主链路但后续需要确认的事项> +```` + ## 模板选择 | 用户表达 | 需求写法 | 使用模板 | @@ -41,23 +199,40 @@ | 多值、多对多、明细、记录、绑定关系 | 独立业务记录或关联关系 | 关联记录 | | 状态、类型、来源、分类、等级等值域 | 业务值域和状态含义 | 值域 | | 唯一、审核、校验、默认值、权限范围 | 业务规则 | 规则 | -| 上传、导入、同步、发布、审核、退款等链路 | 业务流程 | 流程 | -| 列表、详情、筛选、排序、统计、聚合口径 | 展示或统计规则 | 展示统计 | -| 外部系统、第三方平台、跨模块协作 | 集成需求 | 集成 | +| 触发、步骤、链路、流转、时序、分支异常 | 从触发到结果的完整链路 | 流程文档 | +| 要求、交付要求、对接要求、执行要求、验收要求 | 面向执行对象的可验收约束 | 要求文档 | +| 展示、查询、筛选、排序、统计、聚合口径 | 展示或统计规则 | 展示统计 | +| 跨角色、跨系统或跨模块协作 | 协作或集成需求 | 集成 | + +## 方案分层写法 + +| 用户表达 | 写入位置 | 写法 | +|:---|:---|:---| +| 定义何时开始、何时结束、何时有效或失效 | 主草案 | 写成业务规则、状态生命周期或边界要求 | +| 定义异常归类、失败结果、恢复条件、补偿结果 | 主草案 | 写成分支异常、失败结果或验收口径 | +| 提出响应时限、峰值压力、可用性、一致性目标 | 主草案 | 写成业务约束和验收要求 | +| 提出 Redis、MQ、缓存、索引、异步任务、部署等做法 | `references/` 或 `decisions.md` | 写成参考来源或决策背景，主草案只保留业务目标 | +| 同一方案同时包含业务判定和实现建议 | 拆分处理 | 业务判定进主草案，实现建议进参考材料，取舍进决策记录 | ## 写法规则 - 生成的需求草案应优先匹配项目已有结构，不强行使用本模板标题。 - 不把正文拆成没有内容的固定分区。 +- 选择流程文档或要求文档时，优先保持短、清楚、规则明确；不强行补齐通用正文骨架的所有章节。 +- 模板占位只代表信息类型，不代表真实业务；不得把占位或示例扩展成未经确认的业务内容。 - 用户说“表、结构体、数据模型、model、字段、列、属性”时，先归一为业务需求；涉及保存或维护的数据，按业务数据对象和数据项表达。 - 不写 SQL、ORM、字段类型、索引、唯一约束、API path 或 request/response schema。 +- 关联协议、关联主流程、关联文档等引用必须使用可迁移写法；同目录用 `./xxx.md`，跨目录用相对当前文档的 `../xxx/yyy.md`，Markdown 路径使用 `/`。 +- 草案包内强依赖材料优先放入 `references/`，并在主草案中用 `./references/.md` 引用。 +- 连接轮次、状态生命周期、重复提交判定、异常恢复条件等业务判定必须写进主草案，但不得绑定具体服务状态、缓存键、队列、任务或代码结构。 +- Redis、MQ、缓存、索引、分库分表、异步任务等非业务方案只能作为参考来源或决策背景，正文需求必须转译成可验收的业务约束。 - 未确认内容写在最相关的需求语境下，标记为 `需补` 或 `待确认`。 ## 需求项模板库 ### 数据对象 -适用场景：用户提出“需要记录 xxx 信息”“维护 xxx 信息”“新增 xxx model”“需要一个 xxx 表”等创建或维护数据承载对象的需求。 +适用场景：用户提出创建、记录、维护或使用某类业务信息的需求。 ````md ## <业务对象>信息 @@ -70,7 +245,7 @@ ### 修改数据对象 -适用场景：用户提出“给 xxx 增加字段”“调整 xxx 属性”“修改 xxx 数据来源”“删除/停用某个数据项”等变更既有数据承载对象的需求。 +适用场景：用户提出调整既有业务对象、业务属性、数据来源或数据项生命周期的需求。 ````md ## <业务对象>信息调整 @@ -98,7 +273,7 @@ ### 值域 -适用场景：用户提出状态、类型、来源、分类、等级、模式等值域需求。 +适用场景：用户提出用于分类、阶段、来源、等级或模式判断的值域需求。 ````md ## <业务值域> @@ -110,7 +285,7 @@ ### 规则 -适用场景：用户提出唯一、审核、校验、默认值、权限范围、状态流转等规则，不一定新增数据承载对象。 +适用场景：用户提出约束、校验、默认规则、权限范围或状态流转规则，不一定新增数据承载对象。 ````md ## <业务规则> @@ -123,7 +298,7 @@ ### 流程 -适用场景：用户提出上传、导入、同步、发布、审核、退款、重建等有触发、处理、结果的链路需求。 +适用场景：用户提出有触发、处理、结果、分支或异常的链路需求。 ````md ## <业务流程> @@ -138,7 +313,7 @@ ### 展示统计 -适用场景：用户提出列表展示、详情展示、筛选、排序、统计、聚合口径等查询侧需求。 +适用场景：用户提出展示、查询、筛选、排序、统计或聚合口径需求。 ````md ## <展示或统计规则> @@ -152,7 +327,7 @@ ### 集成 -适用场景：用户提出外部系统、第三方平台、跨模块协作、消息通知、数据同步等集成需求。 +适用场景：用户提出跨角色、跨系统、跨模块或跨组织协作需求。 ````md ## <集成需求>