# Reference
- https://github.com/bmad-code-org/BMAD-METHOD
- Doc: user-guide.md
- Date: 25-09-04
- Verson: 4.43.0

# BMad 方法 — 用戶指南

本指南將幫助您了解並有效使用 BMad 方法進行敏捷 AI 驅動的規劃和開發。

## BMad 計劃與執行工作流程

首先，這是完整的標準綠地（Greenfield）規劃 + 執行工作流程。棕地（Brownfield）項目非常相似，但建議即使在簡單項目上也要先理解這個綠地流程，然後再處理棕地項目。BMad 方法需要安裝到您新項目文件夾的根目錄。對於規劃階段，您可以選擇使用強大的網頁代理程式來執行，這可能以較低的成本獲得更高質量的結果，相比於在某些代理工具中提供您自己的 API 密鑰或積分。對於規劃，強大的思維模型和更大的上下文 - 以及作為代理的合作夥伴 - 將產生最佳結果。

如果您要在棕地項目（現有項目）上使用 BMad 方法，請查看 **[在棕地工作](./working-in-the-brownfield.md)**。

如果下面的圖表無法渲染，請在 VSCode（或其中一個分叉克隆版本）中安裝 Markdown All in One 以及 Markdown Preview Mermaid Support 插件。使用這些插件，當您右鍵點擊標籤時，應該有一個打開預覽選項，或查看 IDE 文檔。

### 規劃工作流程（Web UI 或強大的 IDE 代理）

在開發開始之前，BMad 遵循結構化的規劃工作流程，理想情況下在 web UI 中進行以提高成本效益：

graph TD
    A["開始：項目想法"] --> B{"可選：分析師研究"}
    B -->|是| C["分析師：頭腦風暴（可選）"]
    B -->|否| G{"項目簡報可用？"}
    C --> C2["分析師：市場研究（可選）"]
    C2 --> C3["分析師：競爭對手分析（可選）"]
    C3 --> D["分析師：創建項目簡報"]
    D --> G
    G -->|是| E["PM：從簡報創建 PRD（快速通道）"]
    G -->|否| E2["PM：交互式 PRD 創建（更多問題）"]
    E --> F["創建包含 FRs、NFRs、史詩和故事的 PRD"]
    E2 --> F
    F --> F2{"需要 UX？"}
    F2 -->|是| F3["UX 專家：創建前端規格"]
    F2 -->|否| H["架構師：從 PRD 創建架構"]
    F3 --> F4["UX 專家：為 Lovable/V0 生成 UI 提示（可選）"]
    F4 --> H2["架構師：從 PRD + UX 規格創建架構"]
    H --> Q{"早期測試策略？（可選）"}
    H2 --> Q
    Q -->|是| R["QA：對高風險區域的早期測試架構輸入"]
    Q -->|否| I
    R --> I["PO：運行主檢查清單"]
    I --> J{"文檔對齊？"}
    J -->|是| K["規劃完成"]
    J -->|否| L["PO：更新史詩和故事"]
    L --> M["根據需要更新 PRD/架構"]
    M --> I
    K --> N["📁 切換到 IDE（如果在 Web 代理平台中）"]
    N --> O["PO：分片文檔"]
    O --> P["準備 SM/開發循環"]

    style A fill:#f5f5f5,color:#000
    style B fill:#e3f2fd,color:#000
    style C fill:#e8f5e9,color:#000
    style C2 fill:#e8f5e9,color:#000
    style C3 fill:#e8f5e9,color:#000
    style D fill:#e8f5e9,color:#000
    style E fill:#fff3e0,color:#000
    style E2 fill:#fff3e0,color:#000
    style F fill:#fff3e0,color:#000
    style F2 fill:#e3f2fd,color:#000
    style F3 fill:#e1f5fe,color:#000
    style F4 fill:#e1f5fe,color:#000
    style G fill:#e3f2fd,color:#000
    style H fill:#f3e5f5,color:#000
    style H2 fill:#f3e5f5,color:#000
    style Q fill:#e3f2fd,color:#000
    style R fill:#ffd54f,color:#000
    style I fill:#f9ab00,color:#fff
    style J fill:#e3f2fd,color:#000
    style K fill:#34a853,color:#fff
    style L fill:#f9ab00,color:#fff
    style M fill:#fff3e0,color:#000
    style N fill:#1a73e8,color:#fff
    style O fill:#f9ab00,color:#fff
    style P fill:#34a853,color:#fff

#### Web UI 到 IDE 轉換

**關鍵轉換點**：一旦 PO 確認文檔對齊，您必須從 web UI 切換到 IDE 開始開發工作流程：

1. **將文檔複製到項目**：確保 `docs/prd.md` 和 `docs/architecture.md` 在您項目的 docs 文件夾中（或您可以在安裝期間指定的自定義位置）
2. **切換到 IDE**：在您首選的代理 IDE 中打開項目
3. **文檔分片**：使用 PO 代理首先分片 PRD，然後分片架構
4. **開始開發**：開始接下來的核心開發循環

#### 規劃工件（標準路徑）

PRD              → docs/prd.md
架構             → docs/architecture.md
分片史詩         → docs/epics/
分片故事         → docs/stories/
QA 評估         → docs/qa/assessments/
QA 門檢         → docs/qa/gates/

### 核心開發循環（IDE）

一旦規劃完成並且文檔被分片，BMad 遵循結構化的開發工作流程：

graph TD
    A["開發階段開始"] --> B["SM：檢查之前的故事開發/QA 筆記"]
    B --> B2["SM：從分片史詩 + 架構草擬下一個故事"]
    B2 --> S{"高風險故事？（可選）"}
    S -->|是| T["QA：對草稿故事進行 *risk + *design"]
    S -->|否| B3
    T --> U["創建測試策略和風險配置文件"]
    U --> B3{"PO：驗證故事草稿（可選）"}
    B3 -->|請求驗證| B4["PO：根據工件驗證故事"]
    B3 -->|跳過驗證| C{"用戶批准"}
    B4 --> C
    C -->|批准| D["Dev：順序任務執行"]
    C -->|需要更改| B2
    D --> E["Dev：實現任務 + 測試"]
    E --> V{"開發中期 QA 檢查？（可選）"}
    V -->|是| W["QA：*trace 或 *nfr 早期驗證"]
    V -->|否| F
    W --> X["Dev：解決覆蓋率/NFR 差距"]
    X --> F["Dev：運行所有驗證"]
    F --> G["Dev：標記準備審查 + 添加筆記"]
    G --> H{"用戶驗證"}
    H -->|請求 QA 審查| I["QA：測試架構師審查 + 質量門檢"]
    H -->|無 QA 批准| M["重要：驗證所有回歸測試和 Linting 通過"]
    I --> J["QA：測試架構分析 + 積極重構"]
    J --> L{"QA 決定"}
    L -->|需要開發工作| D
    L -->|批准| M
    H -->|需要修復| D
    M --> N["重要：在繼續之前提交您的更改！"]
    N --> Y{"需要門檢更新？"}
    Y -->|是| Z["QA：*gate 更新狀態"]
    Y -->|否| K
    Z --> K["將故事標記為完成"]
    K --> B

    style A fill:#f5f5f5,color:#000
    style B fill:#e8f5e9,color:#000
    style B2 fill:#e8f5e9,color:#000
    style S fill:#e3f2fd,color:#000
    style T fill:#ffd54f,color:#000
    style U fill:#ffd54f,color:#000
    style B3 fill:#e3f2fd,color:#000
    style B4 fill:#fce4ec,color:#000
    style C fill:#e3f2fd,color:#000
    style D fill:#e3f2fd,color:#000
    style E fill:#e3f2fd,color:#000
    style V fill:#e3f2fd,color:#000
    style W fill:#ffd54f,color:#000
    style X fill:#e3f2fd,color:#000
    style F fill:#e3f2fd,color:#000
    style G fill:#e3f2fd,color:#000
    style H fill:#e3f2fd,color:#000
    style I fill:#f9ab00,color:#fff
    style J fill:#ffd54f,color:#000
    style K fill:#34a853,color:#fff
    style L fill:#e3f2fd,color:#000
    style M fill:#ff5722,color:#fff
    style N fill:#d32f2f,color:#fff
    style Y fill:#e3f2fd,color:#000
    style Z fill:#ffd54f,color:#000

## 先決條件

在安裝 BMad 方法之前，確保您有：

- **Node.js** ≥ 18，**npm** ≥ 9
- **Git** 已安裝並配置
- **（可選）** VS Code 與 "Markdown All in One" + "Markdown Preview Mermaid Support" 擴展

## 安裝

### 可選

如果您想在網頁上使用 Claude（Sonnet 4 或 Opus）、Gemini Gem（2.5 Pro）或 Custom GPTs 進行規劃：

1. 導航到 `dist/teams/`
2. 複製 `team-fullstack.txt`
3. 創建新的 Gemini Gem 或 CustomGPT
4. 上傳文件並說明："您的關鍵操作指令已附加，請不要違反指令中的角色設定"
5. 輸入 `/help` 查看可用命令

### IDE 項目設置

# 交互式安裝（推薦）
npx bmad-method install

### Codex（CLI 和 Web）

BMAD 通過 `AGENTS.md` 和提交的核心代理文件與 OpenAI Codex 集成。

- 兩種安裝模式：
- Codex（僅本地）：保持 `.bmad-core/` 被忽略用於本地開發。
- `npx bmad-method install -f -i codex -d .`
- Codex Web 啟用：確保 `.bmad-core/` 被追蹤，以便您可以為 Codex Web 提交它。
- `npx bmad-method install -f -i codex-web -d .`

- 生成的內容：
- 項目根目錄的 `AGENTS.md` 包含 BMAD 部分
- Codex 的使用方法（CLI 和 Web）
- 代理目錄（標題、ID、何時使用）
- 詳細的每個代理部分，包含源路徑、何時使用、激活措辭和 YAML
- 帶有快速使用說明的任務
- 如果存在 `package.json`，會添加有用的腳本：
- `bmad:refresh`、`bmad:list`、`bmad:validate`

- 使用 Codex：
- CLI：在項目根目錄運行 `codex` 並自然提示，例如"作為開發者，實現…"。
- Web：提交 `.bmad-core/` 和 `AGENTS.md`，然後在 Codex 中打開倉庫並以同樣方式提示。

- 更改後刷新：
- 重新運行適當的安裝模式（`codex` 或 `codex-web`）以更新 `AGENTS.md` 中的 BMAD 塊。

## 特殊代理

有兩個 BMad 代理 — 將來它們會合併為單個 BMad-Master。

### BMad-Master

此代理可以執行所有其他代理可以做的任何任務或命令，除了實際的故事實現。此外，此代理可以在網頁上通過訪問知識庫來幫助解釋 BMad 方法，並向您解釋過程中的任何內容。

如果您不想在除開發者之外的不同代理之間切換，這是適合您的代理。只需記住，隨著上下文的增長，代理的性能會下降，因此重要的是指示代理壓縮對話並以壓縮的對話作為初始消息開始新對話。經常這樣做，最好是在每個故事實現後。

### BMad-Orchestrator

此代理不應在 IDE 內使用，它是一個重型特殊用途代理，使用大量上下文並可以變形為任何其他代理。這僅存在於促進網頁包內的團隊。如果您使用網頁包，您將由 BMad Orchestrator 迎接。

### 代理如何工作

#### 依賴系統

每個代理都有一個定義其依賴關係的 YAML 部分：

dependencies:
  templates:
    - prd-template.md
    - user-story-template.md
  tasks:
    - create-doc.md
    - shard-doc.md
  data:
    - bmad-kb.md

**要點：**

- 代理只加載它們需要的資源（精簡上下文）
- 依賴關係在捆綁期間自動解決
- 資源在代理之間共享以保持一致性

#### 代理交互

**在 IDE 中：**

# 一些 IDE，如 Cursor 或 Windsurf 例如，使用手動規則，所以交互是用 '@' 符號完成的
@pm 為任務管理應用創建 PRD
@architect 設計系統架構
@dev 實現用戶認證

# 一些 IDE，如 Claude Code，使用斜槓命令
/pm 創建用戶故事
/dev 修復登錄錯誤

#### 交互模式

- **增量模式**：逐步用戶輸入
- **YOLO 模式**：最少交互的快速生成

## IDE 集成

### IDE 最佳實踐

- **上下文管理**：只在上下文中保留相關文件，保持文件精簡且專注
- **代理選擇**：為任務使用適當的代理
- **迭代開發**：在小的、專注的任務中工作
- **文件組織**：保持乾淨的項目結構
- **定期提交**：經常保存您的工作

## 測試架構師（QA 代理）

### 概述

BMad 中的 QA 代理不僅僅是"高級開發者審查者" - 它是在測試策略、質量門檢和基於風險的測試方面具有深厚專業知識的**測試架構師**。名為 Quinn，此代理在質量事務上提供諮詢權威，同時在安全時積極改進代碼。

#### 快速開始（基本命令）

@qa *risk {story}       # 在開發前評估風險
@qa *design {story}     # 創建測試策略
@qa *trace {story}      # 在開發期間驗證測試覆蓋率
@qa *nfr {story}        # 檢查質量屬性
@qa *review {story}     # 全面評估 → 寫門檢

#### 命令別名（測試架構師）

文檔使用簡短形式以方便使用。兩種樣式都有效：

*risk    → *risk-profile
*design  → *test-design
*nfr     → *nfr-assess
*trace   → *trace-requirements (或只是 *trace)
*review  → *review
*gate    → *gate

### 核心能力

#### 1. 風險分析（`*risk`）

**何時：** 故事草稿後，開發開始前（最早介入點）

識別和評估實現風險：

- **類別**：技術、安全、性能、數據、業務、運營
- **評分**：概率 × 影響分析（1-9 分制）
- **緩解**：每個已識別風險的具體策略
- **門檢影響**：風險 ≥9 觸發 FAIL，≥6 觸發 CONCERNS（參見 `tasks/risk-profile.md` 獲取權威規則）

#### 2. 測試設計（`*design`）

**何時：** 故事草稿後，開發開始前（指導要寫什麼測試）

創建全面的測試策略，包括：

- 每個驗收標準的測試場景
- 適當的測試級別建議（單元 vs 集成 vs E2E）
- 基於風險的優先級（P0/P1/P2）
- 測試數據需求和模擬策略
- CI/CD 集成的執行策略

**示例輸出：**

test_summary:
  total: 24
  by_level:
    unit: 15
    integration: 7
    e2e: 2
  by_priority:
    P0: 8 # 必須有 - 關聯到關鍵風險
    P1: 10 # 應該有 - 中等風險
    P2: 6 # 最好有 - 低風險

#### 3. 需求追蹤（`*trace`）

**何時：** 開發期間（中期實現檢查點）

將需求映射到測試覆蓋率：

- 記錄哪些測試驗證每個驗收標準
- 使用 Given-When-Then 以獲得清晰度（僅文檔，非 BDD 代碼）
- 識別具有嚴重性評級的覆蓋率差距
- 為審計目的創建可追溯性矩陣

#### 4. NFR 評估（`*nfr`）

**何時：** 開發期間或早期審查（驗證質量屬性）

驗證非功能需求：

- **核心四項**：安全性、性能、可靠性、可維護性
- **基於證據**：尋找實際實現證明
- **門檢集成**：NFR 失敗直接影響質量門檢

#### 5. 全面測試架構審查（`*review`）

**何時：** 開發完成後，故事標記為"準備審查"

當您運行 `@qa *review {story}` 時，Quinn 執行：

- **需求可追溯性**：將每個驗收標準映射到其驗證測試
- **測試級別分析**：確保在單元、集成和 E2E 級別進行適當測試
- **覆蓋率評估**：識別差距和冗余測試覆蓋率
- **積極重構**：在安全時直接改進代碼質量
- **質量門檢決定**：根據發現發出 PASS/CONCERNS/FAIL 狀態

#### 6. 質量門檢（`*gate`）

**何時：** 審查修復後或需要更新門檢狀態時

管理質量門檢決定：

- **確定性規則**：PASS/CONCERNS/FAIL 的明確標準
- **平行權威**：QA 擁有 `docs/qa/gates/` 中的門檢文件
- **諮詢性質**：提供建議，不阻止
- **豁免支持**：記錄接受的風險

**注意：** 門檢是諮詢性的；團隊選擇其質量標準。WAIVED 需要原因、批准者和到期日期。參見 `templates/qa-gate-tmpl.yaml` 的架構和 `tasks/review-story.md`（門檢規則）以及 `tasks/risk-profile.md` 的評分。

### 與測試架構師合作

#### 與 BMad 工作流程的集成

測試架構師在整個開發生命周期中提供價值。以下是何時以及如何利用每種能力：

| **階段** | **命令** | **何時使用** | **價值** | **輸出** |
| ---------- | -------- | ------------ | -------------- | ------------------------------------------------------------- |
| **故事起草** | `*risk` | SM 起草故事後 | 及早識別陷阱 | `docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md` |
| | `*design` | 風險評估後 | 指導開發測試策略 | `docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md` |
| **開發** | `*trace` | 實現中期 | 驗證測試覆蓋率 | `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md` |
| | `*nfr` | 構建功能時 | 及早捕獲質量問題 | `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md` |
| **審查** | `*review` | 故事標記為完成 | 全面質量評估 | 故事中的 QA 結果 + 門檢文件 |
| **審查後** | `*gate` | 修復問題後 | 更新質量決定 | 更新的 `docs/qa/gates/{epic}.{story}-{slug}.yml` |

#### 示例命令

# 規劃階段 - 在開發開始之前運行這些
@qa *risk {draft-story}     # 可能出什麼問題？
@qa *design {draft-story}   # 我們應該寫什麼測試？

# 開發階段 - 在編碼期間運行這些
@qa *trace {story}          # 我們在測試所有內容嗎？
@qa *nfr {story}            # 我們是否達到質量標準？

# 審查階段 - 開發完成時運行
@qa *review {story}         # 全面評估 + 重構

# 審查後 - 解決問題後運行
@qa *gate {story}           # 更新門檢狀態

### 強制執行的質量標準

Quinn 強制執行這些測試質量原則：

- **無不穩定測試**：通過適當的異步處理確保可靠性
- **無硬等待**：僅動態等待策略
- **無狀態且並行安全**：測試獨立運行
- **自清理**：測試管理自己的測試數據
- **適當的測試級別**：邏輯單元測試、交互集成測試、旅程 E2E 測試
- **明確斷言**：將斷言保留在測試中，而不是幫助程序中

### 門檢狀態含義

- **PASS**：滿足所有關鍵需求，無阻塞問題
- **CONCERNS**：發現非關鍵問題，團隊應審查
- **FAIL**：應該解決的關鍵問題（安全風險、缺少 P0 測試）
- **WAIVED**：問題已確認但被團隊明確接受

### 特殊情況

**高風險故事：**

- 始終在開發開始前運行 `*risk` 和 `*design`
- 考慮開發中期的 `*trace` 和 `*nfr` 檢查點

**複雜集成：**

- 在開發期間運行 `*trace` 以確保所有集成點都經過測試
- 跟進 `*nfr` 以驗證跨集成的性能

**性能關鍵：**

- 在開發期間早期且經常運行 `*nfr`
- 不要等到審查時才發現性能問題

**棕地/遺留代碼：**

- 從 `*risk` 開始識別回歸危險
- 使用 `*review` 時額外關注向後兼容性

### 最佳實踐

- **早期參與**：在故事起草期間運行 `*design` 和 `*risk`
- **基於風險的焦點**：讓風險分數驅動測試優先級
- **迭代改進**：使用 QA 反饋改進未來故事
- **門檢透明度**：與團隊分享門檢決定
- **持續學習**：QA 記錄模式以供團隊知識分享
- **棕地關懷**：在現有系統中特別注意回歸風險

### 輸出路徑參考

測試架構師輸出存儲位置的快速參考：

*risk-profile  → docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
*test-design   → docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
*trace         → docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
*nfr-assess    → docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
*review        → 故事中的 QA 結果部分 + 門檢文件參考
*gate          → docs/qa/gates/{epic}.{story}-{slug}.yml

## 技術偏好系統

BMad 包含通過位於 `.bmad-core/data/` 中的 `technical-preferences.md` 文件的個性化系統 - 這可以幫助 PM 和架構師偏向於推薦您對設計模式、技術選擇或您想放在這裡的任何其他內容的偏好。

### 與 Web 包一起使用

在創建自定義 web 包或上傳到 AI 平台時，包含您的 `technical-preferences.md` 內容，以確保代理從任何對話開始就有您的偏好。

## 核心配置

`bmad-core/core-config.yaml` 文件是一個關鍵配置，使 BMad 能夠與不同的項目結構無縫工作，將來會提供更多選項。目前最重要的是 yaml 中的 devLoadAlwaysFiles 列表部分。

### 開發者上下文文件

定義開發代理應該始終加載的文件：

devLoadAlwaysFiles:
  - docs/architecture/coding-standards.md
  - docs/architecture/tech-stack.md
  - docs/architecture/project-structure.md

您需要從分片架構中驗證這些文檔存在，它們盡可能精簡，並包含您希望開發代理始終加載到其上下文中的確切信息。這些是代理將遵循的規則。

隨著項目的增長和代碼開始構建一致的模式，編碼標準應該減少到只包含代理仍需要強制執行的標準。代理將查看文件中的周圍代碼來推斷與當前任務相關的編碼標準。

## 獲得幫助

- **Discord 社區**：[加入 Discord](https://discord.gg/gk8jAdXWmj)
- **GitHub 問題**：[報告錯誤](https://github.com/bmadcode/bmad-method/issues)
- **文檔**：[瀏覽文檔](https://github.com/bmadcode/bmad-method/docs)
- **YouTube**：[BMadCode 頻道](https://www.youtube.com/@BMadCode)

## 結論

記住：BMad 旨在增強您的開發過程，而不是取代您的專業知識。將其用作強大的工具來加速您的項目，同時保持對設計決策和實現細節的控制。