---
source: ../../../core/forward-derivation-standards.md
source_version: 1.2.0
translation_version: 1.2.0
last_synced: 2026-03-18
status: current
---

# 正向推演標準 | Forward Derivation Standards

**版本**: 1.2.0
**最後更新**: 2026-03-18
**適用範圍**: 所有使用規格驅動開發的專案

> **語言**: [English](../../../core/forward-derivation-standards.md) | 繁體中文

---

## 目的

本規範定義正向推演的原則和工作流程——從已批准的 SDD 規格自動生成 BDD 場景、TDD 測試骨架和 ATDD 驗收測試。正向推演與[反向工程標準](reverse-engineering-standards.md)互補，形成對稱的推演系統。

**主要優點**：
- 一致的測試結構與規格對齊
- 從需求到測試的可追溯性（@SPEC-XXX、@AC-N 標籤）
- 從已批准規格更快啟動 TDD
- 減少手動轉換錯誤

---

## 正向推演工作流程

```
┌──────────────────────────────────────────────────────────────────────────┐
│                          正向推演工作流程                                   │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌───────────┐  │
│  │ 解析 SPEC   │───▶│ 提取 AC     │───▶│ 生成 BDD   │───▶│ 生成      │  │
│  │             │    │             │    │             │    │ TDD/ATDD  │  │
│  └─────────────┘    └─────────────┘    └─────────────┘    └───────────┘  │
│        │                  │                  │                  │        │
│        │                  │                  │                  ▼        │
│        │                  │                  │         ┌───────────────┐ │
│        │                  │                  │         │   人類審查     │ │
│        │                  │                  │         └───────────────┘ │
│        │                  │                  │                  │        │
│        ▼                  ▼                  ▼                  ▼        │
│   [來源]            [已解析]           [已生成]          [已審查]        │
│   SPEC-XXX.md       AC 列表           .feature/.test    可使用          │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

### 工作流程階段

| 階段 | 描述 | 輸出 | 確定性等級 |
|------|------|------|-----------|
| **解析 SPEC** | 讀取已批准的規格文件 | SPEC 元資料、區塊 | [來源] |
| **提取 AC** | 解析驗收條件（GWT 或條列） | 結構化 AC 列表 | [推演] |
| **生成 BDD** | 將 AC 轉換為 Gherkin 場景 | .feature 檔案 | [生成] |
| **生成 TDD** | 從 AC 建立測試骨架 | 帶 TODO 的測試檔案 | [生成] |
| **生成 ATDD** | 建立驗收測試表格 | Markdown 測試表格 | [生成] |
| **人類審查** | 驗證生成的輸出 | 批准的測試結構 | [已審查] |

---

## 核心原則

### 1. 規格限定生成

**規則**：只推演規格中存在的內容。不添加 AC 未明確定義的功能、場景或測試。

**正確示範**：
```markdown
# SPEC AC
- [ ] 使用者可以使用電子郵件和密碼登入

# 生成的 BDD（正確）
Scenario: 使用者以電子郵件和密碼登入
```

**錯誤示範**：
```markdown
# 生成的 BDD（錯誤 - 超出規格範圍）
Scenario: 使用者以電子郵件和密碼登入
Scenario: 使用者以社群帳號登入  # <-- 不在 AC 中
Scenario: 使用者密碼恢復       # <-- 不在 AC 中
```

### 2. 反幻覺合規

**規則**：本規範嚴格遵循[反幻覺標準](anti-hallucination.md)：

- **1:1 對應**：每個 AC 產生恰好一個場景/測試群組
- **禁止捏造**：不發明驗收條件或測試案例
- **來源標註**：所有生成項目標註來源 SPEC 和 AC 編號

**反幻覺檢查**：
```
輸入：SPEC 有 N 個驗收條件
輸出：恰好 N 個場景（BDD）、N 個測試群組（TDD）、N 個驗收表格（ATDD）

若輸出數量 ≠ 輸入數量 → 違規
```

### 3. 來源標註

**規則**：每個生成項目必須包含可追溯性：

```gherkin
# BDD 範例
# Generated from: specs/SPEC-001.md
# AC: AC-1

@SPEC-001 @AC-1
Scenario: 使用者以有效憑證登入
```

```typescript
// TDD 範例
/**
 * Generated from: specs/SPEC-001.md
 * AC: AC-1
 */
describe('AC-1: 使用者以有效憑證登入', () => {
```

### 4. 確定性標籤

使用這些標籤標示推演確定性：

| 標籤 | 定義 | 範例 |
|------|------|------|
| `[來源]` | 直接來自 SPEC 的內容 | 功能標題、AC 文字 |
| `[推演]` | 從 SPEC 內容轉換 | 從條列 AC 推演的 GWT |
| `[生成]` | AI 生成的結構 | 測試骨架、TODO 註解 |
| `[TODO]` | 需要人類實作 | 測試斷言、步驟定義 |

---

## 輸入格式要求

### 支援的 AC 格式

#### 格式 1：Given-When-Then（推薦）

```markdown
### AC-1: 使用者登入
**Given** 已註冊的使用者有有效憑證
**When** 使用者提交含電子郵件和密碼的登入表單
**Then** 使用者被導向儀表板
**And** 建立工作階段權杖
```

#### 格式 2：條列式

```markdown
### AC-1: 使用者登入
- 使用者可以使用電子郵件和密碼登入
- 登入成功導向儀表板
- 無效憑證顯示錯誤訊息
```

#### 格式 3：勾選清單

```markdown
## 驗收條件
- [ ] 使用者可以使用電子郵件和密碼登入
- [ ] 登入成功時建立工作階段
- [ ] 無效憑證時顯示錯誤訊息
```

---

## 輸出格式

### BDD 輸出（.feature）

```gherkin
# Generated from: specs/SPEC-001.md
# Generator: forward-derivation v1.0.0
# Generated at: 2026-01-19T10:00:00Z

@SPEC-001
Feature: 使用者認證
  作為使用者
  我想要登入系統
  以便存取我的儀表板

  @AC-1 @happy-path
  Scenario: 使用者以有效憑證登入
    # [來源] 來自 SPEC-001 AC-1
    Given 已註冊的使用者有有效憑證
    When 使用者提交登入表單
    Then 使用者被導向儀表板

  @AC-2 @error-handling
  Scenario: 無效憑證登入失敗
    # [來源] 來自 SPEC-001 AC-2
    Given 使用者有無效憑證
    When 使用者提交登入表單
    Then 顯示錯誤訊息
```

### TDD 輸出（.test.ts）

```typescript
/**
 * Tests for SPEC-001: 使用者認證
 * Generated from: specs/SPEC-001.md
 * Generated at: 2026-01-19T10:00:00Z
 * AC Coverage: AC-1, AC-2
 *
 * [生成] 此檔案包含測試骨架。
 * [TODO] 實作測試邏輯和斷言。
 */

describe('SPEC-001: 使用者認證', () => {
  /**
   * AC-1: 使用者以有效憑證登入
   * [來源] specs/SPEC-001.md#AC-1
   */
  describe('AC-1: 使用者以有效憑證登入', () => {
    it('should redirect to dashboard on successful login', async () => {
      // Arrange
      // [TODO] 設定已註冊使用者和有效憑證

      // Act
      // [TODO] 提交登入表單

      // Assert
      // [TODO] 驗證導向儀表板
      expect(true).toBe(true); // Placeholder
    });
  });
});
```

### ATDD 輸出（acceptance.md）

```markdown
# SPEC-001 驗收測試

**規格**: [SPEC-001](../specs/SPEC-001.md)
**生成時間**: 2026-01-19
**狀態**: 待審查

---

## AT-001: 使用者以有效憑證登入

**來源**: SPEC-001 的 AC-1

| 步驟 | 動作 | 預期結果 | 通過/失敗 |
|------|------|----------|-----------|
| 1 | 導航到登入頁面 | 顯示登入表單 | [ ] |
| 2 | 輸入有效電子郵件 | 欄位接受輸入 | [ ] |
| 3 | 輸入有效密碼 | 欄位接受輸入（遮罩） | [ ] |
| 4 | 點擊「登入」按鈕 | 表單已提交 | [ ] |
| 5 | 驗證導向 | 使用者在儀表板頁面 | [ ] |

**前置條件**: 系統中存在使用者帳號

**測試人員**: _______________
**日期**: _______________
**結果**: [ ] 通過 / [ ] 失敗
```

---

## 條列式轉 GWT 轉換

當 AC 以條列點撰寫時，使用此模式轉換：

### 轉換規則

| 條列模式 | 對應到 | 範例 |
|----------|--------|------|
| 條件/狀態 | Given | 「使用者已登入」→ Given 使用者已登入 |
| 使用者動作 | When | 「使用者點擊按鈕」→ When 使用者點擊按鈕 |
| 系統回應 | Then | 「顯示訊息」→ Then 顯示訊息 |
| 「可以/應該/必須」 | When + Then | 「使用者可以刪除項目」→ When 使用者刪除項目 Then 項目已移除 |

---

## 與開發方法論的整合

### 正向推演管道

```
┌───────────────────────────────────────────────────────────────────────┐
│                        對稱推演系統                                     │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  反向工程                                 正向推演                      │
│  (程式碼 → 規格)                          (規格 → 測試)                 │
│                                                                       │
│  ┌───────────────┐                      ┌───────────────┐            │
│  │ 現有程式碼     │                      │ 已批准 SPEC   │            │
│  └───────┬───────┘                      └───────┬───────┘            │
│          │                                      │                     │
│          ▼                                      ▼                     │
│  ┌───────────────┐                      ┌───────────────┐            │
│  │ /reverse-spec │                      │  /derive-bdd  │            │
│  │ /reverse-bdd  │◀─────SPEC-XXX───────▶│  /derive-tdd  │            │
│  │ /reverse-tdd  │                      │  /derive-atdd │            │
│  └───────┬───────┘                      └───────┬───────┘            │
│          │                                      │                     │
│          ▼                                      ▼                     │
│  ┌───────────────┐                      ┌───────────────┐            │
│  │ 初稿 SPEC     │                      │ .feature      │            │
│  │ [已確認]      │                      │ .test.ts      │            │
│  │ [推斷]        │                      │ acceptance.md │            │
│  │ [未知]        │                      │ [生成]        │            │
│  └───────────────┘                      └───────────────┘            │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘
```

### 與整合流程方法論

正向推演位於 `spec-review` 和 `discovery` 階段之間：

```yaml
spec-review → forward-derivation → discovery
```

1. **規格審查 (SDD)**：規格已批准
2. **正向推演**：自動生成 BDD 場景、TDD 骨架
3. **探索 (BDD)**：與利害關係人審查和精煉生成的場景
4. **TDD 紅燈**：使用生成的骨架開始實作測試

---

## 終端投影：使用者指南

推演鏈不止於測試。**使用者指南是同一條鏈的終端投影**——E2E／旅程測試以機器驗證的那條作業流程，其供人閱讀的視圖。「使用者讀到的操作步驟」與「E2E 實際驗證的行為」因此成為一個被維持的不變量。

- **單一真實來源**：SPEC 的驗收條件（AC）。所有下游產物——BDD 場景、TDD／IT／E2E 骨架、ATDD 表格、契約，**以及使用者指南**——都是同一條 AC 主幹的投影。使用者指南不是另一個要互相對照的來源，而是又一個投影。
- **僅限 user-facing AC**：唯有**終端使用者可直接觀察或操作**的 AC（UI 流程、CLI 指令、對外 API 的使用者語意）才需要使用者指南步驟。純內部 AC（重構、內部模組契約、效能門檻、安全內控）無使用者指南義務。**判不準時一律歸 user-facing**——保守預設；必須明確標記才能排除。
- **共用編號（`T-NNN`）**：每個使用者指南步驟標 `T-NNN`，且該 `T-NNN` 必須是某個真實 journey／E2E 測試的 id。使用者指南與 E2E 套件是同一作業流程的兩個投影、共用一把尺。模稜兩可或未標記一律報為**未覆蓋**（寧可冗餘不要遺漏）。
  - ✅ 使用者指南步驟 `T-012「建立專案」` ↔ journey spec 中的 E2E 測試 `T-012`。
  - ❌ 使用者指南自造 `UG-3` 卻無對應測試 → drift，報為未覆蓋。
- **Drift 反例**：使用者指南寫「2-click checkout」、E2E 卻仍驗「3-step payment」——沒有共用編號就無人察覺。共用 `T-NNN` 把這種 drift 變成被報出的覆蓋缺口。

### 單一主幹原則（非平行對照）

測試與文件來源是**同一條 AC 主幹的多層投影**，不是互相對照的獨立真實來源。TDD／IT／E2E 是同一主幹的金字塔**層級**（依 AC 性質分層），非彼此競爭的來源。兩兩對照 N 個來源（N×N）會滋生 drift；把每個產物投影回單一 AC 主幹（N×1）則消除它。

> **規則**：每個測試或文件產物都必須回溯到某個 AC。另立**平行編號體系**——一條脫離 AC 主幹的第二套 `T-NNN` 系列——即為違規。只有一把尺：AC 主幹，且 `T-NNN` 由 journey／E2E 測試與使用者指南共用。

---

## 命令

### 命令參考

| 命令 | 輸入 | 輸出 | 目的 |
|------|------|------|------|
| `/derive-bdd` | SPEC-XXX.md | .feature | AC → Gherkin 場景 |
| `/derive-tdd` | SPEC-XXX.md | .test.ts | AC → 測試骨架 |
| `/derive-atdd` | SPEC-XXX.md | acceptance.md | AC → 驗收測試表格 |
| `/derive-all` | SPEC-XXX.md | 以上全部 | 完整推演管道 |

### 命令參數

| 參數 | 類型 | 預設值 | 描述 |
|------|------|--------|------|
| `--lang` | string | typescript | 目標語言: ts, js, python, java, go |
| `--framework` | string | vitest | 框架: vitest, jest, pytest, junit, go-test |
| `--output-dir` | string | ./generated | 輸出目錄 |
| `--dry-run` | boolean | false | 預覽不建立檔案 |

### 使用範例

```bash
# 從規格生成 BDD 場景
/derive-bdd specs/SPEC-001.md

# 使用 Python/pytest 生成 TDD 測試骨架
/derive-tdd specs/SPEC-001.md --lang python --framework pytest

# 生成所有輸出
/derive-all specs/SPEC-001.md --output-dir ./generated

# 預覽不建立檔案
/derive-all specs/SPEC-001.md --dry-run
```

---

## Pipeline 整合

### 自動 TDD 轉換

當正向推演由自動化 Pipeline 觸發時（參見 [Pipeline 整合標準](pipeline-integration-standards.md)），以下規則適用於轉換至 TDD 循環：

#### Auto-TDD 進入規則

| 規則 | 說明 |
|------|------|
| **推演完整性** | 所有推演輸出（BDD、TDD、ATDD）必須在進入 TDD 前完成生成 |
| **RED 狀態初始化** | Pipeline 在生成測試骨架後將 TDD 狀態設為 RED |
| **測試骨架驗證** | 生成的測試檔案必須能編譯/解析無誤後才能進入 RED |
| **AC 計數驗證** | 進入轉換前驗證輸出測試數量與 AC 數量匹配 |

#### Pipeline Hooks

推演步驟可透過 Pipeline 事件自動觸發：

| Hook | 觸發條件 | 動作 |
|------|---------|------|
| `on-spec-approved` | Spec 狀態變更為「已批准」 | 啟動推演 Pipeline |
| `on-derivation-complete` | 所有推演輸出已生成 | 轉換至 TDD RED 階段 |
| `on-tdd-green` | 所有推演測試通過 | 觸發審查階段 |

#### Auto-TDD 進入工作流程

```
┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ Spec Approved│───▶│  Derive All  │───▶│ Verify Count │───▶│  TDD RED     │
│ (hook)       │    │  BDD+TDD+ATDD│    │ AC = Tests   │    │  (auto-set)  │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
```

1. **Spec 批准**：Pipeline 偵測到 Spec 批准（透過 hook 或輪詢）
2. **完整推演**：Pipeline 以專案配置的語言/框架執行 `/derive-all`
3. **計數驗證**：Pipeline 驗證輸出數量與 AC 數量匹配（反幻覺）
4. **RED 狀態**：Pipeline 將 TDD 狀態設為 RED；測試骨架存在但 assertion 為 [TODO]

#### 與 Pipeline 階段的整合

正向推演對應 [Pipeline 整合標準](pipeline-integration-standards.md) 6 階段模型中的 **DERIVE** 階段：

| Pipeline 階段 | 正向推演角色 |
|--------------|------------|
| SPEC | 輸入：已批准的規格 |
| **DERIVE** | 執行：解析 AC → 生成 BDD/TDD/ATDD 輸出 |
| BUILD | 輸出：測試骨架進入 TDD RED→GREEN 循環 |

---

## 應避免的反模式

### 生成反模式

| 反模式 | 影響 | 正確做法 |
|--------|------|----------|
| **添加額外場景** | 測試膨脹、誤導覆蓋率 | 嚴格 1:1 AC 對應 |
| **發明測試案例** | 虛假信心 | 只從明確的 AC 推演 |
| **跳過來源標註** | 失去可追溯性 | 永遠包含 @SPEC-XXX、@AC-N |
| **過度指定步驟** | 脆弱的測試 | 保持步驟在業務層級 |
| **缺少 TODO 標記** | 實作不完整 | 標記所有生成程式碼為 [TODO] |

### 流程反模式

| 反模式 | 影響 | 正確做法 |
|--------|------|----------|
| **從草稿 SPEC 推演** | 無效輸出 | 只使用已批准的規格 |
| **跳過人類審查** | 品質問題 | 永遠審查生成的輸出 |
| **將骨架視為完整** | 缺少斷言 | 填寫 [TODO] 區塊 |
| **忽略語言慣例** | 不一致的程式碼 | 使用適當的語言範本 |

---

## 最佳實踐

### 應該做的

- ✅ 只從已批准的規格推演
- ✅ 維持嚴格的 1:1 AC 到輸出對應
- ✅ 在所有輸出中包含來源標註
- ✅ 使用 [TODO] 標記需要實作的區塊
- ✅ 使用前審查生成的輸出
- ✅ 保持生成的步驟在業務/領域層級
- ✅ 使用適當的語言/框架範本

### 不應該做的

- ❌ 添加 AC 未定義的場景
- ❌ 從草稿或未批准的規格推演
- ❌ 跳過對生成輸出的人類審查
- ❌ 將生成的骨架視為完整測試
- ❌ 移除來源標註註解
- ❌ 在生成的程式碼中過度指定實作細節

---

## 相關規範

- [反向工程標準](reverse-engineering-standards.md) - 對稱對應（程式碼 → 規格）
- [規格驅動開發](spec-driven-development.md) - 輸入規格格式
- [行為驅動開發](../../../core/behavior-driven-development.md) - BDD 輸出格式
- [測試驅動開發](test-driven-development.md) - TDD 輸出用法
- [驗收測試驅動開發](../../../core/acceptance-test-driven-development.md) - ATDD 輸出格式
- [反幻覺指南](anti-hallucination.md) - 生成合規

---

## 版本歷史

| 版本 | 日期 | 變更 |
|------|------|------|
| 1.2.0 | 2026-03-18 | 新增：Pipeline 整合章節 — auto-TDD 轉換、pipeline hooks、auto-TDD 進入工作流程 |
| 1.0.0 | 2026-01-19 | 初始發布 |

---

## 授權

本規範採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權。
