6aspec 2.0.0-dev.9 → 3.0.0-dev.1

package/.6aspec/rules/brown/brown_specs_sop.md

@@ -1,228 +1,472 @@
 # 棕地需求 - Specs SOP
 
-Phase 1.5: 需求规格定义
+需求规格定义
 
 **输入**：`/6aspec:brown:specs` 后可选需求名称。
 
-**适用流程**：标准级、完整级
+**适用流程**：轻量级、标准级、完整级
 
 **步骤**
 
 1. **选择需求并检查状态**
 
    - 读取 `6aspecdoc/brown/<name>/status.json`
-   - 确认 `phases.understand` 为 "done"
-   - 如果未完成 Phase 1，提示先运行 `/6aspec:brown:understand`
-   - 确认流程深度为 "standard" 或 "complete"
-   - 如果是 "lightweight"，提示应该使用 `/6aspec:brown:proposal`
+   - 根据 `flowDepth` 检查前置阶段：
+     - **轻量级**：确认 `phases.proposal` 为 "done"，如果未完成提示先运行 `/6aspec:brown:proposal`
+     - **标准级/完整级**：确认 `phases.analyze` 为 "done"，如果未完成提示先运行 `/6aspec:brown:analyze`
 
 2. **读取前置文档**
 
-   - `6aspecdoc/brown/<name>/requirement.md`
-   - `6aspecdoc/brown/<name>/artifacts/01-understanding.md`
+   根据 `flowDepth` 读取不同的前置文档：
 
-3. **读取问题答案**
+   **轻量级流程**：
+   - `6aspecdoc/brown/<name>/artifacts/proposal.md`
+   - `6aspecdoc/brown/<name>/explore-summary.md` - 探索摘要（如果存在）
 
-   从 understanding.md 中读取"待明确问题清单"及用户的答案：
+   **标准级/完整级流程**：
+   - `6aspecdoc/brown/<name>/artifacts/proposal.md`
+   - `6aspecdoc/brown/<name>/artifacts/analysis.md`
 
-   - 检查问题清单中哪些问题已经有答案（标记为具体值而非"[待确认]"）
-   - 如果有未回答的问题，提示用户这些问题需要明确，但不阻塞 specs 阶段
-   - 基于已有的答案和现状分析，开始定义需求规格
+3. **读取问题答案（仅标准级/完整级）**
 
-   注意：specs 阶段不再提出新问题，所有需求问题应该在 understand 阶段提出并收集。
+   如果是标准级或完整级流程，从 analysis.md 中读取"澄清结果"及影响面分析：
 
-4. **定义功能需求**
+   - 检查澄清结果中哪些问题已经有答案
+   - 如果有未澄清的问题，提示用户这些问题需要明确，但不阻塞 specs 阶段
+   - 基于已有的澄清结果和现有系统分析，开始定义需求规格
 
-   基于需求理解和问题答案，明确定义系统应该具备的能力：
+   注意：specs 阶段不再提出新问题，所有需求问题应该在 analyze 阶段提出并收集。
 
-   **功能需求格式**：
-   - FR-001: <功能描述>
-     - 输入：<输入内容>
-     - 输出：<输出内容>
-     - 业务规则：<业务规则>
-     - 验收标准：<验收标准>
+4. **按需探索代码库（可选）**
 
-   **拆解原则**：
-   - 每个功能需求应该是独立的、可验证的
+   **触发条件**：
+   - 需要了解现有字段定义、验证逻辑、Scenario实现方式
+   - 需要了解现有的非功能需求实现（如权限控制、性能优化）
+   - 用户明确要求探索（例如："先了解一下现有实现"）
+   - 信息不足，需要参考现有代码才能定义准确的需求规格
+
+   **探索方式**：
+
+   a. **简单搜索**（使用 Grep/Glob 工具）：
+
+   - 搜索相关 Entity 类的字段定义：pattern = `private.*<字段名>`，type = `java`，glob = `*Entity.java`
+   - 搜索相关验证注解：pattern = `@NotNull|@NotEmpty|@Valid`，type = `java`，glob = `*Entity.java`
+   - 搜索现有的测试场景：pattern = `test.*<功能名>`，type = `java`，glob = `*Test.java`
+
+   b. **复杂探索**（使用Task工具调用Explore agent）：
+   - 当需要深入理解现有架构模式时
+   - 当需要跨多个文件理解业务逻辑时
+
+   **探索结果处理**：
+   - 探索发现直接用于需求规格定义
+   - 不生成独立文档
+   - 在specs.md中可以标注"基于现有实现：<文件路径>"
+
+   **注意**：
+   - 探索是可选的，不是强制的
+   - 如果前置文档（proposal、understanding、impact）已经提供了足够信息，可以跳过探索
+   - 探索应该聚焦、快速，避免过度探索
+
+5. **明确 Key Entities 和 Business Rules**
+
+   在定义功能需求之前，先从前置文档中识别业务对象和业务规则，作为后续需求定义的"词汇表"和"约束基础"。
+
+   **Key Entities（关键业务对象）**：
+   - 识别本次需求涉及的核心业务对象（不是数据库表，是业务概念）
+   - 明确每个实体的含义、关键属性口径、状态流转和与其他实体的关系
+   - 避免写数据库字段类型、类名等技术细节
+
+   **Business Rules（业务规则）**：
+   - 识别业务上必须成立的约束/推导规则（与实现无关）
+   - 按 Capability 分类组织，全局规则（跨 Capability）放在"通用规则"分类下
+   - 规则描述格式：条件 → 结果，或直接描述约束
+
+   **Business Rules 组织格式**：
+   ```markdown
+   ### 通用规则
+   - BR-001：<跨 Capability 的全局约束>
+
+   ### Capability: <capability-name>
+   - BR-002：<该能力特有的约束>
+   - BR-003：<该能力特有的约束>
+   ```
+
+   **注意**：
+   - 如果某个 Capability 没有特有规则，不需要单独列出
+   - 如果所有规则都是全局的，只写"通用规则"即可
+   - Business Rules 是业务约束，不是技术约束（技术约束放非功能需求）
+
+6. **基于 Capabilities 定义功能需求**
+
+   从 proposal.md 中读取 Capabilities 列表，按 Capability 组织功能需求：
+
+   **功能需求格式**（按 Capability 组织）：
+   ```markdown
+   ### Capability: <capability-name> [ADD/MODIFY/REMOVE]
+
+   <Capability 描述，说明这个能力是做什么的>
+
+   #### Requirement: <需求名称>
+
+   <需求描述，使用 SHALL/MUST 关键字表示强制性要求>
+
+   ##### 验收标准
+   - AC1: <可观察、可验证的验收点>
+   - AC2: <可观察、可验证的验收点>
+
+   ##### Scenario: <场景名称>
+
+   - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
+   - **GIVEN** <前置条件（业务对象状态/权限/已有数据/开关等）>
+   - **WHEN** <触发动作>
+   - **THEN** <预期结果>
+   - **AND** <额外的预期结果>（可选）
+
+   ##### Scenario: <另一个场景名称>
+
+   - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
+   - **THEN** <预期结果>
+
+   #### Requirement: <另一个需求名称>
+
+   <需求描述>
+
+   ##### 验收标准
+   - AC1: <...>
+
+   ##### Scenario: <场景名称>
+
+   - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
+   - **THEN** <预期结果>
+   ```
+
+   **组织原则**：
+   - 每个 Capability 对应 proposal.md 中的一个能力
+   - 在 Capability 级别标识变更类型：[ADD]（新增）、[MODIFY]（修改）、[REMOVE]（移除）
+   - 每个 Capability 下包含多个 Requirements
+   - 每个 Requirement 应该是独立的、可验证的
+   - 每个 Requirement SHOULD 显式列出验收标准（AC），用于快速评审覆盖面与边界
+   - 每个 Scenario MUST 包含：触发类型 + GIVEN/WHEN/THEN（AND 可选）；触发类型只能从「用户操作｜外部系统触发｜事件订阅｜定时任务」中选择
+   - 使用 SHALL/MUST 关键字表示强制性要求，SHOULD 表示推荐性要求
    - 功能需求应该从用户视角描述（做什么，而不是怎么做）
    - 避免技术实现细节（技术细节放在 design 阶段）
 
-5. **定义非功能需求**
+6. **定义非功能需求（可选）**
+
+   明确系统应该满足的质量标准。**注意：只写有明确要求的项，不要为了完整性而写空泛内容。**
 
-   明确系统应该满足的质量标准：
+   **非功能需求格式**：
+   ```markdown
+   ### 性能需求
+   - 响应时间 SHALL < 200ms
+   - 并发量 SHALL 支持 1000+ QPS
 
-   - NFR-001: 性能需求（响应时间、并发量等）
-   - NFR-002: 安全需求（权限控制、数据加密等）
-   - NFR-003: 可用性需求（易用性、可维护性等）
-   - NFR-004: 兼容性需求（浏览器、数据库等）
+   ### 安全需求
+   - 权限控制：只有管理员 SHALL 可以修改
+   - 数据加密：敏感数据 SHALL 加密存储
 
-6. **定义范围和约束**
+   ### 可用性需求
+   - 易用性：界面 SHOULD 符合团队 UI 规范
+   - 可维护性：代码 SHOULD 遵循现有架构模式
 
-   明确做什么、不做什么：
+   ### 兼容性需求
+   - 浏览器：SHALL 支持 Chrome/Firefox/Safari 最新版本
+   - 数据库：SHALL 兼容现有数据库版本
+   ```
 
-   **范围定义**：
-   - 包含：<明确包含的功能>
-   - 不包含：<明确不包含的功能>
+   **注意事项**：
+   - 使用 SHALL/MUST 表示强制性要求，SHOULD 表示推荐性要求
+   - 如果某个类别（如性能、安全）没有明确要求，可以省略该小节
+   - 避免写"遵循最佳实践"等空泛描述
 
-   **约束条件**：
-   - 技术约束：<技术上的限制>
-   - 业务约束：<业务上的限制>
-   - 时间约束：<时间上的限制>
+7. **定义范围边界（可选）**
 
-7. **定义验收标准**
+   明确做什么、不做什么，以及关键约束：
 
-   明确如何验证需求已经实现：
+   **范围边界格式**：
+   ```markdown
+   ## 1. 范围边界
 
-   - AC-001: <功能验收标准>
-   - AC-002: <非功能验收标准>
-   - AC-003: <数据验收标准>
+   **本次实现**：
+   - <明确包含的核心功能>
+   - <明确包含的核心功能>
+
+   **明确不包含**：
+   - <明确排除的功能或场景>
+   - <明确排除的功能或场景>
+
+   **关键约束**（可选）：
+   - <技术约束：如必须使用某技术栈、兼容某版本>
+   - <业务约束：如必须满足某业务规则>
+   - <时间约束：如必须在某时间前完成>
+   ```
+
+   **注意事项**：
+   - 范围边界用于明确需求边界，避免范围蔓延
+   - "本次实现"应该简洁列出核心功能点
+   - "明确不包含"用于排除容易混淆的功能
+   - "关键约束"只写有实际影响的约束，如果没有可以省略
+   - 如果范围已经很明确（如简单的 bug 修复），整个章节可以省略
 
 8. **创建需求规格文档**
 
-   创建 `6aspecdoc/brown/<name>/artifacts/01.5-specs.md`：
+   注意：Scenario 用于将关键验收路径以结构化方式表达（GIVEN/WHEN/THEN），但验收标准仍应显式列出，便于评审快速检查覆盖面与边界。
+
+   创建 `6aspecdoc/brown/<name>/artifacts/specs.md`：
    ```markdown
-   # Phase 1.5: 需求规格定义
+   # 需求规格定义
 
    > **需求**: <name>
-   > **阶段**: Phase 1.5 - 需求规格
+   > **基于提案**: proposal.md
+   > **流程**: <flowDepth>
+   > **阶段**: Specs
    > **状态**: ✅ 已完成
    > **完成时间**: <timestamp>
 
-   ## 1. 需求概述
+   ## 1. 范围边界
+
+   **本次实现**：
+   - <明确包含的核心功能>
+   - <明确包含的核心功能>
+
+   **明确不包含**：
+   - <明确排除的功能或场景>
+   - <明确排除的功能或场景>
+
+   **关键约束**（可选）：
+   - <技术约束：如必须使用某技术栈、兼容某版本>
+   - <业务约束：如必须满足某业务规则>
+   - <时间约束：如必须在某时间前完成>
+
+   ## 2. Key Entities（关键业务对象）
+
+   > 轻量业务模型：描述业务对象的含义、关键属性口径、状态与关系；避免写数据库表/类/字段类型。
+
+   - **实体**：<实体名称>
+     - **定义**：<一句话定义>
+     - **关键属性**：<属性1口径>；<属性2口径>...
+     - **状态**（可选）：<状态列表>
+     - **关系**（可选）：<与其他实体的业务关系>
+
+   ## 3. Business Rules（业务规则）
 
-   ### 1.1 业务目标
-   <为什么需要这个功能>
+   > 业务上必须成立的约束/推导规则（与实现无关）。按 Capability 分类，跨 Capability 的全局规则放在"通用规则"下。
 
-   ### 1.2 使用场景
-   <谁用、什么时候用、怎么用>
+   ### 通用规则
+   - BR-001：<跨 Capability 的全局约束>
 
-   ### 1.3 范围定义
-   **包含**：
-   - <明确包含的功能>
+   ### Capability: <capability-name>
+   - BR-002：<该能力特有的约束>
 
-   **不包含**：
-   - <明确不包含的功能>
+   ## 4. 功能需求
 
-   ## 2. 功能需求
+   ### Capability: <capability-name> [ADD]
 
-   ### FR-001: <功能名称>
-   **描述**：<功能描述>
+   <Capability 描述，说明这个能力是做什么的>
 
-   **输入**：
-   - <输入内容>
+   #### Requirement: <需求名称>
 
-   **输出**：
-   - <输出内容>
+   <需求描述，使用 SHALL/MUST 关键字表示强制性要求>
 
-   **业务规则**：
-   - <业务规则1>
-   - <业务规则2>
+   ##### 验收标准
+   - AC1: <可观察、可验证的验收点>
+   - AC2: <可观察、可验证的验收点>
 
-   **验收标准**：
-   - <验收标准1>
-   - <验收标准2>
+   ##### Scenario: <场景名称>
 
-   ### FR-002: <功能名称>
-   ...
+   - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
+   - **GIVEN** <前置条件（业务对象状态/权限/已有数据/开关等）>
+   - **WHEN** <触发动作>
+   - **THEN** <预期结果>
+   - **AND** <额外的预期结果>（可选）
 
-   ## 3. 非功能需求
+   ##### Scenario: <另一个场景名称>
 
-   ### 3.1 性能需求
-   - NFR-001: <性能要求>
+   - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
+   - **THEN** <预期结果>
 
-   ### 3.2 安全需求
-   - NFR-002: <安全要求>
+   #### Requirement: <另一个需求名称>
 
-   ### 3.3 可用性需求
-   - NFR-003: <可用性要求>
+   <需求描述>
 
-   ### 3.4 兼容性需求
-   - NFR-004: <兼容性要求>
+   ##### 验收标准
+   - AC1: <...>
 
-   ## 4. 约束条件
+   ##### Scenario: <场景名称>
 
-   ### 4.1 技术约束
-   - <技术上的限制>
+   - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
+   - **THEN** <预期结果>
 
-   ### 4.2 业务约束
-   - <业务上的限制>
+   ### Capability: <another-capability-name> [MODIFY]
 
-   ### 4.3 时间约束
-   - <时间上的限制>
+   <Capability 描述>
 
-   ## 5. 验收标准
+   #### Requirement: <需求名称>
 
-   ### 5.1 功能验收
-   - AC-001: <功能验收标准>
-   - AC-002: <功能验收标准>
+   <需求描述>
 
-   ### 5.2 非功能验收
-   - AC-003: <非功能验收标准>
-   - AC-004: <非功能验收标准>
+   ##### 验收标准
+   - AC1: <...>
 
-   ### 5.3 数据验收
-   - AC-005: <数据验收标准>
+   ##### Scenario: <场景名称>
+
+   - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
+   - **THEN** <预期结果>
+
+   ## 5. 非功能需求
+
+   > **注意**：只写有明确要求的项，如果某个类别没有明确要求，可以省略该小节。
+
+   ### 性能需求
+   - 响应时间 SHALL < <具体值>
+   - 并发量 SHALL 支持 <具体值>
+
+   ### 安全需求
+   - 权限控制：<具体要求>
+   - 数据加密：<具体要求>
+
+   ### 可用性需求
+   - 易用性：<具体要求>
+   - 可维护性：<具体要求>
+
+   ### 兼容性需求
+   - 浏览器：SHALL 支持 <具体版本>
+   - 数据库：SHALL 兼容 <具体版本>
 
    ## 6. 下一步
 
-   运行 `/6aspec:brown:impact` 进行影响面分析。
+   运行 `/6aspec:brown:design` 进行技术方案设计
    ```
 
 9. **更新状态**
 
    更新 `6aspecdoc/brown/<name>/status.json`：
+
+   **轻量级流程**：
    ```json
    {
-     "status": "impact_pending",
+     "status": "design_pending",
+     "flowDepth": "lightweight",
      "phases": {
-       "understand": "done",
+       "proposal": "done",
        "specs": "done",
-       "impact": "pending",
-       ...
+       "design": "pending",
+       "tasks": "blocked",
+       "implement": "blocked"
      },
-     "artifacts": ["01-understanding.md", "01.5-specs.md"]
+     "artifacts": ["proposal.md", "specs.md"]
    }
    ```
 
+   **标准级流程**：
+   ```json
+   {
+     "status": "design_pending",
+     "flowDepth": "standard",
+     "phases": {
+       "analyze": "done",
+       "proposal": "done",
+       "specs": "done",
+       "design": "pending",
+       "tasks": "blocked",
+       "implement": "blocked"
+     },
+     "artifacts": ["analysis.md", "proposal.md", "specs.md"]
+   }
+   ```
+
+   同时更新 `6aspecdoc/brown/<name>/requirement.md`：
+   - 更新"状态"字段为 `📋 Design 待开始`
+   - 更新"最后修改"时间戳为 `<timestamp>`
+   - 更新"当前阶段"为 `Specs - 需求规格定义（已完成）`
+   - 更新"下一步操作"为 `运行 /6aspec:brown:design 继续下一阶段`
+   - 在"进度概览"中标记 Specs 阶段为已完成 `[x]`
+
 **输出**
 
+根据 `flowDepth` 显示不同的输出信息：
+
+**轻量级流程**：
 ```
-## Phase 1.5 完成：需求规格定义
+## Specs 完成：<name>
 
-**需求**: <name>
-**进度**: 2/8 阶段完成（标准级）或 2/9 阶段完成（完整级）
+**流程**: 轻量级
+**进度**: 2/5 阶段完成
 
 ### 需求概要
-- 功能需求：<数量> 个
-- 非功能需求：<数量> 个
-- 验收标准：<数量> 个
+- Capabilities：<数量> 个能力
+- Requirements：<数量> 个需求
+- Scenarios：<数量> 个测试场景
+- 非功能需求：<数量> 项
 
-### 核心功能
-<列出 2-3 个核心功能需求>
+### 核心 Capabilities
+<列出 2-3 个核心 Capability 及其变更类型（ADD/MODIFY/REMOVE）>
+
+### 文档位置
+6aspecdoc/brown/<name>/artifacts/specs.md
+
+### 下一步
+- 直接回复补充或修正需求规格 → 我会更新本阶段文档（specs.md）
+- 运行 `/6aspec:brown:design` → 进入技术方案设计阶段
+- 运行 `/6aspec:brown:continue` → 自动进入下一阶段
+```
+
+**标准级流程**：
+```
+## Specs 完成：<name>
+
+**流程**: 标准级
+**进度**: 3/5 阶段完成
+
+### 需求概要
+- Capabilities：<数量> 个能力
+- Requirements：<数量> 个需求
+- Scenarios：<数量> 个测试场景
+- 非功能需求：<数量> 项
 
-### 关键约束
-<列出 1-2 个关键约束>
+### 核心 Capabilities
+<列出 2-3 个核心 Capability 及其变更类型（ADD/MODIFY/REMOVE）>
 
 ### 文档位置
-6aspecdoc/brown/<name>/artifacts/01.5-specs.md
+6aspecdoc/brown/<name>/artifacts/specs.md
 
 ### 下一步
-- 直接回复补充或修正需求规格 → 我会更新本阶段文档（01.5-specs.md）
-- 运行 `/6aspec:brown:impact` → 进入影响面分析阶段
+- 直接回复补充或修正需求规格 → 我会更新本阶段文档（specs.md）
+- 运行 `/6aspec:brown:design` → 进入技术方案设计阶段
 - 运行 `/6aspec:brown:continue` → 自动进入下一阶段
 ```
 
 **用户补充信息时的处理**
 
 当用户补充需求细节、修正功能需求时（未使用阶段命令）：
-1. 将用户的补充整合到 `01.5-specs.md` 的对应章节（功能需求、非功能需求、验收标准等）
+1. 将用户的补充整合到 `specs.md` 的对应章节（功能需求、非功能需求、验收标准等）
 2. 展示变更摘要
 3. 再次提示：可以继续补充，或通过命令进入下一阶段
 4. **禁止**：不得自动进入下一阶段
 
 **防护措施**
-- 必须先完成 Phase 1（understand）
-- 只适用于标准级和完整级流程
+- 适用于所有流程（轻量级、标准级、完整级）
+- 根据flowDepth检查不同的前置阶段：
+  - 轻量级：必须先完成proposal阶段
+  - 标准级/完整级：必须先完成impact阶段
+- 功能需求必须按 Capability 组织，结构为：Capability > Requirement > Scenario
+- 每个 Capability 必须标识变更类型：[ADD]（新增）、[MODIFY]（修改）、[REMOVE]（移除）
+- 每个 Capability 应该对应 proposal.md 中的一个能力
+- 功能需求必须使用 Requirement + Scenario (WHEN/THEN) 格式
+- 每个 Scenario 的触发类型只能从「用户操作｜外部系统触发｜事件订阅｜定时任务」中选择
+- 使用 SHALL/MUST 表示强制性要求，SHOULD 表示推荐性要求
+- 每个 Scenario 必须可测试、可验证
 - 功能需求必须从用户视角描述，避免技术实现细节
-- 验收标准必须具体、可验证
 - 需求问题的答案应该体现在功能需求定义中，而不是单独列出
+- 非功能需求和范围边界只写有明确要求的内容，避免空泛描述
+- specs的详细程度保持一致，不区分流程深度