@zeyue0329/xiaoma-cli 1.0.49 → 6.0.0-alpha.13

package/src/modules/xmc/docs/iteration-development-guide.md

@@ -0,0 +1,752 @@
+# XiaoMa Method 需求迭代开发详细步骤指南
+
+本指南详细说明如何使用 XiaoMa Method 框架完成需求迭代开发，包括每个步骤的智能体选择、工作流调用和具体的 Prompt 模板。
+
+## 目录
+
+- [场景分析](#场景分析)
+- [开发流程总览](#开发流程总览)
+- [详细步骤与 Prompt](#详细步骤与-prompt)
+  - [Step 0: 项目文档化](#step-0-项目文档化-可选)
+  - [Step 1: 工作流初始化](#step-1-工作流初始化)
+  - [Step 2: 需求规划](#step-2-需求规划)
+  - [Step 3: 架构设计](#step-3-架构设计-仅-xiaoma-method)
+  - [Step 4: 创建史诗和故事](#step-4-创建史诗和故事)
+  - [Step 5: Sprint 规划](#step-5-sprint-规划)
+  - [Step 6: 故事开发循环](#step-6-故事开发循环)
+  - [Step 7: Sprint 回顾](#step-7-sprint-回顾-可选)
+- [快速参考卡片](#快速参考卡片)
+- [重要提示](#重要提示)
+
+---
+
+## 场景分析
+
+典型的需求迭代开发场景：
+
+- **项目类型**: 棕地项目（已有现有代码库）
+- **输入**: 产品经理提供的需求文档
+- **目标**: 完成需求迭代开发
+
+---
+
+## 开发流程总览
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Step 0: 项目文档化 (可选,如文档不足)                              │
+│  └─ Analyst: document-project                                   │
+├─────────────────────────────────────────────────────────────────┤
+│  Step 1: 工作流初始化                                            │
+│  └─ PM: workflow-init → 确定轨道                                 │
+├─────────────────────────────────────────────────────────────────┤
+│  Step 2: 需求规划                                                │
+│  ├─ Quick Flow: PM → tech-spec                                  │
+│  └─ XiaoMa Method: PM → prd                                     │
+├─────────────────────────────────────────────────────────────────┤
+│  Step 3: 架构设计 (仅 XiaoMa Method)                             │
+│  └─ Architect: create-architecture                              │
+├─────────────────────────────────────────────────────────────────┤
+│  Step 4: 创建史诗和故事                                          │
+│  └─ PM: create-epics-and-stories                                │
+├─────────────────────────────────────────────────────────────────┤
+│  Step 5: Sprint 规划                                             │
+│  └─ SM: sprint-planning                                         │
+├─────────────────────────────────────────────────────────────────┤
+│  Step 6: 故事开发循环                                            │
+│  ├─ SM: create-story                                            │
+│  ├─ DEV: dev-story                                              │
+│  └─ DEV: code-review                                            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 详细步骤与 Prompt
+
+### Step 0: 项目文档化 (可选)
+
+> **何时需要**: 如果你的项目缺少清晰的架构文档、技术栈说明，建议先执行此步骤
+
+**智能体**: Analyst (Mary) 📊
+
+**工作流**: `document-project`
+
+**Prompt**:
+
+```
+*document-project
+
+我需要你帮我对现有项目进行全面的文档化分析。
+
+项目路径: [你的项目根目录路径]
+
+请使用 "Deep" 扫描级别，分析以下内容:
+1. 项目技术栈和框架
+2. 代码架构和目录结构
+3. 核心模块和组件
+4. API 接口和数据模型
+5. 依赖关系和配置
+
+请生成优化的代码库文档，以便后续的需求开发工作。
+```
+
+---
+
+### Step 1: 工作流初始化
+
+> **目的**: 分析需求复杂度，确定使用哪个开发轨道
+
+**智能体**: PM (John) 📋
+
+**工作流**: `workflow-init`
+
+**Prompt**:
+
+```
+*workflow-init
+
+我需要基于现有项目进行需求迭代开发。
+
+## 需求文档内容
+[在此粘贴你的需求文档内容]
+
+## 项目背景
+- 项目名称: [你的项目名称]
+- 项目类型: 棕地项目（现有代码库）
+- 技术栈: [列出主要技术栈，如 React, Node.js, PostgreSQL 等]
+
+请分析需求复杂度，并推荐适合的开发轨道:
+- Quick Flow (Level 0-1): 适用于 Bug 修复、小功能
+- XiaoMa Method (Level 2-3): 适用于中等复杂度的产品功能
+- Enterprise Method (Level 4): 适用于企业级大型系统
+
+请给出你的建议和理由。
+```
+
+**预期输出**:
+
+- 创建 `xmc-workflow-status.yaml` 文件
+- 确定开发轨道 (Quick Flow / XiaoMa Method / Enterprise)
+- 下一步工作流建议
+
+---
+
+### Step 2: 需求规划
+
+#### Step 2A: Quick Flow 轨道
+
+> **适用条件**: Step 1 确定为 Level 0-1 (Bug 修复、小功能)
+
+**智能体**: PM (John) 📋
+
+**工作流**: `tech-spec`
+
+**Prompt**:
+
+```
+*tech-spec
+
+## 需求文档
+[在此粘贴你的需求文档内容]
+
+## 项目上下文
+- 项目名称: [项目名称]
+- 现有代码库路径: [项目路径]
+- 相关模块/文件: [列出可能涉及的文件或模块]
+
+请基于需求创建技术规范文档，包含:
+1. 功能概述和目标
+2. 技术实现方案
+3. 接口设计 (如有)
+4. 数据模型变更 (如有)
+5. 任务分解和接受标准
+6. 测试要求
+
+请确保技术规范足够详细，可以直接指导开发实现。
+```
+
+**如果选择 Quick Flow，直接跳到 Step 5**
+
+---
+
+#### Step 2B: XiaoMa Method 轨道
+
+> **适用条件**: Step 1 确定为 Level 2-4 (中大型功能/产品)
+
+**智能体**: PM (John) 📋
+
+**工作流**: `prd`
+
+**Prompt**:
+
+```
+*prd
+
+## 原始需求文档
+[在此粘贴你的需求文档内容]
+
+## 项目上下文
+- 项目名称: [项目名称]
+- 产品定位: [简要描述产品是什么]
+- 目标用户: [目标用户群体]
+- 现有功能: [简要列出现有的主要功能]
+
+请创建完整的产品需求文档 (PRD)，包含:
+
+### 功能需求 (FRs)
+请将需求分解为具体的功能需求项，每个需求项需包含:
+- FR ID 和名称
+- 详细描述
+- 用户故事 (As a... I want... So that...)
+- 接受标准 (Given/When/Then 格式)
+- 优先级 (P0/P1/P2)
+
+### 非功能需求 (NFRs)
+包括但不限于:
+- 性能要求
+- 安全要求
+- 可用性要求
+- 可维护性要求
+
+### 依赖和约束
+- 技术约束
+- 业务约束
+- 时间约束
+
+请确保 PRD 足够详细，能够指导后续的架构设计和开发实现。
+```
+
+---
+
+#### Step 2C: UX 设计 (可选)
+
+> **适用条件**: 需求涉及用户界面变更
+
+**智能体**: UX Designer (Sally) 🎨
+
+**工作流**: `create-ux-design`
+
+**Prompt**:
+
+```
+*create-ux-design
+
+请基于已创建的 PRD 文档，为此次迭代创建 UX 设计规范。
+
+## 设计范围
+- 涉及的页面/组件: [列出需要设计的页面或组件]
+- 现有设计系统: [描述项目现有的设计规范，如有]
+
+请提供:
+1. 用户流程图 (User Flow)
+2. 交互设计说明
+3. 组件规范 (尺寸、颜色、状态)
+4. 响应式设计考虑
+5. 无障碍性要求
+
+请使用 Mermaid 图表展示用户流程。
+```
+
+---
+
+### Step 3: 架构设计 (仅 XiaoMa Method)
+
+> **适用条件**: Level 2-4 项目，涉及架构变更
+
+**智能体**: Architect (Winston) 🏗️
+
+**工作流**: `create-architecture`
+
+**Prompt**:
+
+```
+*create-architecture
+
+请基于 PRD 文档创建技术架构设计。
+
+## 现有架构背景
+- 当前技术栈: [列出技术栈]
+- 现有架构模式: [如 MVC, 微服务, 单体等]
+- 数据库: [数据库类型和当前 schema 概述]
+
+## 架构设计要求
+请提供以下内容:
+
+### 1. 系统架构概览
+- 整体架构图 (使用 Mermaid)
+- 新增/变更的组件说明
+
+### 2. 数据模型设计
+- 新增/变更的数据表
+- 实体关系图 (ER Diagram)
+- 数据迁移策略 (如需)
+
+### 3. API 设计
+- 新增/变更的 API 端点
+- 请求/响应格式
+- 认证和授权策略
+
+### 4. 技术决策记录 (ADR)
+- 关键技术选型及理由
+- 权衡分析
+
+### 5. 集成方案
+- 与现有系统的集成点
+- 第三方服务集成 (如有)
+
+### 6. 非功能性考虑
+- 性能优化策略
+- 安全措施
+- 可扩展性设计
+
+请确保架构设计与现有代码库兼容，并尽量减少对现有功能的影响。
+```
+
+---
+
+#### Step 3.5: 架构验证 (推荐)
+
+**智能体**: Architect (Winston) 🏗️
+
+**工作流**: `validate-architecture`
+
+**Prompt**:
+
+```
+*validate-architecture
+
+请验证刚才创建的架构设计文档。
+
+验证要点:
+1. 架构设计是否完整覆盖了 PRD 中的所有功能需求?
+2. 技术选型是否合理?
+3. 数据模型设计是否规范?
+4. API 设计是否符合 RESTful 规范?
+5. 是否考虑了扩展性和维护性?
+6. 是否有潜在的技术风险?
+
+请指出任何问题并给出改进建议。
+```
+
+---
+
+### Step 4: 创建史诗和故事
+
+**智能体**: PM (John) 📋
+
+**工作流**: `create-epics-and-stories`
+
+**Prompt**:
+
+```
+*create-epics-and-stories
+
+请基于 PRD 和架构设计文档，创建史诗 (Epics) 和用户故事 (Stories)。
+
+## 分解要求
+
+### 史诗 (Epics)
+- 将需求按功能模块分组为史诗
+- 每个史诗应有明确的业务价值
+- 史诗之间应尽量解耦
+
+### 用户故事 (Stories)
+每个故事需包含:
+- Story ID 和标题
+- 所属史诗
+- 用户故事描述 (As a... I want... So that...)
+- 接受标准 (Given/When/Then 格式)
+- 故事点估算 (1/2/3/5/8)
+- 优先级
+- 技术依赖 (其他故事 ID)
+- 相关文件路径提示
+
+### 分解原则
+- 每个故事应可在 1-2 天内完成
+- 故事应独立可测试
+- 遵循 INVEST 原则 (Independent, Negotiable, Valuable, Estimable, Small, Testable)
+
+请输出结构化的史诗和故事列表。
+```
+
+---
+
+#### Step 4.5: 实现就绪检查
+
+**智能体**: Architect (Winston) 🏗️
+
+**工作流**: `implementation-readiness`
+
+**Prompt**:
+
+```
+*implementation-readiness
+
+请检查项目是否已准备好进入实现阶段 (Phase 4)。
+
+验证清单:
+1. PRD 文档是否完整且已验证?
+2. 架构设计是否覆盖所有技术需求?
+3. 史诗和故事是否已正确分解?
+4. 故事之间的依赖关系是否清晰?
+5. 是否存在未解决的技术问题或风险?
+6. 开发环境是否已准备就绪?
+
+请给出实现就绪状态评估和建议。
+```
+
+---
+
+### Step 5: Sprint 规划
+
+**智能体**: SM (Bob) 🏃
+
+**工作流**: `sprint-planning`
+
+**Prompt**:
+
+```
+*sprint-planning
+
+请初始化 Sprint 并创建 sprint-status.yaml 追踪文件。
+
+## Sprint 配置
+- Sprint 名称: [如 "Sprint 1 - 用户认证功能"]
+- Sprint 目标: [简要描述本 Sprint 的目标]
+- Sprint 周期: [如 2 周]
+
+## 故事选择
+请根据以下原则选择本 Sprint 的故事:
+1. 优先选择高优先级故事
+2. 考虑故事依赖关系，先实现被依赖的故事
+3. 控制 Sprint 容量，不要超载
+
+请创建 sprint-status.yaml 文件，并输出 Sprint 计划概览。
+```
+
+**预期输出**:
+
+- 创建 `sprint-status.yaml` 文件
+- Sprint 故事列表和顺序
+
+---
+
+### Step 6: 故事开发循环
+
+> 对于 Sprint 中的每个故事，重复以下 6.1 → 6.2 → 6.3 步骤
+
+---
+
+#### Step 6.1: 创建故事上下文
+
+**智能体**: SM (Bob) 🏃
+
+**工作流**: `create-story`
+
+**Prompt**:
+
+```
+*create-story
+
+请从积压中创建下一个待开发的故事。
+
+当前 Sprint: [Sprint 名称]
+目标故事: [故事 ID，如 AUTH-001]
+
+请生成故事上下文 XML，包含:
+1. 故事详细描述
+2. 完整的接受标准
+3. 技术实现指导
+4. 相关文件路径
+5. 测试要求
+6. 依赖说明
+
+确保上下文足够详细，让 DEV 智能体可以独立完成实现。
+```
+
+---
+
+#### Step 6.2: 故事开发实现
+
+**智能体**: DEV (Amelia) 💻
+
+**工作流**: `dev-story`
+
+**Prompt**:
+
+```
+*dev-story
+
+请实现以下故事:
+
+故事 ID: [故事 ID]
+故事标题: [故事标题]
+
+## 实现要求
+1. 严格按照故事上下文 XML 中的接受标准实现
+2. 遵循项目现有的代码风格和架构模式
+3. 编写必要的单元测试
+4. 确保所有测试通过
+5. 不要引入新的安全漏洞
+
+## 实现步骤
+请按以下顺序执行:
+1. 阅读并理解故事上下文
+2. 分析需要修改的文件
+3. 实现功能代码
+4. 编写测试代码
+5. 运行测试确保通过
+6. 更新相关文档 (如需)
+
+完成后请汇报:
+- 修改的文件列表
+- 新增的文件列表
+- 测试执行结果
+- 任何需要注意的事项
+```
+
+---
+
+#### Step 6.3: 代码审查
+
+**智能体**: DEV (Amelia) 💻
+
+**工作流**: `code-review`
+
+**Prompt**:
+
+```
+*code-review
+
+请对刚才实现的故事进行代码审查。
+
+故事 ID: [故事 ID]
+
+## 审查维度
+请从以下方面进行审查:
+
+### 1. 功能正确性
+- 是否满足所有接受标准?
+- 边界情况是否处理?
+
+### 2. 代码质量
+- 代码是否清晰可读?
+- 命名是否规范?
+- 是否有代码重复?
+- 是否遵循项目代码规范?
+
+### 3. 安全性
+- 是否存在安全漏洞 (注入、XSS 等)?
+- 敏感数据是否正确处理?
+
+### 4. 性能
+- 是否有明显的性能问题?
+- 数据库查询是否优化?
+
+### 5. 测试覆盖
+- 测试是否充分?
+- 是否覆盖边界情况?
+
+### 6. 可维护性
+- 代码是否易于理解和修改?
+- 是否有必要的注释?
+
+请给出审查结论:
+- APPROVED: 代码通过审查，可以合并
+- CHANGES REQUESTED: 需要修改，请列出具体问题
+```
+
+---
+
+#### Step 6.4: 更新故事状态
+
+**智能体**: SM (Bob) 🏃
+
+**Prompt**:
+
+```
+请更新 sprint-status.yaml 中故事 [故事 ID] 的状态为:
+- 如果代码审查通过: "Done"
+- 如果代码审查需要修改: 保持 "In Progress"
+
+并汇报当前 Sprint 进度。
+```
+
+---
+
+### Step 7: Sprint 回顾 (可选)
+
+> **时机**: 完成一个史诗或 Sprint 后
+
+**智能体**: SM (Bob) 🏃
+
+**工作流**: `epic-retrospective`
+
+**Prompt**:
+
+```
+*epic-retrospective
+
+请对刚完成的 [史诗名称/Sprint] 进行回顾。
+
+## 回顾内容
+1. 什么做得好?
+2. 什么可以改进?
+3. 遇到了哪些障碍?
+4. 学到了什么经验?
+
+## 度量
+- 计划故事数: X
+- 完成故事数: Y
+- 故事点完成率: Z%
+
+请总结经验教训，为下一个 Sprint 提供改进建议。
+```
+
+---
+
+## 快速参考卡片
+
+### 智能体调用快速参考
+
+| 步骤 | 智能体 | 工作流 | 触发命令 |
+|------|--------|--------|---------|
+| 项目文档化 | Analyst | document-project | `*document-project` |
+| 工作流初始化 | PM | workflow-init | `*workflow-init` |
+| 技术规范 (Quick) | PM | tech-spec | `*tech-spec` |
+| PRD 创建 | PM | prd | `*prd` |
+| UX 设计 | UX Designer | create-ux-design | `*create-ux-design` |
+| 架构设计 | Architect | create-architecture | `*create-architecture` |
+| 创建史诗故事 | PM | create-epics-and-stories | `*create-epics-and-stories` |
+| Sprint 规划 | SM | sprint-planning | `*sprint-planning` |
+| 创建故事 | SM | create-story | `*create-story` |
+| 故事开发 | DEV | dev-story | `*dev-story` |
+| 代码审查 | DEV | code-review | `*code-review` |
+
+### 轨道选择快速参考
+
+| 需求类型 | 轨道 | 关键工作流 |
+|---------|------|-----------|
+| Bug 修复、小改动 | Quick Flow | tech-spec → quick-dev |
+| 中等功能 (5-15 故事) | XiaoMa Method | prd → architecture → stories |
+| 大型功能 (15+ 故事) | Enterprise | prd → full architecture → stories |
+
+### 智能体角色速查
+
+| 智能体 | 图标 | 主要阶段 | 最佳用于 |
+|--------|------|---------|---------|
+| **Analyst** | 📊 | Phase 1 (分析) | 发现、需求、棕地文档 |
+| **PM** | 📋 | Phase 2 (规划) | 规划、需求文档 |
+| **UX Designer** | 🎨 | Phase 2 (规划) | UX 重型项目、设计 |
+| **Architect** | 🏗️ | Phase 3 (解决方案) | 技术设计、架构 |
+| **SM** | 🏃 | Phase 4 (实现) | 故事管理、Sprint 协调 |
+| **DEV** | 💻 | Phase 4 (实现) | 实现、编码 |
+| **TEA** | 🧪 | 所有阶段 | 测试、质量保证 |
+| **Technical Writer** | 📚 | 所有阶段 | 文档、图表 |
+| **Principal Engineer** | ⚡ | Quick Flow | 快速开发、技术领导力 |
+| **XiaoMa Master** | 🧙 | 元 | 编排、多智能体协作 |
+
+---
+
+## 重要提示
+
+### 1. 新鲜聊天原则
+
+每个主要工作流建议在新的聊天会话中执行，避免上下文污染导致 AI 幻觉。
+
+**适用场景**:
+- 规划工作流（PRD、架构）
+- 分析工作流（头脑风暴、研究）
+- 复杂故事实现
+
+### 2. 一次一个故事
+
+完成一个故事的完整生命周期后再开始下一个：
+```
+create-story → dev-story → code-review → 更新状态 → 下一个故事
+```
+
+### 3. 及时验证
+
+在阶段过渡前运行验证工作流：
+- Phase 2 → 3: `validate-prd`, `validate-tech-spec`
+- Phase 3 → 4: `implementation-readiness`
+
+### 4. 状态追踪
+
+随时可以使用 `*workflow-status` 检查当前进度和下一步建议。
+
+### 5. 变更管理
+
+如果开发过程中需求变更，使用 `*correct-course` 工作流处理。
+
+---
+
+## 常见问题
+
+### Q: 如何选择正确的轨道?
+
+运行 `*workflow-init`，系统会根据需求复杂度自动推荐。
+
+### Q: 迷茫时怎么办?
+
+加载任何智能体，运行 `*workflow-status`，系统会分析当前状态并建议下一步。
+
+### Q: 需求中途变更怎么办?
+
+使用 PM、Architect 或 SM 智能体的 `*correct-course` 工作流。
+
+### Q: 如何进行多智能体协作讨论?
+
+使用 `*party-mode` 工作流，XiaoMa Master 会编排多个智能体进行协作讨论。
+
+---
+
+## 附录: 工作流状态追踪文件
+
+### xmc-workflow-status.yaml
+
+由 `workflow-init` 创建，追踪项目整体进度：
+
+```yaml
+project:
+  name: "Project Name"
+  track: "XiaoMa Method"
+
+phases:
+  analysis:
+    status: "Completed"
+    workflows:
+      brainstorm-project: completed
+      product-brief: completed
+
+  planning:
+    status: "In Progress"
+    workflows:
+      prd: completed
+      create-ux-design: pending
+
+  solutioning:
+    status: "Not Started"
+
+  implementation:
+    status: "Not Started"
+```
+
+### sprint-status.yaml
+
+由 `sprint-planning` 创建，追踪实现进度：
+
+```yaml
+epics:
+  - name: "User Authentication"
+    status: "In Progress"
+    stories:
+      - id: "AUTH-001"
+        title: "Login with email"
+        status: "Done"
+      - id: "AUTH-002"
+        title: "OAuth integration"
+        status: "In Progress"
+```