universal-dev-standards 5.0.0-rc.8 → 5.0.0

package/bundled/locales/zh-TW/core/acceptance-criteria-traceability.md

@@ -0,0 +1,301 @@
+---
+source: ../../../core/acceptance-criteria-traceability.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-03-18
+status: current
+---
+
+# 驗收標準可追溯性規範
+
+> **語言**: [English](../../../core/acceptance-criteria-traceability.md) | 繁體中文
+
+**適用範圍**: 所有使用規格驅動或測試驅動工作流程的軟體專案
+**Scope**: universal
+
+---
+
+## 概述
+
+驗收標準可追溯性規範定義了如何追蹤驗收標準（AC）、測試實作與覆蓋狀態之間的關係。本規範確保每個 AC 都可被驗證測試，並提供標準化的覆蓋率分析報告格式。
+
+## 參考資料
+
+| 標準 / 來源 | 內容 |
+|------------|------|
+| ISO/IEC/IEEE 29119-3 | 測試文件 — 可追溯性矩陣 |
+| IEEE 830 | 軟體需求規格 — 可追溯性 |
+| ISTQB Foundation | 基於需求的測試 |
+| INVEST 原則 | 驗收標準品質 |
+
+---
+
+## AC 對測試的可追溯性矩陣
+
+### 標準矩陣格式
+
+| AC-ID | 測試檔案 | 測試名稱 | 狀態 | 備注 |
+|-------|---------|---------|------|------|
+| AC-1 | `tests/auth.test.ts` | `should login with valid credentials` | ✅ 已覆蓋 | |
+| AC-2 | `tests/auth.test.ts` | `should reject invalid credentials` | ✅ 已覆蓋 | |
+| AC-3 | — | — | ❌ 未覆蓋 | 被 API 相依性阻擋 |
+| AC-4 | `tests/auth.test.ts` | `should lock account after 5 failures` | ⚠️ 部分覆蓋 | 缺少邊界情況 |
+
+### 矩陣欄位
+
+| 欄位 | 必填 | 說明 |
+|------|------|------|
+| `AC-ID` | 是 | 規格中的唯一識別碼（例如 AC-1、AC-2） |
+| `Test File` | 是（若已覆蓋） | 實作此 AC 的測試檔案路徑 |
+| `Test Name` | 是（若已覆蓋） | 測試案例或 describe 區塊的名稱 |
+| `Status` | 是 | 覆蓋狀態：`covered`、`partial`、`uncovered` |
+| `Notes` | 否 | 補充資訊（阻擋因素、相依性等） |
+
+### 連結慣例
+
+測試 **必須** 使用標準注釋參照其來源 AC：
+
+```typescript
+// TypeScript/JavaScript
+describe('AC-1: User login with valid credentials', () => {
+  // @AC AC-1
+  // @SPEC SPEC-001
+  it('should redirect to dashboard on successful login', () => { ... });
+});
+```
+
+```python
+# Python
+class TestAC1_UserLogin:
+    """AC-1: User login with valid credentials
+    @AC AC-1
+    @SPEC SPEC-001
+    """
+    def test_redirect_to_dashboard(self): ...
+```
+
+```gherkin
+# BDD Feature
+@SPEC-001 @AC-1
+Scenario: User login with valid credentials
+```
+
+---
+
+## 覆蓋狀態定義
+
+### 狀態分類
+
+| 狀態 | 符號 | 定義 | 判斷標準 |
+|------|------|------|---------|
+| **已覆蓋** | ✅ | AC 已完整測試 | AC 中所有條件都有對應的測試斷言 |
+| **部分覆蓋** | ⚠️ | AC 已部分測試 | 部分條件已測試，但缺少邊界情況或執行路徑 |
+| **未覆蓋** | ❌ | AC 沒有測試 | 沒有任何測試案例參照此 AC |
+
+### 覆蓋率計算
+
+```
+AC Coverage % = (covered_count / total_ac_count) × 100
+
+Where:
+  covered_count = count of AC with status "covered"
+  total_ac_count = total number of AC in specification
+  partial counts as 0.5 for coverage calculation
+```
+
+### 計算範例
+
+```
+SPEC-001: 8 AC total
+  - 5 covered (✅)
+  - 2 partial (⚠️)
+  - 1 uncovered (❌)
+
+Coverage = (5 + 2×0.5) / 8 = 6/8 = 75%
+```
+
+---
+
+## 品質門檻
+
+### 預設門檻
+
+| 門檻 | 數值 | 強制執行 |
+|------|------|---------|
+| **最低 AC 覆蓋率** | 100% | 正式發布前必須達到 |
+| **簽入最低要求** | 80% | 功能分支合併前必須達到 |
+| **警告級別** | 60% | 觸發覆蓋率警告 |
+
+### 可設定門檻
+
+專案 **可以** 在設定檔中自訂門檻：
+
+```json
+{
+  "acCoverage": {
+    "minimum": 100,
+    "checkinMinimum": 80,
+    "warningLevel": 60,
+    "partialWeight": 0.5
+  }
+}
+```
+
+### 門檻例外
+
+覆蓋率要求的例外情況 **必須** 記錄在案：
+
+| 例外類型 | 允許時機 | 必要文件 |
+|---------|---------|---------|
+| 外部相依性阻擋 | 第三方 API 無法使用 | Issue 連結 + 時程 |
+| 基礎設施限制 | 測試環境限制 | 解決方案計畫 |
+| 延後至下一迭代 | 已與利害關係人確認 | Ticket 參照 |
+
+---
+
+## AC 覆蓋率報告格式
+
+### 標準報告結構
+
+```markdown
+# AC Coverage Report
+
+**Specification**: SPEC-001 — User Authentication
+**Generated**: 2026-03-18
+**Coverage**: 75% (6/8 AC)
+
+## Summary
+
+| Status | Count | Percentage |
+|--------|-------|------------|
+| ✅ Covered | 5 | 62.5% |
+| ⚠️ Partial | 2 | 25.0% |
+| ❌ Uncovered | 1 | 12.5% |
+
+## Traceability Matrix
+
+| AC-ID | Description | Status | Test Reference |
+|-------|-------------|--------|----------------|
+| AC-1 | Login with valid credentials | ✅ | auth.test.ts:15 |
+| AC-2 | Reject invalid credentials | ✅ | auth.test.ts:32 |
+| AC-3 | Rate limit login attempts | ⚠️ | auth.test.ts:48 (missing edge case) |
+| ...   | ...                        | ... | ... |
+
+## Gaps
+
+### Uncovered AC
+- **AC-8**: Social login integration — Blocked by OAuth provider sandbox
+
+### Partial AC
+- **AC-3**: Rate limit — Missing test for concurrent requests
+- **AC-6**: Session timeout — Missing test for background tab behavior
+
+## Action Items
+1. [ ] AC-8: Set up OAuth sandbox environment (ETA: 2026-03-25)
+2. [ ] AC-3: Add concurrent request test
+3. [ ] AC-6: Add background tab test
+```
+
+### 機器可讀格式
+
+```json
+{
+  "specId": "SPEC-001",
+  "specName": "User Authentication",
+  "generatedAt": "2026-03-18T10:00:00Z",
+  "coverage": {
+    "percentage": 75,
+    "covered": 5,
+    "partial": 2,
+    "uncovered": 1,
+    "total": 8
+  },
+  "matrix": [
+    {
+      "acId": "AC-1",
+      "description": "Login with valid credentials",
+      "status": "covered",
+      "testFile": "tests/auth.test.ts",
+      "testName": "should login with valid credentials",
+      "testLine": 15
+    }
+  ]
+}
+```
+
+---
+
+## 自動規格生成品質規則
+
+### AC 品質要求
+
+當從 PRD、使用者故事或需求自動生成規格時，所生成的 AC **必須** 符合以下品質標準：
+
+| 標準 | 說明 | 驗證方式 |
+|------|------|---------|
+| **具體（Specific）** | AC 描述具體、可觀察的行為 | 不使用模糊用語（「應該運作正常」、「夠快」） |
+| **可衡量（Measurable）** | AC 有可量化或可驗證的結果 | 包含預期數值、狀態或行為 |
+| **可達成（Achievable）** | AC 在技術上可行 | 參照已知的 API、資料或能力 |
+| **相關（Relevant）** | AC 與功能目的相關 | 對應使用者需求或業務需求 |
+| **可測試（Testable）** | AC 可通過測試驗證 | 可以用 Given-When-Then 表達 |
+
+### 規格生成 I/O 契約
+
+#### 輸入格式
+
+| 輸入類型 | 必要欄位 | 範例 |
+|---------|---------|------|
+| PRD | 標題、說明、使用者故事 | 產品需求文件 |
+| 使用者故事 | As a / I want / So that | 「As a user, I want to login...」 |
+| 功能簡報 | 功能名稱、目標、限制 | 功能說明文件 |
+
+#### 輸出格式
+
+生成的規格 **必須** 包含：
+
+| 區段 | 必填 | 說明 |
+|------|------|------|
+| SPEC ID | 是 | 唯一識別碼（例如 SPEC-001） |
+| 標題 | 是 | 功能名稱 |
+| 說明 | 是 | 功能描述 |
+| 驗收標準 | 是 | 編號 AC 清單（AC-1、AC-2、…） |
+| AC 格式 | 是 | Given-When-Then 或結構化條列 |
+| 可測試性標記 | 是 | 每個 AC 標記為可測試 / 不可測試 |
+
+#### 驗證規則
+
+1. **AC 數量**：生成的規格 **必須** 至少有 1 個 AC
+2. **AC 唯一性**：不可有重複的 AC 描述
+3. **AC 完整性**：正常路徑 + 至少 1 個錯誤或邊界情況
+4. **AC 可測試性**：100% 的 AC 必須可測試
+5. **可追溯性**：每個 AC 都連結回來源需求
+
+---
+
+## 反模式
+
+| 反模式 | 影響 | 正確做法 |
+|-------|------|---------|
+| 測試無法追溯 | 無法驗證規格覆蓋率 | 測試中一律標注 AC-ID |
+| 將部分覆蓋視為完整覆蓋 | 對覆蓋率產生錯誤信心 | 使用誠實的狀態分類 |
+| 忽略未覆蓋的 AC | 驗證存在缺口 | 追蹤並規劃所有 AC 的覆蓋工作 |
+| AC 缺乏可測試性 | 無法驗證 | 確保所有 AC 都可測試 |
+| 覆蓋但缺乏斷言 | 測試執行但不驗證任何內容 | 確認測試含有有意義的斷言 |
+
+---
+
+## 相關規範
+
+- [正向推導規範](forward-derivation-standards.md) — 從 AC 生成測試
+- [規格驅動開發](spec-driven-development.md) — AC 定義格式
+- [測試規範](testing-standards.md) — 測試實作規範
+- [簽入規範](checkin-standards.md) — 簽入的覆蓋率門檻
+- [測試治理](test-governance.md) — 完成標準
+
+---
+
+## 版本歷程
+
+| 版本 | 日期 | 變更內容 |
+|------|------|---------|
+| 1.0.0 | 2026-03-18 | 初始版本 — 可追溯性矩陣、覆蓋率計算、規格生成規則 |

package/bundled/locales/zh-TW/core/acceptance-test-driven-development.md

@@ -0,0 +1,47 @@
+---
+source: ../../../core/acceptance-test-driven-development.md
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-03-24
+status: current
+---
+
+# 驗收測試驅動開發（ATDD）標準
+
+> **語言**: [English](../../../core/acceptance-test-driven-development.md) | 繁體中文
+
+**版本**: 1.1.0
+**最後更新**: 2026-01-25
+**適用性**: 所有採用驗收測試驅動開發的專案
+**範圍**: 通用 (Universal)
+**業界標準**: 無（2003-2006 實踐）
+
+---
+
+## 摘要
+
+驗收測試驅動開發（ATDD）是一種傳統開發方法論（2003-2006），強調在開發開始之前透過協作定義驗收條件。整個團隊（業務、開發和測試）共同合作，透過可執行的驗收測試來定義「完成」的標準。
+
+ATDD 的核心價值在於 **Three Amigos**（三方協作）模式，由客戶/PO、開發人員和測試人員共同定義驗收條件。ATDD 是定義驗收條件的一種可選協作方法 — 團隊也可以透過訪談、PRD 或利害關係人討論來收集需求，達成類似的成果。
+
+---
+
+**完整指南：[ATDD 指南](../../../methodologies/guides/atdd-guide.md)**
+
+---
+
+## 快速參考
+
+| 面向 | 說明 |
+|------|------|
+| **核心工作流** | 研討會 → 精煉 → 開發 → 展示 → 完成 |
+| **關鍵價值** | Three Amigos 協作（PO + 開發 + QA） |
+| **測試層級** | 系統/驗收測試 |
+| **參與者** | 整個團隊 + 利害關係人 |
+| **工具** | FitNesse、Cucumber、Robot Framework |
+
+## 相關標準
+
+- [行為驅動開發](behavior-driven-development.md)
+- [測試驅動開發](../../../core/test-driven-development.md)
+- [規格驅動開發](spec-driven-development.md)

package/bundled/locales/zh-TW/core/accessibility-standards.md

@@ -0,0 +1,84 @@
+---
+source: ../../../core/accessibility-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-03-24
+status: current
+---
+
+# 無障礙標準
+
+> **語言**: [English](../../../core/accessibility-standards.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-01-29
+**適用性**: 所有具有使用者介面的軟體專案
+**範圍**: 通用 (Universal)
+**業界標準**: WCAG 2.1/2.2、WAI-ARIA 1.2、Section 508
+**參考**: [w3.org](https://www.w3.org/WAI/WCAG21/quickref/)
+
+---
+
+## 目的
+
+本標準定義建立無障礙軟體的完整指南，確保軟體能被各種能力的人使用。本標準符合國際標準（包括 WCAG 2.1），並支持全球各地的無障礙法規合規。
+
+**參考標準**：
+- [WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/) - 網頁內容無障礙指南
+- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) - 最新 WCAG 版本（2023）
+- [WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/) - 無障礙富網際網路應用程式
+- [Section 508](https://www.section508.gov/) - 美國聯邦無障礙需求
+- [EN 301 549](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/) - 歐洲無障礙標準
+
+---
+
+## 無障礙原則（POUR）
+
+| 原則 | 說明 | 範例 |
+|------|------|------|
+| **可感知 (Perceivable)** | 資訊和使用者介面元件必須以使用者可感知的方式呈現 | 替代文字、字幕、對比度 |
+| **可操作 (Operable)** | 使用者介面元件和導航必須可操作 | 鍵盤導航、充足時間、防癲癇 |
+| **可理解 (Understandable)** | 資訊和使用者介面的操作必須可理解 | 可讀性、可預測、輸入協助 |
+| **穩健 (Robust)** | 內容必須足夠穩健，能被各種使用者代理正確解讀 | 相容性、解析、名稱/角色/值 |
+
+## WCAG 合規等級
+
+| 等級 | 說明 | 建議 |
+|------|------|------|
+| **A** | 最低要求 — 所有專案必須達成 | 基礎無障礙需求 |
+| **AA** | 建議等級 — 大多數法規要求此等級 | 涵蓋大多數使用者需求 |
+| **AAA** | 最高等級 — 特定情境的最佳實踐 | 政府、醫療、教育 |
+
+## 鍵盤導航
+
+| 需求 | 說明 |
+|------|------|
+| 所有互動元素可透過鍵盤存取 | Tab、Shift+Tab、Enter、Space、方向鍵 |
+| 焦點指示器可見 | 使用者能清楚看到目前焦點位置 |
+| 無鍵盤陷阱 | 使用者可以用鍵盤離開所有元件 |
+| 焦點順序合邏輯 | Tab 順序遵循視覺佈局 |
+
+## 色彩與對比
+
+| 元素 | AA 等級 | AAA 等級 |
+|------|---------|----------|
+| 一般文字 | 4.5:1 | 7:1 |
+| 大型文字（18pt+） | 3:1 | 4.5:1 |
+| UI 元件 | 3:1 | — |
+| 非文字內容 | 3:1 | — |
+
+## 測試清單
+
+| 測試項目 | 工具 |
+|----------|------|
+| 自動化無障礙掃描 | axe-core、Lighthouse |
+| 鍵盤導航測試 | 手動測試 |
+| 螢幕閱讀器測試 | NVDA、VoiceOver、JAWS |
+| 色彩對比驗證 | Colour Contrast Analyser |
+| 表單標籤驗證 | axe-core、WAVE |
+
+## 相關標準
+
+- [效能標準](performance-standards.md)
+- [安全標準](security-standards.md)
+- [測試標準](testing-standards.md)

package/bundled/locales/zh-TW/core/agent-dispatch.md

@@ -0,0 +1,89 @@
+---
+source: ../../../core/agent-dispatch.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-03-24
+status: current
+---
+
+# 代理派遣與並行協調
+
+> **語言**: [English](../../../core/agent-dispatch.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-03-20
+**適用性**: 使用多代理編排的 AI 輔助開發
+**範圍**: 通用 (Universal)
+**靈感來源**: [Superpowers](https://github.com/obra/superpowers) — dispatching-parallel-agents、subagent-driven-development (MIT)
+
+---
+
+## 目的
+
+定義 AI 子代理的並行派遣、工作協調與狀態回報標準。確保高效並行化的同時，防止檔案衝突與整合失敗。
+
+---
+
+## 術語表
+
+| 術語 | 定義 |
+|------|------|
+| 子代理 (Sub-agent) | 由編排器產生的 AI 代理，負責處理特定任務 |
+| 獨立域 (Independent Domain) | 與其他任務無共享可變狀態的任務範圍 |
+| 狀態協定 (Status Protocol) | 子代理必須回報的標準化回傳狀態 |
+| 檔案衝突 (File Conflict) | 多個代理同時修改同一檔案的情況 |
+
+---
+
+## 核心原則 — 先獨立再並行
+
+> **派遣代理並行之前，必須驗證其任務域是獨立的（無共享可變狀態）。**
+
+---
+
+## Prompt 設計原則
+
+每個子代理的 prompt 必須包含：
+
+| 元素 | 說明 |
+|------|------|
+| **任務邊界** | 明確定義子代理可以操作的檔案與範圍 |
+| **禁止清單** | 不可修改的檔案路徑 |
+| **回傳格式** | 要求使用標準狀態協定回報結果 |
+| **超時機制** | 每個任務的最大執行時間 |
+
+## 狀態協定
+
+子代理必須使用以下狀態之一回報：
+
+| 狀態 | 說明 | 後續動作 |
+|------|------|----------|
+| `DONE` | 任務成功完成 | 編排器繼續下一步 |
+| `BLOCKED` | 遇到無法自行解決的阻礙 | 編排器介入或重新分配 |
+| `FAILED` | 任務失敗 | 編排器決定重試或跳過 |
+| `NEEDS_REVIEW` | 完成但需要人工審查 | 暫停等待人工確認 |
+
+## 並行派遣條件
+
+在派遣前必須驗證：
+
+| 檢查項目 | 驗證方式 |
+|----------|----------|
+| 無共享可變檔案 | 比較各任務的檔案路徑清單 |
+| 無執行順序依賴 | 驗證任務之間無因果關係 |
+| 獨立測試範圍 | 各任務的測試套件不重疊 |
+
+## 衝突解決
+
+當無法完全避免共享狀態時：
+
+1. **序列化** — 將衝突的任務改為依序執行
+2. **分區** — 將共享檔案拆分為獨立區段
+3. **鎖定** — 對共享資源實施寫入鎖
+
+## 相關標準
+
+- [Git Worktree 隔離](git-worktree.md)
+- [分支完成工作流程](branch-completion.md)
+- [AI 模型選擇策略](model-selection.md)
+- [驗證證據](verification-evidence.md)

package/bundled/locales/zh-TW/core/ai-agreement-standards.md

@@ -0,0 +1,87 @@
+---
+source: ../../../core/ai-agreement-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-03-24
+status: current
+---
+
+# AI 協議標準
+
+> **語言**: [English](../../../core/ai-agreement-standards.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-01-29
+**適用性**: 所有 AI 輔助開發工作階段
+**範圍**: 通用 (Universal)
+**業界標準**: ISO 12207 §6.1
+**ISO 12207 對應**: 協議程序 (6.1)
+
+---
+
+## 目的
+
+本標準將人類（需求方）與 AI（供應方）之間的互動形式化為可驗證的協議。在「Vibe Coding」中，prompt 上下文作為管控 AI 行為和交付物的合約。
+
+---
+
+## 1. 上下文合約
+
+每個 AI 工作階段必須以清晰的上下文合約開始。通常透過系統 prompt 檔案實現（如 `CLAUDE.md`、`.cursorrules`）。
+
+### 1.1 合約組成
+
+有效的上下文合約必須定義：
+
+| 組成部分 | 說明 | 範例 |
+|----------|------|------|
+| **角色定義** | 使用者 vs. AI 的代表身份 | 「你是一位資深後端工程師...」 |
+| **工作範圍** | 操作邊界 | 「只修改 `src/utils/` 中的檔案，不要碰 `config/`。」 |
+| **約束法則** | 不可協商的規則 | 「不可硬編碼密鑰。必須使用 TypeScript。」 |
+| **驗收條件** | 完成定義 | 「程式碼必須通過 `npm test` 和 `npm run lint`。」 |
+
+## 2. 需求提案（RFP）標準
+
+複雜任務應以「RFP」（需求提案）格式組織，而非簡單的對話訊息。
+
+### RFP 範本
+
+```markdown
+## 背景
+[描述現狀和為什麼需要此變更]
+
+## 範圍
+[明確列出要修改的檔案和功能]
+
+## 驗收條件
+- [ ] 條件 1
+- [ ] 條件 2
+
+## 約束
+- [不可做的事項]
+- [技術限制]
+```
+
+## 3. 變更管理
+
+| 變更類型 | 處理方式 |
+|----------|----------|
+| **範圍擴增** | AI 必須標示超出原始合約的請求 |
+| **需求變更** | 必須更新上下文合約後才能執行 |
+| **緊急修復** | 可繞過合約但必須事後補充文件 |
+
+## 4. 交付驗證
+
+每次交付必須包含：
+
+| 項目 | 說明 |
+|------|------|
+| **自我驗證** | AI 在交付前執行合約中定義的驗收條件 |
+| **變更摘要** | 列出所有修改的檔案和變更原因 |
+| **風險揭露** | 標示任何潛在風險或未解決的問題 |
+
+## 相關標準
+
+- [虛擬組織標準](virtual-organization-standards.md)
+- [反幻覺標準](anti-hallucination.md)
+- [驗證證據](verification-evidence.md)