--- name: "ads-prd" description: "根据自然语言功能描述创建或更新功能规格说明书。" agent_created: true argument-hint: "描述你想要生成 spec 的功能" compatibility: "需要 adspecs 项目结构及 docs/ 目录" metadata: author: "Qingwen Chen" user-invocable: true disable-model-invocation: false --- ## 用户输入 ```text $ARGUMENTS ``` **必须** 在继续之前考虑用户输入（如果非空）。 ## 路径配置加载 在开始执行之前，先确定输出目录： 1. 检查项目根目录是否存在 `.adspecs/paths.json` 2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键 3. 如果不存在或配置键缺失，使用下方表格中的默认值 | 配置键 | 默认值 | 用途 | | --------- | ------------- | ----------------------------- | | `prd_dir` | `docs/20-prd` | PRD（产品需求说明书）输出目录 | 将解析后的路径记为 `PRD_DIR`，后续步骤中引用此变量而非硬编码路径。 ## 执行前检查 **检查扩展钩子（编写规格说明前）**: - 检查项目根目录是否存在 `.adspecs/extensions.yml`。 - 如果存在，读取它并查找 `hooks.before_adspecs` 下的条目。 - 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。 - 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。 - 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式： - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。 - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。 - 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/ads-git-commit`。 - 对于每个可执行钩子，根据其 `optional` 标志输出以下内容： - **可选钩子** (`optional: true`): ``` ## 扩展钩子 **可选前置钩子**: {extension} 命令: `/{command}` 描述: {description} 提示: {prompt} 执行: `/{command}` ``` - **必选钩子** (`optional: false`): ``` ## 扩展钩子 **自动前置钩子**: {extension} 执行: `/{command}` EXECUTE_COMMAND: {command} 等待钩子命令结果后再继续执行 Outline。 ``` - 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。 ## 概述 用户在触发消息中 `/ads-prd` 之后输入的文本**就是**功能描述。假设你在本次对话中始终可以获取到它，即使 `$ARGUMENTS` 字面上出现在下方。除非用户提供了空命令，否则不要要求用户重复输入。 根据功能描述，执行以下操作： 1. **生成简洁的短名称**（2-4 个词）用于功能： - 分析功能描述并提取最有意义的关键词 - 创建一个 2-4 个词的短名称，抓住功能的本质 - 尽可能使用动词-名词格式（如 "add-user-auth"、"fix-payment-bug"） - 保留技术术语和缩写（OAuth2、API、JWT 等） - 保持简洁但足够描述性，以便一眼就能理解功能 - 示例： - "我想添加用户认证" → "user-auth" - "为 API 实现 OAuth2 集成" → "oauth2-api-integration" - "为分析功能创建仪表盘" → "analytics-dashboard" - "修复支付处理超时 bug" → "fix-payment-timeout" 2. **识别二级模块**： - 扫描 `{ARCH_DIR}/` 目录，查找 `01-*_business_scenarios.md` 或 `01-*_business_architecture.md` 文件（业务功能架构文档，两者命名均可能出现） - 如果找到，读取文件内容，重点关注： - **二、系统模块总览** → **2.2 子模块清单**：获取所有主模块（P00~P{N}）及其下属的二级模块（子模块，编号格式如 P03-01、P03-02、SYS-01 等) - **三、各模块业务场景详述**：获取每个模块的业务场景描述（S-P{XX}-{YY} 系列） - 将需求描述内容与各二级模块的名称、说明、业务场景进行语义匹配，确定需求最匹配的**二级模块编号**（如 P03-02） - 匹配规则： 1. **精确匹配**：需求描述中明确提到某个子模块名称或编号 → 直接采用 2. **场景匹配**：需求描述的业务场景与某个模块下的场景（S-P{XX}-{YY}）高度吻合 → 采用该子模块编号 3. **语义匹配**：需求描述的核心功能与某个子模块的"说明"字段语义相近 → 采用该子模块编号 4. **无法匹配**：需求内容与任何二级模块都不匹配 → 使用 AskUserQuestion 让用户从二级模块列表中选择，或标记为"新模块" - 将匹配到的二级模块编号记为 `MODULE_ID`（如 `P03-02`），对应的主模块编号记为 `PARENT_MODULE`（如 `P03`) - 如果架构文档不存在，跳过此步骤，`MODULE_ID` 留空，输出目录不包含模块子目录 3. **创建分支**（可选，通过钩子）： 如果上述执行前检查中的 `before_adspecs` 钩子运行成功，它将已创建/切换到 git 分支并输出包含 `BRANCH_NAME` 和 `FEATURE_NUM` 的 JSON。记录这些值以供参考，但分支名称**不**决定 spec 目录名称。 如果用户明确提供了 `GIT_BRANCH_NAME`，将其传递给钩子，以便分支脚本使用该确切值作为分支名称（绕过所有前缀/后缀生成）。 4. **创建 spec 功能目录**: Spec 默认存储在 `{PRD_DIR}` 目录下，除非用户明确提供了 `ADSPECS_FEATURE_DIRECTORY`。 **`ADSPECS_FEATURE_DIRECTORY` 的解析顺序**: 1. 如果用户明确提供了 `ADSPECS_FEATURE_DIRECTORY`（例如通过环境变量、参数或配置），直接使用它 2. 否则，在 `docs/` 下自动生成： - 将 `.adspecs/templates/02-产品需求说明书模板.md` 复制到 `$ADSPECS_FEATURE_DIRECTORY/产品需求说明书.md` 作为起点 - 设置 `SPEC_FILE` 为 `$ADSPECS_FEATURE_DIRECTORY/产品需求说明书.md` - 输出根目录：`{PRD_DIR}/`（由路径配置加载阶段解析，默认 `docs/20-prd/`） - 如果 `MODULE_ID` 已识别（非空）： - 输出子目录：`{PRD_DIR}/{MODULE_ID}/`（如 `docs/20-prd/M03-02/`） - 如果子目录不存在，自动创建 - 如果 `MODULE_ID` 为空（架构文档不存在或无法匹配）： - 直接使用 `{PRD_DIR}/-` 作为输出目录（例如 `003-user-auth` 或 `20260319-143022-user-auth`） - 输出文件名：基于需求描述生成简洁名称，格式 `{MODULE_ID}_{short-name}_产品需求说明书.md` - 完整输出路径示例： - 有模块：`docs/20-prd/M03-02/{MODULE_ID}_{short-name}_产品需求说明书.md` - 无模块：`docs/20-prd/{short-name}_产品需求说明书.md` - 如果目录下已有同名文件，询问用户是覆盖还是重命名,还是新增版本号格式如下： - 有模块：`docs/20-prd/M03-02/{MODULE_ID}_{short-name}_产品需求说明书_v{version}.md` - 无模块：`docs/20-prd/{short-name}_产品需求说明书_v{version}.md` - 将解析后的路径持久化到 `.adspecs/feature.json`（多功能注册表格式）： ```json { "active": "", "prd": [ { "id": "<功能ID>", "directory": "", "filename": "", "name": "<功能名称>", "status": "drafting", "created": "" } ] } ``` **操作方式**: 1. 读取现有的 `.adspecs/feature.json`（如存在） 2. 将新功能追加到 `prd` 数组（若 directory 已存在则跳过，避免重复） 3. 将 `active` 更新为当前功能目录 4. 写入文件（使用 2-space 缩进以保证可读性） 写入实际的解析后目录路径值（例如 `{PRD_DIR}/003-user-auth`），而非字面字符串 `ADSPECS_FEATURE_DIRECTORY`。 这允许下游命令（`/ads-plan`、`/ads-clarify` 等）通过 `active` 字段定位当前功能目录，而无需依赖 git 分支名称约定。 **注意**: 不要在功能目录下创建 `feature.json` 文件——所有功能追踪统一在 `.adspecs/feature.json` 中管理。 **重要**: - 每次 `/ads-prd` 调用只能创建一个功能 - spec 目录名称和 git 分支名称是相互独立的 — 它们可能相同但由用户选择 - spec 目录和文件始终由此命令创建，而非由钩子创建 5. 加载 `.adspecs/templates/02-产品需求说明书模板.md` 并**完整读取**：模板全文是章节骨架、ID 体系与填写格式的唯一权威（速查见下方「模板结构与编写约定」）。若模板文件不存在，仍按「模板结构与编写约定」的 12 部分结构生成，并在完成报告中注明模板缺失。 6. 遵循以下执行流程： 1. 从参数中解析用户描述 如果为空：错误 "No feature description provided" 2. 提取描述中的关键概念 识别：角色、业务对象、操作、数据、约束 3. 对于不明确的方面： - 基于上下文和行业标准做出合理的推断 - 仅在以下情况标记为 [NEEDS CLARIFICATION: 具体问题]： - 该选择显著影响功能范围或用户体验 - 存在多种合理的解释且含义不同 - 没有合理的默认值 - §5 业务对象的父子/引用关系"删除或作废时如何处理"无明确业务依据（禁止自行推断） - **限制：最多 3 个 [NEEDS CLARIFICATION] 标记** - 按影响排序澄清优先级：范围 > 安全/隐私 > 用户体验 > 技术细节 4. 按模板第 2 部分组织用户故事与验收场景： - 每个用户故事含唯一编号 `US-{n}`、优先级（P1 最高，按用户旅程重要性排序）、故事描述（作为[角色]，我想要[功能]，以便于[价值]）、为何赋予此优先级、独立测试说明、前置/后置条件 - 每个故事必须可独立开发/测试/部署/演示（即使只实现它，也应构成有价值的最小可用产品） - 验收场景拆分为独立单行条目并编号 `US-{n}-AC{n}`，格式：**[场景标题]**: **Given** [初始状态]，**When** [操作]，**Then** [预期结果] 如果没有清晰的用户流程：错误 "Cannot determine user scenarios" 5. 生成功能需求（内容落入模板第 3~4 部分：业务场景及流程、功能描述） 每个需求必须是可测试的 对未明确的细节使用合理的默认值（在假设部分记录假设） 按模块拆分，每个模块包含：触发条件、展示内容、操作规则、系统反馈。避免‘便捷、智能’等抽象词。涉及字段时列出名称、含义、来源 6. 定义成功标准（落入模板第 7 部分验收标准：不设独立 ID，通过"关联用户故事/关联业务规则"归约到 `US-{n}`/`BR-{n}`） 按功能模块生成可验证的验收标准。格式：场景/操作/预期结果。覆盖正常、异常、权限、边界情况。 创建可度量、与技术无关的成果 包括量化指标（时间、性能、容量）和定性测量（用户满意度、任务完成率） 每个标准必须可在不知道实现细节的情况下验证 7. 识别关键实体（如果涉及数据）并整理为模板第 5 部分业务对象说明： 先按单据类/聚合子/主数据/枚举类分类标注，再按 OBJ 结构（§5.1）或枚举结构（§5.2）输出业务属性、关联对象与参照完整性约束 8. 状态流转（待处理、处理中、已完成等）必须清晰列出进入/离开条件、触发人、前端展示、通知机制等——对应模板 §3.4 状态机（状态图 + 状态转换规则矩阵 + 状态说明表）与 §4.3 后置状态变更 9. 异常处理表类似：异常场景、触发条件、用户可见内容、系统处理方式、重试机制、数据保存策略等——对应 §4.3 异常处理；本期无法闭环的事项转入第 11 部分风险清单 `R-{n}` 与待确认问题清单 `Q-{n}` 10. 返回：成功（spec 可进入计划阶段） 7. 使用模板结构将规格说明书写入 `SPEC_FILE`，用从功能描述（参数）派生的具体细节替换占位符，同时保留章节顺序和标题。 8. **规格说明书质量验证**: 在编写初始 spec 后，根据质量标准对其进行验证： a. **创建 Spec 质量检查清单**: 在 `ADSPECS_FEATURE_DIRECTORY/checklists/prd_checklist.md` 生成检查清单文件，使用检查清单模板结构，包含以下验证项： ```markdown # 规格说明书质量检查清单：[功能名称] **目的**: 在进入计划阶段之前验证规格说明书的完整性和质量 **创建日期**: [DATE] **功能**: [链接到 spec.md] ## 内容质量 - [ ] 无实现细节（语言、框架、API） - [ ] 聚焦于用户价值和业务需求 - [ ] 为非技术利益相关者编写 - [ ] 所有必填章节已完成 ## 需求完整性 **通用项** - [ ] 无 [NEEDS CLARIFICATION] 标记残留 - [ ] 需求可测试且无歧义 - [ ] 范围界限清晰（§1.3 不包含项逐条列出并标注归属模块） - [ ] 依赖和假设已识别 - [ ] 异常和边界情况已识别且穷举主要情况 - [ ] 功能描述具体到研发可直接实现 - [ ] 一级/二级模块名称和编号与架构文档（`01-*_business_architecture.md` / `01-*_business_scenarios.md`）§2.1 模块清单、§2.2 子模块清单一致 - [ ] 二级菜单/模块划分合理性检查 **用户故事与验收（§2、§7）** - [ ] 用户故事含 `US-{n}` 编号、优先级（P1 最高）与独立测试说明 - [ ] 验收场景拆为独立单行 Given-When-Then 条目并编号 `US-{n}-AC{n}` - [ ] 验收标准可验证、可度量且与技术无关（§7 不设独立 ID，归约到 `US-{n}`/`BR-{n}`） **场景与流程（对应 M4，§3）** - [ ] 每个端到端流程都有完整的流程说明（流程目标/参与角色/步骤表）并配套 Mermaid 流程图 - [ ] 流程步骤之间的每一处衔接均明确标注"同步等待"或"异步触发"（衔接类型强制必填） - [ ] 对文档中出现的每一个核心单据，均显式回答"是否需要审批"（明确回答"不需要"同样须显式记录，禁止留空） - [ ] 每个审批流都有完整的审批节点、通过/驳回后的状态流转说明，并配套 Mermaid 流程图 - [ ] 状态流转完整（进入/离开条件、触发人、展示/通知机制；§3.4 状态机含状态图 + 转换规则矩阵 + 状态说明表） **业务功能（对应 M2、M3，§4.3）** - [ ] 每个业务功能均明确操作角色、主操作对象、引用的关联对象 - [ ] 每个业务功能均说明了前置条件 - [ ] 每个业务功能均明确区分"后置状态变更"与"下游触发"两个独立字段（下游触发注明衔接类型与所在流程） - [ ] 每个业务功能引用的业务规则，均有独立的规则条目定义（§3.2 `BR-{n}`），而非仅在文字中提及 - [ ] 业务规则均标注规则类型（校验类/计算类/推导类/转换类），编号写在规则标题后括号内 - [ ] 同一条业务规则被多个功能引用时，已合并为同一 `BR-{n}` 并列出全部引用方 - [ ] 输入/输出数据、特殊处理、异常处理等 §4.3 其余字段完整 **业务对象（对应 M1，§5）** - [ ] 全部业务对象已做单据类/聚合子对象/主数据/枚举类的分类标注并赋 `OBJ-{业务域缩写}-{三位序号}` - [ ] 每个对象的业务属性均说明了类型、长度/精度、是否必填、是否唯一、引用对象 - [ ] 每一对存在父子或引用关系的对象，均明确回答"父对象删除/作废时子对象如何处理"（级联处理或独立保留二选一，不允许遗漏或 AI 推断） **岗位角色（对应 M5，§1.4、§6）** - [ ] 已列出业务涉及的全部岗位角色 - [ ] 每个角色的功能权限完整列出（§6.1 权限矩阵） - [ ] 对每一个查询/列表类功能，在每个相关角色下均明确填写了数据范围说明（§6.2 数据权限；无限制也需显式写明） **全局** - [ ] §11.2 待确认问题清单中不存在"待确认"状态的条目 - [ ] 风险与待确认项已以 `R-{n}`/`Q-{n}` 表列出（§11） - [ ] 文档中未出现任何 UI/UE 交互层面的描述（页面布局、控件、点击路径等；UI/交互规格由 /ads-front-spec 承接） ## 功能就绪 - [ ] 所有功能需求有清晰的验收标准 - [ ] 用户场景覆盖流程完整 - [ ] 功能满足成功标准中定义的可度量成果 - [ ] 无实现细节泄露到规格说明书中 ## 备注 - 标记为不完整的项需要在 `/ads-clarify` 或 `/ads-plan` 之前更新 spec ``` b. **运行验证检查**: 对照每个检查清单项审查 spec： - 对于每一项，确定其通过或失败 - 记录发现的具体问题（引用相关 spec 章节） c. **处理验证结果**: - **如果所有项通过**: 将检查清单标记为完成，并继续必选执行后钩子部分 - **如果有项失败（不包含 [NEEDS CLARIFICATION]）**: 1. 列出失败的项和具体问题 2. 更新 spec 以处理每个问题 3. 重新运行验证直到所有项通过（最多 3 次迭代） 4. 如果 3 次迭代后仍然失败，在检查清单备注中记录剩余问题并警告用户 - **如果 [NEEDS CLARIFICATION] 标记残留**: 1. 从 spec 中提取所有 [NEEDS CLARIFICATION: ...] 标记 2. **限制检查**: 如果超过 3 个标记，仅保留 3 个最关键的问题（按范围/安全/UX 影响），对其余做出合理推断 3. 对于每个需要澄清的问题（最多 3 个），以此格式向用户呈现选项： ```markdown ## 问题 [N]：[主题] **上下文**: [引用相关 spec 章节] **需要明确的内容**: [NEEDS CLARIFICATION 标记中的具体问题] **建议答案**: | 选项 | 答案 | 含义 | | ------ | ---------------- | ------------------------ | | A | [第一个建议答案] | [这对功能意味着什么] | | B | [第二个建议答案] | [这对功能意味着什么] | | C | [第三个建议答案] | [这对功能意味着什么] | | 自定义 | 提供你自己的答案 | [说明如何提供自定义输入] | **你的选择**: _[等待用户回复]_ ``` 4. **关键 - 表格格式**: 确保 markdown 表格格式正确： - 使用一致的间距，管道对齐 - 每个单元格的内容周围应有空格：`| 内容 |` 而非 `|内容|` - 标题分隔符必须至少有 3 个破折号：`|--------|` - 测试表格在 markdown 预览中是否正确渲染 5. 按顺序编号问题（Q1、Q2、Q3 - 最多 3 个） 6. 在等待回复之前一起呈现所有问题 7. 等待用户对所有问题的选择回复（例如："Q1: A, Q2: 自定义 - [详情], Q3: B"） 8. 将 spec 中的每个 [NEEDS CLARIFICATION] 标记替换为用户选择或提供的答案来更新 spec 9. 在所有澄清解决后重新运行验证 d. **更新检查清单**: 在每次验证迭代后，以当前的通过/失败状态更新检查清单文件 ## 模板结构与编写约定 模板 v2.3（`02-产品需求说明书模板.md`）是 `SPEC_FILE` 章节骨架的唯一权威：**12 个部分、固定顺序、标题层级照抄**，将各部分占位符替换为本次需求的真实内容。逐部分产出要点： | 部分 | 标题 | 产出要点 | 可选性 | | ---- | ---- | -------- | ------ | | 第1部分 | 需求概览 | 文档头（版本/创建日期/修订日期/所属模块/数据标准）＋基本信息/背景/范围（"不包含"项须标注归属模块）/涉及角色 | 必填 | | 第2部分 | 用户故事 | `US-{n}` 故事（优先级排序、独立测试、前置/后置条件）＋单行 Given-When-Then 验收场景 `US-{n}-AC{n}` | 必填 | | 第3部分 | 业务场景及流程 | §3.1 端到端流程（目标/参与角色/步骤表/流程图）＋审批流；§3.2 业务规则；§3.3 业务数据；§3.4 状态机 | 必填（§3.4 仅在存在状态流转时） | | 第4部分 | 功能描述 | §4.1 功能清单 `P{模块}-{子模块}-{序号}`、§4.2 结构树（ASCII）、§4.3 每个功能详细说明 | 必填 | | 第5部分 | 业务对象说明 | 对象分类＋`OBJ-{业务域缩写}-{三位序号}` 结构（§5.1）/枚举结构（§5.2） | 涉及数据时必填 | | 第6部分 | 权限要求 | §6.1 功能权限（每行对应 `PERM-{n}`）、§6.2 数据权限（隔离维度/角色数据范围） | 必填 | | 第7部分 | 验收标准 | 归约到 `US-{n}`/`BR-{n}`，无独立 ID；§7.2 非功能验收；§7.3 已知问题或限制 | 必填 | | 第8部分 | 参考资料 | 相关文档/相关功能/外部依赖（含异常策略表）/备注 | 按需 | | 第9部分 | 术语表 | 核心业务术语（术语/英文/定义/备注） | 按需 | | 第10部分 | 假设与约束 | 需求假设/业务约束/技术约束 | 必填 | | 第11部分 | 风险与待确认问题 | `R-{n}` 风险清单、`Q-{n}` 待确认问题清单（关联章节/确认方/状态闭环） | 必填 | | 第12部分 | 变更记录 | 追加一行（版本/日期/变更人/变更内容），版本号递增 | 必填 | ### 编号约定（以模板「全链路 ID 体系约定」表为准） - **PRD 编写阶段由 AI 自动赋予**：`US-{n}`、`US-{n}-AC{n}`、`PROC-{业务域缩写}-{三位序号}`、`BR-{n}`、`OBJ-{业务域缩写}-{三位序号}`；业务域缩写由需求内容确定，在 PROC/OBJ 间保持一致。 - `BR-{n}` 写在规则标题后括号内，如 `规则1: 到货必检制度 (BR-01)`；§4.3 各功能通过"涉及的业务规则"引用已赋编号。 - `FUNC-{n}`（§4.1 三级编号深度优先映射）与 `PERM-{n}`（权限矩阵每行）由**需求分析阶段**映射/赋予——PRD 编写阶段不预设这两种编号。 - 功能编号 `P{模块}-{子模块}-{序号}`：一级/二级模块名称与编号必须与 `docs/10-architecture/` 下 `01-*_business_architecture.md`（或 `01-*_business_scenarios.md`）§2.1 模块清单、§2.2 子模块清单**严格一致**（如 P05 仓储物流管理 → P05-01 原辅材料仓库）；无法归入清单模块时向用户确认或标注新模块。 - 模板正文示例中的编号（如 FUNC-CON-001、RULE-CON-001）仅为演示占位，实际取值以上述 ID 体系约定为准。 ### 强制条款（模板中带"必须/不允许"语义的约束） 1. 所有流程图一律 **Mermaid 源代码**输出（顺序/分支用 `flowchart TD`、审批流配合菱形判断节点、跨角色时序可选 `sequenceDiagram`），禁止图片或其他绘图工具格式。 2. §3.1 每个端到端业务流程必须包含：流程目标、流程参与角色、流程步骤表（步骤/步骤描述/引用的业务功能/衔接类型/分支条件）＋ Mermaid 流程图。 3. 步骤表"衔接类型"为**强制必填项**，取值仅两种：**同步等待**（结果直接驱动下一步，失败则流程在此中断）／**异步触发**（完成后产生业务事件，允许延迟响应，失败不影响已达成结果）——它直接决定下游 ME 事件建模，撰写和自查时必须重点检查。 4. §3.1 每个核心业务单据必须显式回答"是否需要人工审批"：需要→按审批流结构输出（适用单据/触发条件/审批节点表/流程图）；不需要→**显式记录**如 `OBJ-CON-001 合同：无需审批，录入后直接生效`，**禁止留空**（留空视为信息缺失而非"无审批"的确认结果）。 5. §3.2 业务规则必须标注**规则类型**（校验类/计算类/推导类/转换类），填写校验失败提示、适用场景与示例；同一条规则被多个业务功能引用时必须识别为同一条、合并为单一 BR 编号并列出全部引用方（规则复用强制检查），不允许重复定义。 6. §5 撰写前先对全部业务对象做**分类标注**（单据类/聚合子/主数据/枚举类）；枚举类按 §5.2 取值列表输出，其余按 §5.1 结构输出（对象分类/说明/生命周期状态/业务属性表/关联的聚合子对象/关联的其他业务对象/参照完整性约束），属性引用列使用 OBJ 编号。 7. §5 **关联关系强制确认**：对任何存在父子或引用关系的业务对象，必须回答"父对象删除或作废时如何处理"，答案仅两种——**级联处理**（组合关系）／**独立保留**（聚合关系）。此决策不能由 AI 从名称或描述自行推断（不同企业的答案可能相反）；没有明确业务依据时计入 [NEEDS CLARIFICATION] 向用户确认，**不允许留空**。 8. §4.3 每个功能详细说明必填：操作角色、主操作对象、引用的关联对象、前置条件、功能描述、用户操作流程、输入/输出数据、涉及的业务规则、后置状态变更、下游触发（注明衔接类型与所在流程）、特殊处理、异常处理。 9. §7 验收标准不设独立 ID，每条通过"关联用户故事/关联业务规则"归约到 `US-{n}`/`BR-{n}`；§7.2 非功能验收标准（性能/安全/兼容/可用）给出量化指标。 10. §11 风险编号 `R-{n}`、问题编号 `Q-{n}` 在章节内递增，不与其它章节 ID 冲突；状态流转：开放 → 已缓解/已确认 → 已关闭。 > 各部分的表格结构、字段细节与填写示例以模板原文为准——生成时必须完整加载模板；本节仅用于编写与质量自查时的快速对照。 ## 必选执行后钩子 **必须在向用户报告完成之前完成本节。** 检查项目根目录是否存在 `.adspecs/extensions.yml`。 - 如果不存在，或 `hooks.after_adspecs` 下没有注册钩子，跳到完成报告。 - 如果存在，读取它并查找 `hooks.after_adspecs` 下的条目。 - 如果 YAML 无法解析或无效，静默跳过钩子检查并继续完成报告。 - 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。 - 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式： - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。 - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。 - 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/ads-git-commit`。 - 对于每个可执行钩子，根据其 `optional` 标志输出以下内容： - **必选钩子** (`optional: false`) — **必须为每个必选钩子发出 `EXECUTE_COMMAND:`**： ``` ## 扩展钩子 **自动钩子**: {extension} 执行: `/{command}` EXECUTE_COMMAND: {command} ``` - **可选钩子** (`optional: true`): ``` ## 扩展钩子 **可选钩子**: {extension} 命令: `/{command}` 描述: {description} 提示: {prompt} 执行: `/{command}` ``` ## 完成报告 向用户报告完成情况，包含： - `ADSPECS_FEATURE_DIRECTORY` — 功能目录路径 - `SPEC_FILE` — spec 文件路径 - 检查清单结果摘要 - 是否准备好进入下一阶段（`/ads-clarify` 或 `/ads-plan`） **注意:** 分支创建由 `before_adspecs` 钩子（git 扩展）处理。Spec 目录和文件创建始终由此核心命令处理。 ## 快速指南 - 聚焦于用户需要**什么**以及**为什么**。 - 避免描述如何实现（无技术栈、API、代码结构）。 - 为业务利益相关者编写，而非为开发者。 - 不要创建嵌入在 spec 中的任何检查清单。那将由单独的命令完成。 ### 章节要求 - **章节骨架**: 模板 v2.3 的第 1~12 部分为固定骨架；`SPEC_FILE` 保持各部分标题与顺序不变（对照「模板结构与编写约定」），仅替换占位符内容 - **必填章节**: 每个功能必须完成 - **可选章节**: 仅在与功能相关时包含（如 §3.4 状态机仅在存在状态流转时填写） - 当某个章节不适用时，完全删除它（不要留下 "N/A"） ### AI 生成指南 从用户提示创建此 spec 时： 1. **做出合理推断**: 使用上下文、行业标准和常见模式来填补空白 2. **记录假设**: 在假设部分记录合理的默认值 3. **限制澄清标记**: 最多 3 个 [NEEDS CLARIFICATION] 标记 - 仅用于以下关键决策： - 显著影响功能范围或用户体验 - 存在多种合理的解释且含义不同 - 缺乏任何合理的默认值 4. **按影响排序澄清优先级**: 范围 > 安全/隐私 > 用户体验 > 技术细节 5. **像测试人员一样思考**: 每个模糊的需求都应该不通过"可测试且无歧义"的检查清单项 6. **需要澄清的常见领域**（仅当没有合理默认值时）: - 功能范围和边界（包含/排除特定用例） - 用户类型和权限（如果存在多种冲突的解释可能性） - 安全/合规要求（当法律/财务影响显著时） **合理默认值示例**（不要询问以下内容）: - 数据保留：该领域的行业标准实践 - 性能目标：除非有说明，否则为标准 Web/移动应用期望值 - 错误处理：用户友好的消息及适当的回退处理 - 认证方式：Web 应用的标准基于会话或 OAuth2 - 集成模式：使用项目合适的模式（Web 服务用 REST/GraphQL，库用函数调用，工具用 CLI 参数等） ### 成功标准指南 成功标准必须： 1. **可度量**: 包含具体的指标（时间、百分比、数量、比率） 2. **技术无关**: 不提及框架、语言、数据库或工具 3. **以用户为中心**: 从用户/业务角度描述成果，而非系统内部 4. **可验证**: 无需知道实现细节即可测试/验证 **好的示例**: - "用户可以在 3 分钟内完成结账" - "系统支持 10,000 个并发用户" - "95% 的搜索在 1 秒内返回结果" - "任务完成率提升 40%" **不好的示例**（聚焦于实现）: - "API 响应时间低于 200ms"（太技术化，用"用户能瞬间看到结果"替代） - "数据库可处理 1000 TPS"（实现细节，用面向用户的指标替代） - "React 组件渲染高效"（框架特定） - "Redis 缓存命中率高于 80%"（技术特定） ## 完成标志 - [ ] 规格说明书已写入 `SPEC_FILE` 并对照质量检查清单验证通过 - [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过 - [ ] 完成报告已呈现给用户，包含功能目录、spec 文件路径和检查清单结果