6aspec 2.0.0-dev.2 → 2.0.0-dev.20

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

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

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

@@ -31,28 +31,33 @@
 
    ### 阶段进度
 
-   **轻量级流程（4阶段）**：
+   **轻量级流程（5阶段）**：
    | 阶段 | 状态 | 完成时间 |
    |------|------|----------|
    | Proposal | ✅ 已完成 / 🔄 进行中 / 📋 待开始 / 🔒 阻塞 | <timestamp> |
+   | Specs | ... | ... |
    | Design | ... | ... |
    | Tasks | ... | ... |
    | Implement | ... | ... |
 
-   **标准级流程（5阶段）**：
+   **标准级流程（7阶段）**：
    | 阶段 | 状态 | 完成时间 |
    |------|------|----------|
    | Understand | ✅ 已完成 / 🔄 进行中 / 📋 待开始 / 🔒 阻塞 | <timestamp> |
    | Impact | ... | ... |
+   | Proposal | ... | ... |
+   | Specs | ... | ... |
    | Design | ... | ... |
    | Tasks | ... | ... |
    | Implement | ... | ... |
 
-   **完整级流程（7阶段）**：
+   **完整级流程（9阶段）**：
    | 阶段 | 状态 | 完成时间 |
    |------|------|----------|
    | Understand | ✅ 已完成 / 🔄 进行中 / 📋 待开始 / 🔒 阻塞 | <timestamp> |
    | Impact | ... | ... |
+   | Proposal | ... | ... |
+   | Specs | ... | ... |
    | Design | ... | ... |
    | Tasks | ... | ... |
    | Implement | ... | ... |
@@ -70,18 +75,23 @@
 
    **轻量级**：
    - [ ] proposal.md
+   - [ ] specs.md
    - [ ] design.md
    - [ ] tasks.md
 
    **标准级**：
    - [ ] understanding.md
    - [ ] impact-analysis.md
+   - [ ] proposal.md
+   - [ ] specs.md
    - [ ] design.md
    - [ ] tasks.md
 
    **完整级**：
    - [ ] understanding.md
    - [ ] impact-analysis.md
+   - [ ] proposal.md
+   - [ ] specs.md
    - [ ] design.md
    - [ ] tasks.md
    - [ ] verification-report.md