update bmad user guide

BMAD-PILOT-USER-GUIDE.md

@@ -0,0 +1,164 @@
+# BMAD Pilot 使用指南
+
+本指南介绍如何使用 BMAD Pilot 工作流，编排一组协作 AI 角色（PO/Architect/SM/Dev/QA）在仓库上下文中完成：01 产品需求文档、02 系统设计规范、03 冲刺计划，并自动进入开发与测试，整个过程包含多次用户确认门与质量评分。
+
+参考阅读：BMAD-README.md（BMAD 方法概览）、BMAD-INTEGRATION-GUIDE.md（进阶集成）。
+
+---
+
+## 命令总览
+
+- 命令：`/bmad-pilot <PROJECT_DESCRIPTION> [OPTIONS]`
+- 作用：在仓库上下文中，按阶段编排 `bmad-po → bmad-architect → bmad-sm → bmad-dev → bmad-qa`。
+- Orchestrator：`bmad-orchestrator` 负责整体调度与确认门控制。
+
+### Options
+- `--skip-tests`：跳过 QA 阶段
+- `--direct-dev`：跳过 SM 冲刺计划，架构后直接进入开发
+- `--skip-scan`：跳过初始仓库扫描（不推荐）
+
+### 输出目录
+- 所有产出归档在：`./.claude/specs/{feature_name}/`
+  - `00-repo-scan.md` — 仓库扫描摘要（自动生成）
+  - `01-product-requirements.md` — 产品需求文档（确认后保存）
+  - `02-system-architecture.md` — 系统设计规范（确认后保存）
+  - `03-sprint-plan.md` — 冲刺计划（确认后保存；`--direct-dev` 时跳过）
+
+`{feature_name}` 由 `<PROJECT_DESCRIPTION>` 生成（kebab-case：小写，空格/标点转 `-`，连续合并，首尾去除）。
+
+---
+
+## 快速开始
+
+1) 执行 Pilot：
+```
+/bmad-pilot 为现有项目新增看板模块，支持多用户权限与移动端适配
+```
+2) 与 PO 交互澄清，直至 PRD ≥ 90 分 → 确认保存。
+3) 与 Architect 讨论技术决策，直至架构 ≥ 90 分 → 确认保存。
+4) 审阅并确认 SM 的冲刺计划（或使用 `--direct-dev` 跳过该阶段）。
+5) Dev 基于文档实现；QA 基于文档与实现测试（除非 `--skip-tests`）。
+6) 查看产出目录：`./.claude/specs/{feature_name}/`。
+
+---
+
+## 工作流阶段
+
+- Phase 0：仓库扫描（自动，除非 `--skip-scan`）
+  - Agent：`bmad-orchestrator`
+  - 结果：扫描摘要返回并写入 `00-repo-scan.md`
+  - 内容：项目类型、技术栈、代码组织、惯例、集成点、约束与注意事项
+
+- Phase 1：产品需求（交互）
+  - Agent：`bmad-po`
+  - 循环：澄清问题 → 更新 PRD → 评分（目标 ≥ 90）
+  - 确认门：PRD ≥ 90 分后，需要用户明确确认再继续
+  - 保存：`01-product-requirements.md`
+
+- Phase 2：系统架构（交互）
+  - Agent：`bmad-architect`
+  - 循环：技术选型与设计澄清 → 更新架构 → 评分（目标 ≥ 90）
+  - 确认门：架构 ≥ 90 分后，需要用户明确确认再继续
+  - 保存：`02-system-architecture.md`
+
+- Phase 3：冲刺计划（交互，除非 `--direct-dev`）
+  - Agent：`bmad-sm`
+  - 循环：计划要点与问题澄清 → 更新计划 → 确认保存
+  - 保存：`03-sprint-plan.md`
+
+- Phase 4：开发实现（自动）
+  - Agent：`bmad-dev`
+  - 输入：PRD、架构、冲刺计划、`00-repo-scan.md`
+
+- Phase 5：质量保障（自动，除非 `--skip-tests`）
+  - Agent：`bmad-qa`
+  - 输入：PRD、架构、冲刺计划、实现、`00-repo-scan.md`
+
+---
+
+## 交互与质量门
+
+- 质控阈值：PRD 与架构质量评分需达到 ≥ 90 分。
+- 强制确认门：每个关键阶段完成后，Orchestrator 会停下等待你的“继续/确认”。
+- 迭代澄清：PO/Architect/SM 会提出 2-5 个精准问题，Orchestrator 转述并汇总你的回答以供下一轮完善。
+
+---
+
+## 仓库上下文
+
+- 首次扫描：`bmad-orchestrator` 自动扫描当前仓库（`--skip-scan` 可跳过）。
+- 缓存路径：`./.claude/specs/{feature_name}/00-repo-scan.md`（供所有后续 Agent 引用）。
+- 作用：提供技术栈识别、约定、测试模式、集成点，避免上下文丢失并保持一致性。
+
+---
+
+## 角色职责
+
+- `bmad-po`：需求澄清与 PRD 产出，评分与问题驱动迭代。
+- `bmad-architect`：技术架构与关键决策，评分与问题驱动迭代。
+- `bmad-sm`：冲刺计划、任务拆分、依赖/风险/节奏规划。
+- `bmad-dev`：按文档实现、测试、日志/安全/性能与同构风格。
+- `bmad-qa`：基于需求与实现的全维度测试（单测/集成/E2E/性能/安全）。
+
+---
+
+## 示例
+
+- 基础运行：
+```
+/bmad-pilot 在线商城结算流程升级，支持优惠券与发票
+```
+
+- 跳过测试：
+```
+/bmad-pilot H5 活动页生成器 --skip-tests
+```
+
+- 直接从架构进入开发（跳过 SM）：
+```
+/bmad-pilot 小程序客服模块重构 --direct-dev
+```
+
+- 跳过扫描（不推荐）：
+```
+/bmad-pilot 部署流水线可视化 --skip-scan
+```
+
+---
+
+## 目录结构
+
+```
+.claude/
+  specs/
+    {feature_name}/
+      00-repo-scan.md
+      01-product-requirements.md
+      02-system-architecture.md
+      03-sprint-plan.md
+```
+
+---
+
+## Tips & 常见问题
+
+- 分数上不去：优先补齐评分分项的缺口（业务指标、关键流程、性能/安全约束等）。
+- 上下文不一致：检查并引用 `00-repo-scan.md` 的关键约定与模式，保证 PRD/架构/计划一致。
+- 依赖/网络受限：Dev/QA 的实际执行受环境影响；请在项目内准备依赖与测试环境，或先提交伪实现/测试策略。
+- 文档路径：确保在项目根目录执行，Pilot 会将文件写入 `./.claude/specs/{feature_name}/`。
+
+---
+
+## 最佳实践
+
+- 小步快跑：每轮补充最关键信息，快速达成 ≥ 90 分文档。
+- 统一术语：在 PRD 固定术语词表；架构与代码沿用同名。
+- 用例先行：PRD 的验收标准应转化为 QA 的关键测试用例。
+- 复用模式：尽量沿用扫描识别的现有代码/测试模式，减少偏差。
+
+---
+
+## 版本记录
+
+- 2025-08-11：新增仓库扫描摘要缓存 `00-repo-scan.md`，统一路径与跨阶段引用；明确确认门与目录预创建说明。
+