universal-dev-standards 5.15.1 → 5.16.0

package/bundled/locales/zh-TW/skills/spec-derivation/guide.md

@@ -0,0 +1,476 @@
+---
+source: ../../../../skills/spec-derivation/guide.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 218670e49db0
+status: current
+scope: partial
+description: |
+  從已核准的 SDD 規格推演 BDD 場景與 TDD 測試骨架。
+  ATDD 驗收測試表格為選用輸出，供特殊需求使用。
+  使用時機：規格已核准、開始 BDD/TDD 實作、產生測試結構。
+  關鍵字：forward derivation、spec to test、BDD generation、TDD skeleton、test derivation、正向推演、規格轉測試、測試生成。
+---
+
+# 正向推演指南（Forward Derivation Guide）
+
+> **語言**：[English](../../../../skills/spec-derivation/guide.md) | 繁體中文
+
+**版本**：2.0.0
+**最後更新**：2026-01-25
+**適用範圍**：Claude Code Skills
+
+> **核心標準**：此 skill 實作 [Forward Derivation Standards](../../core/forward-derivation-standards.md)。如需任何 AI 工具皆可存取的完整方法論文件，請參閱該核心標準。
+
+---
+
+## 目的
+
+此 skill 引導你從已核准的 SDD 規格推演 BDD 場景與 TDD 測試骨架，並嚴格遵循反幻覺（Anti-Hallucination）標準。
+
+> **注意**：ATDD 測試表格為選用，可透過 `/derive-atdd` 取得。BDD 場景本身即可作為可執行的驗收測試，因此在多數情境下 ATDD 表格屬於冗餘。
+
+正向推演（Forward Derivation）是 [逆向工程（Reverse Engineering）](../reverse-engineer/SKILL.md) 的對稱對應：
+- **逆向工程（Reverse Engineering）**：程式碼 → 規格
+- **正向推演（Forward Derivation）**：規格 → 測試
+
+## 快速參考
+
+### 正向推演工作流程
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│              Forward Derivation Workflow                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1️⃣  SPEC Parsing (AI Automated)                               │
+│      ├─ Read approved specification                             │
+│      ├─ Extract Acceptance Criteria (GWT or bullet)             │
+│      └─ Validate SPEC structure and completeness                │
+│                                                                 │
+│  2️⃣  Derivation (AI Automated)                                 │
+│      ├─ AC → BDD Gherkin scenarios                             │
+│      ├─ AC → TDD test skeletons with TODOs                     │
+│      └─ (Optional) AC → ATDD acceptance test tables            │
+│                                                                 │
+│  3️⃣  Human Review (Required)                                   │
+│      ├─ Verify generated scenarios match AC intent              │
+│      ├─ Fill in [TODO] sections                                │
+│      └─ Refine step definitions if needed                      │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 指令總覽
+
+| 指令 | 輸入 | 輸出 | 目的 |
+|---------|-------|--------|---------|
+| `/derive-bdd` | SPEC-XXX.md | .feature | AC → Gherkin 場景 |
+| `/derive-tdd` | SPEC-XXX.md | .test.ts | AC → 測試骨架 |
+| `/derive-all` | SPEC-XXX.md | .feature + .test.ts | 完整推演管線 |
+| `/derive-atdd` | SPEC-XXX.md | acceptance.md | AC → 驗收測試表格（選用） |
+
+## 核心原則
+
+### 1. 受規格約束的生成（Spec-Bounded Generation）
+
+**至關重要**：只推演規格中存在的內容。絕不新增超出 Acceptance Criteria 明確定義範圍的場景、測試或功能。
+
+```
+# Anti-Hallucination Rule
+Input:  SPEC with N Acceptance Criteria
+Output: Exactly N scenarios (BDD)
+        Exactly N test groups (TDD)
+        Exactly N acceptance tests (ATDD, if requested)
+
+If output count ≠ input count → VIOLATION
+```
+
+### 2. 來源歸屬（Source Attribution）
+
+每個生成的項目都「必須」包含 traceability：
+
+```gherkin
+# Generated from: specs/SPEC-001.md
+# AC: AC-1
+
+@SPEC-001 @AC-1
+Scenario: User login with valid credentials
+```
+
+### 3. 推演標籤（Derivation Tags，來自統一標籤系統）
+
+此 skill 使用 **推演標籤（Derivation Tags）** 從規格生成新內容。完整的標籤參考請見 [Anti-Hallucination Standards](../../core/anti-hallucination.md#certainty-classification-tags)。
+
+| 標籤 | 使用時機 | 範例 |
+|-----|----------|---------|
+| `[Source]` | 直接取自 SPEC 的內容 | 功能標題、AC 文字 |
+| `[Derived]` | 從 SPEC 內容轉換而來 | 由 bullet AC 轉成 GWT |
+| `[Generated]` | AI 生成的結構 | 測試骨架 |
+| `[TODO]` | 需要人工實作 | 斷言、step definition |
+
+## 工作流程階段
+
+### 階段 1：SPEC 解析
+
+**輸入**：已核准的規格檔案
+**輸出**：結構化的 Acceptance Criteria 清單
+
+**動作**：
+1. 讀取規格檔案
+2. 辨識 Acceptance Criteria 區段
+3. 解析 AC 格式（Given-When-Then 或 Bullet）
+4. 驗證 AC 完整性
+
+**驗證檢查清單**：
+- [ ] SPEC 狀態為「Approved」或「Ready」
+- [ ] Acceptance Criteria 區段存在
+- [ ] 每個 AC 都有唯一識別碼（AC-1、AC-2 等）
+- [ ] AC 格式可解析（GWT 或 bullet）
+
+### 階段 2：BDD 推演
+
+**輸入**：已解析的 Acceptance Criteria
+**輸出**：Gherkin .feature 檔案
+
+**轉換規則**：
+
+| AC 格式 | 轉換方式 |
+|-----------|----------------|
+| Given-When-Then | 直接對應到 Gherkin |
+| Bullet points | 使用 GWT 模式比對轉換 |
+| Checklist | 條件 → Given、動作 → When、結果 → Then |
+
+**範例**：
+```markdown
+# Input AC (Bullet)
+- [ ] User can login with email and password
+- [ ] Login shows error for invalid credentials
+```
+
+```gherkin
+# Output BDD
+@SPEC-001 @AC-1
+Scenario: User login with email and password
+  Given a user with valid credentials
+  When the user submits login form
+  Then the user is logged in successfully
+
+@SPEC-001 @AC-2
+Scenario: Login shows error for invalid credentials
+  Given a user with invalid credentials
+  When the user submits login form
+  Then an error message is displayed
+```
+
+### 階段 3：TDD 推演
+
+**輸入**：已解析的 Acceptance Criteria
+**輸出**：測試骨架檔案
+
+**動作**：
+1. 為 SPEC 建立 describe 區塊
+2. 為每個 AC 建立 describe 區塊
+3. 以具描述性的名稱產生 it 區塊
+4. 加入帶有 TODO 註解的 AAA 結構
+5. 包含占位用的斷言（placeholder assertions）
+
+**參數**：
+| 參數 | 選項 | 預設 |
+|-----------|---------|---------|
+| `--lang` | typescript、javascript、python、java、go | typescript |
+| `--framework` | vitest、jest、pytest、junit、go-test | vitest |
+
+### 階段 4：ATDD 推演（選用）
+
+> **注意**：ATDD 測試表格為選用。BDD 場景本身即可作為可執行的驗收測試。僅在以下情況使用 ATDD 表格：
+> - 需要人工測試流程
+> - 利害關係人偏好表格式的測試文件
+> - 法規遵循要求特定的測試證據格式
+
+**輸入**：已解析的 Acceptance Criteria
+**輸出**：驗收測試表格文件
+
+**動作**：
+1. 為每個 AC 建立測試表格
+2. 產生逐步動作欄位
+3. 加入預期結果欄位
+4. 包含 Pass/Fail 勾選框
+5. 加入測試員簽核區段
+
+### 階段 5：人工審查
+
+**輸入**：生成的檔案
+**輸出**：經審查與精修的檔案
+
+**審查檢查清單**：
+- [ ] 生成的場景符合 AC 意圖
+- [ ] 沒有超出 AC 數量的多餘場景
+- [ ] 來源歸屬正確
+- [ ] 已標出 [TODO] 區段供實作
+- [ ] step 語言為業務層級（非技術性）
+
+## 輸出格式
+
+### BDD Feature 檔案
+
+```gherkin
+# Generated from: specs/SPEC-001.md
+# Generator: /derive-bdd v1.0.0
+# Generated at: 2026-01-19T10:00:00Z
+
+@SPEC-001
+Feature: User Authentication
+  [Source] From SPEC-001 Summary
+
+  @AC-1 @happy-path
+  Scenario: User login with valid credentials
+    # [Source] From SPEC-001 AC-1
+    Given a registered user with valid credentials
+    When the user submits login form
+    Then the user is redirected to dashboard
+
+  @AC-2 @error-handling
+  Scenario: Login fails with invalid credentials
+    # [Source] From SPEC-001 AC-2
+    Given a user with invalid credentials
+    When the user submits login form
+    Then an error message is displayed
+```
+
+### TDD 測試骨架
+
+```typescript
+/**
+ * Tests for SPEC-001: User Authentication
+ * Generated from: specs/SPEC-001.md
+ * Generated at: 2026-01-19T10:00:00Z
+ * AC Coverage: AC-1, AC-2
+ */
+
+describe('SPEC-001: User Authentication', () => {
+  describe('AC-1: User login with valid credentials', () => {
+    it('should redirect to dashboard on successful login', async () => {
+      // Arrange
+      // [TODO] Set up registered user with valid credentials
+
+      // Act
+      // [TODO] Submit login form
+
+      // Assert
+      // [TODO] Verify redirect to dashboard
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+
+  describe('AC-2: Login fails with invalid credentials', () => {
+    it('should display error message', async () => {
+      // Arrange
+      // [TODO] Set up user with invalid credentials
+
+      // Act
+      // [TODO] Submit login form
+
+      // Assert
+      // [TODO] Verify error message is displayed
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+});
+```
+
+### ATDD 驗收測試表格（選用）
+
+> 當需要 ATDD 測試表格時，透過 `/derive-atdd` 生成。
+
+```markdown
+# SPEC-001 Acceptance Tests
+
+**Specification**: SPEC-001
+**Generated**: 2026-01-19
+**Status**: Pending
+
+## AT-001: User login with valid credentials
+**Source**: AC-1
+
+| Step | Action | Expected | Pass/Fail |
+|------|--------|----------|-----------|
+| 1 | Navigate to login page | Login form displayed | [ ] |
+| 2 | Enter valid credentials | Fields accept input | [ ] |
+| 3 | Click Login | Form submitted | [ ] |
+| 4 | Verify redirect | Dashboard displayed | [ ] |
+
+**Tester**: _______________
+**Date**: _______________
+**Result**: [ ] Pass / [ ] Fail
+```
+
+## 與其他 Skill 的整合
+
+### 與 /sdd（Spec-Driven Development）
+
+1. 使用 `/sdd` 工作流程完成 SPEC
+2. 透過審查取得 SPEC 核准
+3. 執行 `/derive-all` 產生測試結構
+4. 在 BDD/TDD 工作流程中使用生成的輸出
+
+### 與 /bdd（Behavior-Driven Development）
+
+1. 使用 `/derive-bdd` 產生 BDD 場景
+2. 與利害關係人審查並精修場景
+3. 使用 `/bdd` 繼續進行 BDD 構思
+4. 實作 step definition
+
+### 與 /tdd（Test-Driven Development）
+
+1. 使用 `/derive-tdd` 產生 TDD 骨架
+2. 在 [TODO] 區段填入實際的斷言
+3. 以生成的測試結構進入 TDD Red 階段
+4. 實作程式碼以讓測試通過
+
+### 與整合式流程（Integrated Flow）
+
+正向推演融入整合式流程（Integrated Flow）方法論：
+
+```
+spec-review (approved) → forward-derivation → discovery (BDD)
+                              │
+                              ├─→ .feature files for BDD
+                              └─→ .test.ts skeletons for TDD
+
+Optional: /derive-atdd → acceptance.md for manual testing
+```
+
+## 完整推演管線
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Complete Forward Derivation Pipeline                   │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│   Approved SPEC                                                         │
+│        │                                                                │
+│        ▼                                                                │
+│   /derive-all specs/SPEC-XXX.md                                        │
+│        │                                                                │
+│        ├─→ /derive-bdd                                                  │
+│        │    └─→ features/SPEC-XXX.feature                              │
+│        │                                                                │
+│        └─→ /derive-tdd                                                  │
+│             └─→ tests/SPEC-XXX.test.ts                                 │
+│                                                                         │
+│   Optional: /derive-atdd specs/SPEC-XXX.md                              │
+│        └─→ acceptance/SPEC-XXX-acceptance.md                           │
+│                                                                         │
+│   Human Review                                                          │
+│        │                                                                │
+│        ├─→ Verify 1:1 AC mapping                                       │
+│        ├─→ Fill [TODO] sections                                        │
+│        └─→ Refine step definitions                                     │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 使用範例
+
+```bash
+# Generate BDD scenarios
+/derive-bdd specs/SPEC-001.md
+
+# Generate TDD skeleton with Python/pytest
+/derive-tdd specs/SPEC-001.md --lang python --framework pytest
+
+# Generate all test structures
+/derive-all specs/SPEC-001.md
+
+# Preview without creating files
+/derive-all specs/SPEC-001.md --dry-run
+
+# Specify output directory
+/derive-all specs/SPEC-001.md --output-dir ./generated
+```
+
+## 應避免的反模式（Anti-Patterns）
+
+### ❌ 不要這樣做
+
+1. **新增多餘場景**
+   - 錯誤：SPEC 有 3 個 AC，卻生成 5 個場景
+   - 正確：SPEC 有 3 個 AC，恰好生成 3 個場景
+
+2. **從草稿 SPEC 推演**
+   - 錯誤：對未核准的規格執行 `/derive-all`
+   - 正確：只從已核准的規格推演
+
+3. **略過來源歸屬**
+   - 錯誤：場景沒有 @SPEC-XXX 標籤
+   - 正確：每個場景都標上來源 SPEC 與 AC
+
+4. **過度指定技術細節**
+   - 錯誤：`Given database connection is established using PostgreSQL driver`
+   - 正確：`Given user data exists in the system`
+
+5. **把骨架當成已完成**
+   - 錯誤：未填入 [TODO] 就使用生成的測試
+   - 正確：執行測試前先填完所有 [TODO] 區段
+
+## 最佳實踐
+
+### 該做的（Do's）
+
+- ✅ 只從已核准的規格推演
+- ✅ 維持嚴格的 1:1 AC 對輸出對應
+- ✅ 在所有輸出中包含來源歸屬
+- ✅ 以 [TODO] 標記實作區段
+- ✅ 與利害關係人審查生成的輸出
+- ✅ 讓 step 語言保持在業務層級
+
+### 不該做的（Don'ts）
+
+- ❌ 新增超出 AC 定義範圍的場景
+- ❌ 從草稿或未核准的規格推演
+- ❌ 略過對生成輸出的人工審查
+- ❌ 把生成的骨架當成完整的測試
+- ❌ 移除來源歸屬註解
+- ❌ 過度指定實作細節
+
+---
+
+## 配置偵測
+
+此 skill 會自動偵測專案配置：
+
+1. 檢查既有的 `specs/` 目錄結構
+2. 從 package.json/pyproject.toml 偵測測試框架
+3. 辨識偏好的輸出目錄
+4. 配置語言專屬的範本
+
+---
+
+## 相關標準
+
+- [Forward Derivation Standards](../../core/forward-derivation-standards.md) - **核心方法論標準（主要參考）**
+- [Reverse Engineering Standards](../../core/reverse-engineering-standards.md) - 對稱對應
+- [Spec-Driven Development](../../core/spec-driven-development.md) - 輸入規格格式
+- [Behavior-Driven Development](../../core/behavior-driven-development.md) - BDD 輸出格式
+- [Test-Driven Development](../../core/test-driven-development.md) - TDD 輸出用途
+- [Anti-Hallucination Guidelines](../../core/anti-hallucination.md) - 生成合規性
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|---------|------|---------|
+| 2.0.0 | 2026-01-25 | ATDD 從必要輸出改為選用輸出；/derive-all 現在只輸出 BDD + TDD |
+| 1.1.0 | 2026-01-25 | 新增：對統一標籤系統的參考 |
+| 1.0.0 | 2026-01-19 | 初始發布 |
+
+---
+
+## 授權
+
+此 skill 以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 釋出。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)