universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-TW/ai/standards/testing.ai.yaml

@@ -0,0 +1,137 @@
+# 測試標準 - AI 優化版
+# 來源: core/testing-standards.md
+
+id: testing
+meta:
+  version: "1.3.0"
+  updated: "2025-12-30"
+  source: core/testing-standards.md
+  description: 測試金字塔與建議的覆蓋率比例，支援框架選項
+  language: zh-TW
+
+# 框架選擇 - 根據專案需求選擇
+# 參考來源: ISTQB Glossary v4.0, Martin Fowler's Testing Pyramid
+framework_options:
+  decision_point: 根據專案類型選擇測試框架
+  choices:
+    - id: istqb-framework
+      file: options/testing/istqb-framework.ai.yaml
+      best_for: 企業專案、認證需求、正式 QA 流程
+    - id: industry-pyramid
+      file: options/testing/industry-pyramid.ai.yaml
+      best_for: 敏捷開發、CI/CD 優化、快速迭代
+
+# 預設金字塔 (業界標準 - 可由框架選擇覆蓋)
+pyramid:
+  ratio: "70/20/10"
+  note: "業界標準比例。ISTQB 框架使用 4 層但無固定比例。"
+  levels:
+    - name: 單元測試 (UT)
+      percentage: 70
+      scope: 單一函式/方法
+      speed: 非常快 (<100ms)
+    - name: 整合測試 (IT/SIT)
+      percentage: 20
+      scope: 多個元件
+      speed: 快速 (<1s)
+      note: "IT (敏捷/DevOps) 或 SIT (企業/ISTQB) - 兩者都指整合測試"
+    - name: 端對端測試 (E2E)
+      percentage: 10
+      scope: 使用者流程/系統測試
+      speed: 較慢 (>10s)
+
+options:
+  testing_framework:
+    description: 選擇測試框架方法
+    multiSelect: false
+    choices:
+      - id: istqb-framework
+        file: options/testing/istqb-framework.ai.yaml
+      - id: industry-pyramid
+        file: options/testing/industry-pyramid.ai.yaml
+  test_level:
+    description: 選擇要實施的測試層級
+    multiSelect: true
+    choices:
+      - id: unit-testing
+        file: options/testing/unit-testing.ai.yaml
+      - id: integration-testing
+        file: options/testing/integration-testing.ai.yaml
+      - id: system-testing
+        file: options/testing/system-testing.ai.yaml
+      - id: e2e-testing
+        file: options/testing/e2e-testing.ai.yaml
+      - id: security-testing
+        file: options/testing/security-testing.ai.yaml
+        best_for: 處理敏感資料的應用程式、安全關鍵系統
+      - id: performance-testing
+        file: options/testing/performance-testing.ai.yaml
+        best_for: 高流量應用程式、即時系統、API
+      - id: contract-testing
+        file: options/testing/contract-testing.ai.yaml
+        best_for: 微服務、API 整合、分散式系統
+
+rules:
+  - id: follow-pyramid
+    trigger: 規劃測試策略時
+    instruction: 遵循 70/20/7/3 的單元/整合/系統/端對端比例
+    priority: required
+
+  - id: first-principles
+    trigger: 撰寫測試時
+    instruction: 遵循 FIRST 原則（快速、獨立、可重複、自我驗證、及時）
+    priority: required
+
+  - id: arrange-act-assert
+    trigger: 組織測試結構時
+    instruction: 使用 Arrange-Act-Assert 模式
+    priority: required
+
+  - id: meaningful-names
+    trigger: 命名測試時
+    instruction: 使用描述性的測試名稱，說明測試內容
+    priority: required
+    examples:
+      good:
+        - "should_return_user_when_valid_id_provided"
+        - "test_login_fails_with_invalid_credentials"
+      bad:
+        - "test1"
+        - "testLogin"
+
+  - id: test-boundaries
+    trigger: 選擇測試內容時
+    instruction: 專注於邊界條件和邊緣案例
+    priority: recommended
+
+  - id: avoid-test-doubles-overuse
+    trigger: 使用 mocks/stubs 時
+    instruction: 謹慎使用測試替身；當速度足夠快時，優先使用真實實作
+    priority: recommended
+
+quick_reference:
+  test_pyramid:
+    columns: [層級, 百分比, 範圍, 速度]
+    rows:
+      - [單元, 70%, 單一函式, <100ms]
+      - [整合, 20%, 多個元件, <1s]
+      - [系統, 7%, 完整系統, <10s]
+      - [端對端, 3%, 使用者流程, ">10s"]
+
+  first_principles:
+    columns: [原則, 說明]
+    rows:
+      - [快速 (Fast), 測試執行迅速]
+      - [獨立 (Independent), 測試之間無相依性]
+      - [可重複 (Repeatable), 每次執行結果相同]
+      - [自我驗證 (Self-validating), 通過/失敗無需人工檢查]
+      - [及時 (Timely), 與程式碼同步撰寫]
+
+  test_doubles:
+    columns: [類型, 用途, 使用時機]
+    rows:
+      - [Stub, 回傳預設值, 簡單相依性]
+      - [Mock, 驗證互動, 複雜相依性]
+      - [Fake, 簡化實作, 資料庫/外部服務]
+      - [Spy, 記錄呼叫, 驗證行為]
+      - [Dummy, 填充參數, 未使用的參數]

package/bundled/locales/zh-TW/ai/standards/versioning.ai.yaml

@@ -0,0 +1,211 @@
+# 語意化版本標準 - AI 優化版
+# 來源: core/versioning.md
+
+id: versioning
+meta:
+  version: "1.2.0"
+  updated: "2025-12-30"
+  source: core/versioning.md
+  description: 軟體發布的語意化版本 (SemVer)
+  language: zh-TW
+
+format:
+  template: "MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]"
+  examples:
+    - "2.3.1"
+    - "1.0.0-alpha.1"
+    - "3.2.0-beta.2+20250112"
+
+components:
+  major:
+    purpose: 破壞性變更
+    when_to_increment:
+      - 不相容的 API 變更
+      - 移除已棄用功能
+      - 重大架構變更
+    guidelines:
+      - 重設 MINOR 和 PATCH 為 0
+      - 記錄遷移指南
+      - 在前一個 MINOR 版本提供棄用警告
+
+  minor:
+    purpose: 新功能
+    when_to_increment:
+      - 新增向後相容的功能
+      - 棄用功能（非移除）
+      - 重大內部改進
+    guidelines:
+      - 重設 PATCH 為 0
+      - 既有功能不變
+      - 新功能是選擇性的
+
+  patch:
+    purpose: Bug 修正
+    when_to_increment:
+      - Bug 修正（無新功能）
+      - 安全修補
+      - 文件更正
+      - 內部重構（無 API 變更）
+    guidelines:
+      - 無新功能
+      - 無 API 變更
+      - 可以安全立即更新
+
+prerelease:
+  identifiers:
+    - id: alpha
+      purpose: 早期測試
+      stability: 不穩定
+      audience: 內部團隊
+
+    - id: beta
+      purpose: 功能完整
+      stability: 大致穩定
+      audience: 早期採用者
+
+    - id: rc
+      purpose: 最終測試（發布候選）
+      stability: 穩定
+      audience: Beta 測試者
+
+  ordering: "alpha < beta < rc < stable"
+
+initial_development:
+  version_0:
+    description: 主版本 0 表示開發階段
+    guidelines:
+      - API 可能頻繁變更
+      - MINOR 版本允許破壞性變更
+      - API 穩定時升至 1.0.0
+
+deprecation:
+  timeline:
+    internal_api: 1 個 minor 版本
+    partner_api: 2 個 minor 版本 + 3 個月
+    public_api: 2 個 minor 版本 + 6 個月
+    critical_infrastructure: 至少 1 年
+
+  backward_compatibility:
+    breaking_changes:
+      - 移除公開 API 端點
+      - 移除必要請求欄位
+      - 新增必要請求欄位
+      - 變更回應欄位類型
+      - 變更錯誤碼含義
+      - 移除使用者依賴的回應欄位
+
+    safe_changes:
+      - 新增選用請求欄位
+      - 新增回應欄位
+      - 新增端點
+      - 新增錯誤碼
+      - 改善錯誤訊息
+      - 效能改進
+
+api_versioning_strategies:
+  - strategy: URL 路徑
+    format: "/api/v1/users"
+    pros: 清楚、易於路由
+    cons: URL 污染
+    recommended: true
+
+  - strategy: 查詢參數
+    format: "/api/users?version=1"
+    pros: 選用版本控制
+    cons: 快取問題
+
+  - strategy: Header
+    format: "Accept: application/vnd.api.v1+json"
+    pros: 乾淨的 URL
+    cons: 較不可見
+
+release_process:
+  phases:
+    - phase: 1
+      name: 發布前診斷
+      mandatory: true
+      check_items:
+        - 系統工具版本
+        - 必要驅動程式
+        - 磁碟空間
+        - 資料庫連線
+        - 應用程式版本
+        - 設定完整性
+
+    - phase: 2
+      name: 環境準備
+      purpose: 安裝缺少的工具和驅動程式
+
+    - phase: 3
+      name: 套件產生
+      naming: "{PROJECT}-upgrade-v{VERSION}-{DATE}.tar.gz"
+
+    - phase: 4
+      name: 部署執行
+      steps:
+        - 上傳升級套件
+        - 解壓套件
+        - 試運行測試（強烈建議）
+        - 實際升級
+
+    - phase: 5
+      name: 發布後驗證
+      check_items:
+        - 服務正常運作
+        - API 回傳正確版本
+        - 日誌無致命錯誤
+        - 功能驗證通過
+
+rules:
+  - id: semver-compliance
+    trigger: 發布新版本時
+    instruction: 嚴格遵循語意化版本格式
+    priority: required
+
+  - id: deprecation-warning
+    trigger: 規劃破壞性變更時
+    instruction: 在移除前 N-1 版本加入棄用警告
+    priority: required
+
+  - id: migration-guide
+    trigger: 發布 MAJOR 版本時
+    instruction: 記錄遷移指南，附前後對照範例
+    priority: required
+
+  - id: changelog-update
+    trigger: 發布任何版本時
+    instruction: 更新 CHANGELOG.md 記錄所有重要變更
+    priority: required
+
+  - id: pre-release-diagnosis
+    trigger: 開始發布流程時
+    instruction: 不得跳過診斷階段
+    priority: required
+
+  - id: dry-run-test
+    trigger: 部署升級時
+    instruction: 不得跳過試運行測試
+    priority: required
+
+quick_reference:
+  version_components:
+    columns: [組成, 用途, 重設]
+    rows:
+      - [MAJOR, 破壞性變更, "MINOR=0, PATCH=0"]
+      - [MINOR, 新功能, "PATCH=0"]
+      - [PATCH, Bug 修正, 無]
+
+  prerelease_order:
+    columns: [識別碼, 穩定度, 受眾]
+    rows:
+      - [alpha, 不穩定, 內部團隊]
+      - [beta, 大致穩定, 早期採用者]
+      - [rc, 穩定, Beta 測試者]
+
+  deprecation_periods:
+    columns: [API 類型, 最短期間]
+    rows:
+      - [內部 API, 1 個 minor 版本]
+      - [合作夥伴 API, 2 個 minor + 3 個月]
+      - [公開 API, 2 個 minor + 6 個月]
+      - [關鍵基礎設施, 1 年]

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

@@ -0,0 +1,213 @@
+---
+source: core/ai-instruction-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-01-14
+status: current
+---
+
+# AI 指令檔案規範
+
+> **語言**: [English](../../../core/ai-instruction-standards.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-01-14
+**適用範圍**: 所有使用 AI 編碼助手的專案
+
+---
+
+## 目的
+
+本規範定義建立和維護 AI 指令檔案（又稱「系統提示詞檔」）的最佳實踐。這些檔案引導 AI 助手理解專案特定的慣例、標準和工作流程。
+
+---
+
+## 支援的 AI 工具
+
+| AI 工具 | 指令檔案 | 格式 |
+|---------|---------|------|
+| Claude Code | `CLAUDE.md` | Markdown |
+| Cursor | `.cursorrules` | Markdown |
+| Windsurf | `.windsurfrules` | Markdown |
+| Cline | `.clinerules` | Markdown |
+| GitHub Copilot | `.github/copilot-instructions.md` | Markdown |
+| OpenCode | `.opencode/instructions.md` | Markdown |
+
+---
+
+## 核心原則：通用與專用分離
+
+### 為什麼要分離？
+
+AI 指令檔案通常混合兩種類型的內容：
+1. **通用規則**：適用於任何專案
+2. **專案專用配置**：專屬於你的專案
+
+分離這些內容可以改善：
+- **可攜性**：通用區段可在專案間重複使用
+- **可維護性**：更容易更新而不會意外「洩漏」
+- **清晰性**：使用者知道採用標準時需要自訂哪些部分
+
+---
+
+## 檔案結構
+
+### 建議的佈局
+
+```markdown
+# [專案名稱] - AI 指令
+
+## 通用標準
+<!-- 適用於任何專案的規則 -->
+- Commit 訊息格式
+- 程式碼審查清單
+- 測試標準
+- 反幻覺規則
+
+---
+
+## 專案專用配置
+<!-- 專屬於本專案 - 採用時需自訂 -->
+
+### 技術棧
+[你的技術在這裡]
+
+### 快速指令
+[你的建置/測試/部署指令]
+
+### 檔案結構
+[你的專案結構]
+
+### 發布流程
+[你的發布工作流程]
+```
+
+---
+
+## 內容指南
+
+### 通用內容（不要包含專案特定細節）
+
+| 類別 | 範例 |
+|------|------|
+| **Commit 標準** | Conventional Commits 格式、訊息結構 |
+| **程式碼審查** | 審查清單、註解前綴 |
+| **測試** | 測試金字塔比例、命名慣例 |
+| **AI 行為** | 反幻覺規則、來源標註 |
+| **文件** | 寫作風格、結構指南 |
+
+**在通用區段中避免：**
+- 特定指令（例如：`npm test`、`pytest`）
+- 硬編碼路徑（例如：`cli/src/`、`/var/www/`）
+- 版本號（例如：`Node.js 18`、`Python 3.11`）
+- 專案名稱和 URL
+
+### 專案專用內容（明確標記這些區段）
+
+| 類別 | 範例 |
+|------|------|
+| **技術棧** | 程式語言、框架、版本 |
+| **指令** | 建置、測試、lint、部署指令 |
+| **檔案結構** | 目錄佈局、關鍵檔案 |
+| **發布流程** | 版本檔案、部署步驟 |
+| **團隊慣例** | 語言偏好、命名模式 |
+
+---
+
+## 標記慣例
+
+使用明確的標記來區分內容類型：
+
+### 選項 A：區段標題
+
+```markdown
+## 通用標準
+[通用內容]
+
+## 專案專用配置
+[專案專用內容]
+```
+
+### 選項 B：行內標記
+
+```markdown
+> ⚠️ **專案專用**：此區段包含專屬於本專案的配置。
+
+### 技術棧
+...
+```
+
+### 選項 C：註解標註
+
+```markdown
+<!-- 通用：以下適用於所有專案 -->
+### Commit 訊息格式
+...
+
+<!-- 專案專用：為你的專案自訂 -->
+### 快速指令
+...
+```
+
+---
+
+## 維護檢查清單
+
+在提交 AI 指令檔案的變更之前：
+
+- [ ] **通用區段**：無專案特定的路徑、指令或版本
+- [ ] **專案專用區段**：已用標籤明確標記
+- [ ] **交叉引用**：指向標準文件的連結正確
+- [ ] **一致性**：格式與現有區段一致
+
+### 洩漏檢測
+
+執行此檢查以找出通用區段中可能的專案特定內容洩漏：
+
+```bash
+# 範例：在通用區段中找出硬編碼指令
+grep -n "npm\|yarn\|pip\|cargo" CLAUDE.md | head -20
+```
+
+審查每個匹配項，確保它在專案專用區段中。
+
+---
+
+## 快速參考卡
+
+### 通用 vs 專案專用
+
+| 類型 | 包含 | 範例 |
+|------|------|------|
+| **通用** | 通用規則 | 「提交前執行測試」 |
+| **專案專用** | 具體指令 | 「提交前執行 `npm test`」 |
+
+### 區段標記
+
+| 標記 | 含義 |
+|------|------|
+| `## 通用` | 適用於任何專案 |
+| `## 專案專用` | 專屬於本專案 |
+| `> ⚠️ 專案專用` | 特定區段的行內警告 |
+
+---
+
+## 相關標準
+
+- [文件結構](documentation-structure.md)
+- [文件寫作標準](documentation-writing-standards.md)
+- [反幻覺指南](anti-hallucination.md)
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-01-14 | 初始發布 |
+
+---
+
+## 授權
+
+本標準採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 發布。