universal-dev-standards 5.14.0 → 5.16.0

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

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/ai-instruction-standards.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-01-14
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-05-28
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **語言**: [English](../../../core/ai-instruction-standards.md) | 繁體中文
 
-**版本**: 1.0.0
-**最後更新**: 2026-01-14
+**版本**: 1.1.0
+**最後更新**: 2026-05-28
 **適用範圍**: 所有使用 AI 編碼助手的專案
 
 ---
@@ -151,6 +151,130 @@ AI 指令檔案通常混合兩種類型的內容：
 
 ---
 
+## 國際化（i18n）
+
+AI 指令檔常需提供多語言版本——既為了國際採用者，也為了非英語母語維護者主導的專案。本章節定義多語言指令檔的組織、驗證與安裝規則。
+
+### AI 指令檔的範圍
+
+本標準涵蓋兩個層級的 AI 指令檔：
+
+| 層級 | 範例 | i18n 模式 |
+|------|------|----------|
+| **Root 層** | `CLAUDE.md`、`.cursorrules`、`.windsurfrules`、`.opencode/instructions.md` | 單檔內以 inline 段落分語言（例：`## 中文` / `## English`）|
+| **Skill 層** | Claude Code `.claude/skills/{name}/SKILL.md`、OpenCode plugin instructions | Canonical（英文）+ `locales/{lang}/` 變體 |
+
+> 注意：skill 層的多檔結構主要對 Claude Code 適用。其他工具是 root 單檔；對它們只有下方「分層語言策略」與「Chimera 防範」規則適用。
+
+### 分層語言策略
+
+每份 AI 指令檔概念上有 **4 層**，各層語言責任不同：
+
+| 層 | 內容 | Canonical (en) | Locale ({lang}) | 為何分這層 |
+|----|------|---------------|----------------|-----------|
+| **L1 — Metadata** | YAML frontmatter `description`、`argument-hint`、`allowed-tools` | **必須英文** | **必須對應 locale 語言** | AI 觸發訊號；英文 token 效率最高 + 訓練語料密度高 |
+| **L2 — 指令（Instructions）** | 對 AI 的命令式規則（steps、behavior、allowed-tools 理由）| **必須英文** | 對應 locale 語言（可選；可保留英文）| AI 讀英文指令最精準；只有當維護者需要以母語讀指令時才翻譯 |
+| **L3 — 輸出範本（Output Templates）** | 範例輸出、回應格式、情境範本 | 英文（canonical 鎖定英文）| **強制對應 locale**（mandatory）| **唯一直接影響 AI 輸出語言的層**——AI 會繼承所見範本的語言 |
+| **L4 — 人類文件** | 維護者註解、貢獻者說明、walkthrough | 英文 | 對應 locale 語言（強烈建議）| 給人類維護者讀，AI 不讀 |
+
+**關鍵 insight**：L1（description）是 AI 用來決定「**是否呼叫**」此 skill 的觸發訊號——它**不**影響 AI 之後說什麼。L3（output template）才是控制 AI 輸出語言的唯一開關，因為 AI 會慣性沿用範本語言。**i18n 強制檢查應該聚焦在 L3——加強 L1 的強制（例如強制 description 用 locale）是常見錯誤，它解決的是錯誤的問題。**
+
+### Canonical / Locale 檔案結構
+
+UDS 標準與 skill 的 locale 變體結構：
+
+```text
+core/{name}.md                              ← canonical（英文）— single source of truth
+core/{name}.ai.yaml                         ← canonical 結構化（英文）
+locales/{lang}/core/{name}.md               ← locale 變體（匹配 lang）
+locales/{lang}/ai/standards/{name}.ai.yaml  ← locale .ai.yaml（匹配 lang）
+skills/{name}/SKILL.md                      ← canonical skill（英文）
+locales/{lang}/skills/{name}/SKILL.md       ← locale skill 變體
+```
+
+**命名慣例**：使用 BCP 47 語言標籤——`zh-TW`、`zh-CN`、`ja`、`ko`、`en-US` 等。
+
+### Locale 變體 Frontmatter 必填欄位
+
+每個 locale 變體必須含追蹤用 frontmatter，方便偵測 drift：
+
+```yaml
+---
+name: {與 canonical 同名}
+source: {指回 canonical 的相對路徑}
+source_version: {翻譯時 canonical 的版本}
+translation_version: {本翻譯的版本}
+---
+```
+
+當 canonical 更新（bump `source_version`），locale 維護者應重新同步並 bump `translation_version`。若 `source_version` 落後超過 2 個 minor 版本，會觸發 drift 警告（見「Chimera 防範」）。
+
+### 責任邊界
+
+| 角色 | 擁有 | 必須做 |
+|------|------|--------|
+| **Canonical 擁有者** | `core/{name}.md`、`core/{name}.ai.yaml`、`skills/{name}/SKILL.md` | 維持 L1/L2/L3/L4 為英文；每次 breaking change 時 bump `source_version` |
+| **Locale 維護者** | `locales/{lang}/...` 檔 | `translation_version` 對齊 `source_version`；翻譯 L1（必）、L2（選）、L3（必）、L4（建議）|
+| **採用者（下游專案）** | 自己的 `.claude/skills/`、`CLAUDE.md` 等 | 用 `uds install --locale {lang}` 安裝；**絕不**手動修改 canonical 檔（要客製化請用 locale 變體或 overlay）|
+
+### Chimera 防範
+
+**Chimera**（混血兒）指違反分層規則、混合語言的檔案。常見 chimera 模式：
+
+| 模式 | 嚴重度 | 偵測方式 |
+|------|--------|----------|
+| Canonical 檔的 `description` 含 CJK | ❌ Error | Lint：`canonical:description-must-be-ascii` |
+| Locale 變體的 `description` 是純 ASCII | ❌ Error | Lint：`locale:description-must-match-language` |
+| Locale 變體缺 `source:` frontmatter | ❌ Error | Lint：`locale:must-have-source-frontmatter` |
+| Canonical L3 output template 含非英文範例回應 | ⚠️ Warn | Lint：`canonical:l3-language-consistency` |
+| 採用者 `.claude/skills/` 的檔案與 canonical 和任何 locale 變體都不同 | ⚠️ Warn | Sync check：`adopter:must-match-installed-locale` |
+| `translation_version` 落後 `source_version` 超過 2 minor | ⚠️ Warn | Drift check |
+
+Pre-commit / CI lint 強制 error 級規則；warn 級規則只在 dashboard 揭露不阻擋。
+
+### 採用者安裝模式
+
+採用者透過 UDS CLI 安裝指令檔：
+
+```bash
+uds install --locale zh-TW   # 以繁體中文安裝 skills 與 standards
+```
+
+**Locale 解析優先順序**：
+1. `--locale` CLI 旗標（最高）
+2. `.uds/install.yaml` 的 `locale:` 欄位
+3. 環境變數 `UDS_LOCALE`
+4. Fallback：`en`
+
+**Locale 不存在時的 fallback 行為**：當索求的 locale 對某個 skill 沒有變體時，CLI：
+- 安裝 canonical（英文）檔案
+- 發出 WARN 列出哪些 skill fallback 了
+- **不**阻斷安裝
+
+這確保覆蓋率不完整時採用者仍能用。採用者可查 `locales/COVERAGE.md` 知道哪些有翻譯、哪些沒有。
+
+### 遷移：已有 chimera 的採用者
+
+若採用者已手動修改過專案中的 canonical 檔（例：在 `.claude/skills/` 翻譯了描述）：
+
+1. **辨識 chimera**：比對採用者檔案與 UDS canonical / canonical 的 locale 變體。
+2. **安裝正確變體**：執行 `uds install --locale {lang}` 替換 chimera 為 locale 變體。
+3. **保留專案級客製**：若 chimera 含合理的專案級客製（非翻譯），抽出為 overlay 或記錄到客製化日誌（例：`UDS-CUSTOMIZATION.md`）。
+4. **丟棄純翻譯**：chimera 中純翻譯部分直接丟棄——locale 變體會取代它。
+
+### 快速參考
+
+| 動作 | 何時 | 工具 / 檔案 |
+|------|------|------------|
+| 新增語言支援 | 想支援新 locale | 建立 `locales/{lang}/...` 對應 canonical 結構 |
+| 更新 canonical | 改進英文 source | Bump `source_version`；通知 locale 維護者 |
+| 翻譯 / 同步 locale | 新增或更新 locale 內容 | Bump `translation_version`；參照當前 `source_version` |
+| 檢查覆蓋率 | 定期 review | 看自動產生的 `locales/COVERAGE.md` |
+| 帶 locale 安裝 | 採用者初設或重新同步 | `uds install --locale {lang}` |
+| 跑 i18n lint | Commit 前 / CI | `uds lint --i18n` |
+
+---
+
 ## 維護檢查清單
 
 在提交 AI 指令檔案的變更之前：
@@ -205,6 +329,7 @@ grep -n "npm\|yarn\|pip\|cargo" CLAUDE.md | head -20
 | 版本 | 日期 | 變更 |
 |------|------|------|
 | 1.0.0 | 2026-01-14 | 初始發布 |
+| 1.1.0 | 2026-05-28 | 新增 i18n 章節；範圍延伸至 skill 層級檔案 |
 
 ---
 

package/bundled/locales/zh-TW/core/browser-compatibility-standards.md

@@ -1,11 +1,228 @@
 ---
 source: ../../../core/browser-compatibility-standards.md
 source_version: 1.0.0
-translation_version: 0.0.0
-last_synced: 2026-05-05
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: b806494266e8
 ---
 
-<!-- TODO: 待完整繁體中文翻譯 — Translation pending -->
-<!-- See source: core/browser-compatibility-standards.md -->
+# 瀏覽器相容性標準
 
-> 此標準尚未完整翻譯。請參閱英文原文：[English](../../../core/browser-compatibility-standards.md)
+> **語言**：[English](../../../core/browser-compatibility-standards.md) | 繁體中文
+
+**版本**：1.0.0
+**最後更新**：2026-05-05
+**適用範圍**：前端專案（網頁應用程式、漸進式網頁應用程式 PWA、Web Components）
+**範疇**：universal
+**業界標準**：Browserslist、W3C WebDriver、WebDriver BiDi
+**參考資料**：[caniuse.com](https://caniuse.com/)、[Playwright 瀏覽器支援矩陣](https://playwright.dev/docs/browsers)
+
+---
+
+## 目的
+
+本標準定義所支援的瀏覽器與裝置矩陣、測試自動化策略，以及瀏覽器相容性的發布閘門（即 `release-readiness-gate.md` 中的第 9 維度，Tier-3）。
+
+瀏覽器相容性問題屬於使用者最容易察覺的缺陷之一，卻因為團隊往往假設「在 Chrome 上能跑就好」而被系統性地測試不足。若缺少明確的支援矩陣與自動化驗證，回歸缺陷便會滲漏到正式環境，影響大量使用者族群。
+
+---
+
+## 支援層級定義
+
+| 層級 | 定義 | 發布閘門 |
+|------|-----------|--------------|
+| **Tier-1**（完整支援） | 功能完全對等 + 自動化測試覆蓋 | 100% 通過 —— 任一測試失敗即阻擋發布 |
+| **Tier-2**（部分支援） | 盡力支援；主要流程必須可運作 | ≥ 95% 通過 —— 低於則 WARN，< 90% 則 FAIL |
+| **Tier-3**（盡力而為） | 非正式支援；缺陷會記錄但不阻擋發布 | 僅作為建議參考 |
+
+---
+
+## 預設瀏覽器矩陣
+
+團隊**必須**明確宣告其支援矩陣。以下預設值涵蓋了大多數網頁流量（依 2025–2026 年資料）：
+
+### Tier-1（預設）
+
+| 瀏覽器 | 版本 | 平台 |
+|---------|----------|---------|
+| Chrome | latest、latest-1 | Windows、macOS、Linux、Android |
+| Safari | latest、latest-1 | macOS、iOS |
+| Firefox | latest | Windows、macOS、Linux |
+| Edge | latest | Windows、macOS |
+
+### Tier-2（預設）
+
+| 瀏覽器 | 版本 | 平台 |
+|---------|----------|---------|
+| Chrome | latest-2、latest-3 | 桌面 |
+| Safari | latest-2 | macOS、iOS |
+| Samsung Internet | latest | Android |
+| Opera | latest | 桌面 |
+
+### Tier-3（預設）
+
+| 瀏覽器 | 備註 |
+|---------|-------|
+| IE 11 | 已終止支援（EOL）；僅在合約要求時才支援 |
+| Chrome < latest-3 | 列為已知限制追蹤 |
+
+### 裝置 / 視窗（Viewport）矩陣
+
+| 類別 | 最小寬度 | 代表性裝置 |
+|----------|-----------|-----------------------|
+| 行動裝置（小） | 360px | Android（小尺寸） |
+| 行動裝置（標準） | 390px | iPhone 14 |
+| 平板（直向） | 768px | iPad |
+| 平板（橫向） | 1024px | iPad 橫向 |
+| 桌面（小） | 1280px | 13 吋筆電 |
+| 桌面（標準） | 1440px | 15 吋筆電 / 外接螢幕 |
+| 桌面（寬） | 1920px | Full HD 螢幕 |
+
+最低要求：在 **360px、768px、1280px**（行動 / 平板 / 桌面斷點）進行測試。
+
+---
+
+## 自動化測試
+
+### Playwright 矩陣設定
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  projects: [
+    // Tier-1 browsers
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
+    { name: "edge", use: { ...devices["Desktop Edge"] } },
+    // Mobile Tier-1
+    { name: "mobile-chrome", use: { ...devices["Pixel 7"] } },
+    { name: "mobile-safari", use: { ...devices["iPhone 14"] } },
+    // Viewport coverage
+    { name: "tablet", use: { ...devices["iPad Pro 11"] } },
+  ],
+  // Tier-1 failure = build failure
+  reporter: [["html"], ["junit", { outputFile: "results/browser-compat.xml" }]],
+});
+```
+
+### CI 執行策略
+
+```bash
+# Run full Tier-1 matrix on release candidate
+npx playwright test --project=chromium,firefox,webkit,edge,mobile-chrome,mobile-safari,tablet
+
+# Run Tier-1 only on every PR (fast feedback)
+npx playwright test --project=chromium,firefox,webkit
+
+# Run Tier-2 on release candidate (results feed into sign-off as WARN/PASS)
+npx playwright test --project=samsung,opera
+```
+
+### 雲端瀏覽器測試
+
+針對 Tier-1 的跨作業系統測試（例如在 Windows 主機的 CI 上測試 Safari），請使用雲端服務：
+
+| 服務 | 使用情境 |
+|---------|---------|
+| BrowserStack Automate | 商業專案；提供最廣泛的 OS + 瀏覽器矩陣 |
+| Sauce Labs | 已有既有合約的企業 |
+| LambdaTest | 開源 / 對成本敏感的專案 |
+
+**最低雲端測試要求**：在真實 iOS 裝置上測試 Safari latest 與 latest-1（對於 WebKit 的缺陷，模擬器（Simulator）並不足夠）。
+
+---
+
+## 視覺回歸測試（選用但建議）
+
+像素差異（Pixel-diff）測試可偵測跨瀏覽器的版面回歸：
+
+```bash
+# Using Playwright visual comparisons
+npx playwright test --update-snapshots  # update baseline
+npx playwright test                     # compare against baseline; fail if diff > threshold
+```
+
+門檻建議值：版面元件 < 0.5% 像素差異；複雜的互動元件 < 2%。
+
+---
+
+## 發布閘門條件
+
+這是 `release-readiness-gate.md` 中的**第 9 維度**（Tier-3：前端 / 網頁專案必填；CLI / 純後端專案則標示為 `N/A`）。
+
+| 閘門 | Pass | Warn | Fail |
+|------|------|------|------|
+| Tier-1 瀏覽器矩陣 | 100% 測試通過 | — | 任一測試失敗 |
+| Tier-2 瀏覽器矩陣 | ≥ 95% 通過 | 90–95% | < 90% |
+| 視窗覆蓋（360/768/1280） | 任何 Tier-1 瀏覽器上版面皆無破版 | — | 任一關鍵流程無法使用 |
+
+### 簽核所需的證據
+
+```
+| 9 | Browser / Device Compat | PASS | Playwright: 6 browsers × 7 viewports, 100% Tier-1; Tier-2: 97%; [junit report link] | QA Lead |
+```
+
+### `N/A` 條件
+
+在以下情況標示為 `N/A`：
+- 專案為純 CLI、純後端 API，或行動原生（非網頁）
+- 記錄理由：`"N/A — backend API service, no browser UI"`
+
+---
+
+## Browserslist 設定
+
+在 repo 根目錄提交一份 `.browserslistrc`，以確保建置工具（Babel、PostCSS、Autoprefixer）針對相同的瀏覽器：
+
+```
+# .browserslistrc
+# Tier-1: production targets
+last 2 Chrome versions
+last 2 Firefox versions
+last 2 Safari versions
+last 2 Edge versions
+last 2 iOS versions
+last 2 ChromeAndroid versions
+
+# Tier-2: for reference (not in build targets by default)
+# last 4 Chrome versions
+# Samsung Internet >= 14
+```
+
+---
+
+## 反模式
+
+- **只測試 Chrome** —— Chrome 約佔桌面流量的 65%；剩下的 35% 是 Safari / Firefox / Edge 使用者，而你的 bug 會被他們發現
+- **使用瀏覽器模擬器測試 iOS Safari** —— 模擬器上的 WebKit 與真實裝置的 WebKit 有所分歧；對於 release candidate，務必在真實 iOS 上測試
+- **未指定矩陣** —— 隱含假設「支援所有瀏覽器」是不可能測試的；明確的 Tier-1 矩陣勝過毫無實質的隱含覆蓋
+- **將 Tier-3 瀏覽器失敗當作阻擋項** —— Tier-3 是盡力而為；記錄問題才是恰當做法，而非阻擋發布
+- **略過行動視窗測試** —— 行動優先（mobile-first）已是標準；缺少 360px 測試將為大多數行動使用者帶來破損的使用體驗
+
+---
+
+## 與其他標準的關係
+
+- **`accessibility-standards.md`** —— 鍵盤導覽與螢幕報讀器測試需跨所有 Tier-1 瀏覽器執行
+- **`e2e-testing.md`** —— Playwright 矩陣設定將 E2E 測試擴展為多瀏覽器
+- **`release-readiness-gate.md`** —— 第 9 維度（Tier-3）
+- **`performance-standards.md`** —— Core Web Vitals 目標適用於每個 Tier-1 瀏覽器
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更內容 |
+|---------|------|---------|
+| 1.0.0 | 2026-05-05 | 首次發布：Tier-1/2/3 矩陣、Playwright 設定、雲端測試、發布閘門條件 |
+
+---
+
+## 授權
+
+本標準依 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/core/contract-testing-standards.md

@@ -1,11 +1,190 @@
 ---
 source: ../../../core/contract-testing-standards.md
 source_version: 1.0.0
-translation_version: 0.0.0
-last_synced: 2026-05-05
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 2afa2fe434a6
 ---
 
-<!-- TODO: 待完整繁體中文翻譯 — Translation pending -->
-<!-- See source: core/contract-testing-standards.md -->
+# 合約測試標準（Contract Testing Standards）
 
-> 此標準尚未完整翻譯。請參閱英文原文：[English](../../../core/contract-testing-standards.md)
+> **語言**：[English](../../../core/contract-testing-standards.md) | 繁體中文
+
+**版本**：1.0.0
+**最後更新**：2026-05-05
+**適用範圍**：具有 API 消費者（服務對服務、前端對後端、公開 API）的專案
+**範疇**：universal
+**業界標準**：消費者驅動合約測試（Consumer-Driven Contract Testing, CDCT）、Pact Specification v3
+**參考資料**：[pact.io](https://docs.pact.io/)、[Spring Cloud Contract](https://spring.io/projects/spring-cloud-contract)
+
+---
+
+## 目的
+
+合約測試（Contract testing）驗證 provider（API 伺服器）與其 consumer（用戶端）對於確切介面 —— 請求格式、回應 schema 與狀態碼 —— 達成共識，且無需雙方同時部署。
+
+若缺少合約測試：
+- Provider 的變更會在 production 中悄悄破壞 consumer
+- 服務之間的整合測試需要完整環境
+- API 版本決策在缺乏實際使用證據的情況下做出
+
+本標準將消費者驅動合約測試正式化為一道**發布閘門**（`release-readiness-gate.md` 中的 Dimension 4，Tier-3）。
+
+---
+
+## 消費者驅動合約流程
+
+```
+Consumer 撰寫互動預期
+        ↓
+Consumer 將合約發布至 Pact Broker
+        ↓
+Provider CI 取得 consumer 合約
+        ↓
+Provider 驗證自身能否滿足每一筆互動
+        ↓
+Pact Broker 記錄：can-i-deploy 結果
+        ↓
+發布閘門：provider 部署前所有 consumer 合約必須 GREEN
+```
+
+---
+
+## 合約涵蓋範圍
+
+一份合約涵蓋：
+
+| 元素 | 是否必須指定 | 備註 |
+|---------|-------------|-------|
+| 請求方法（Request method） | 是 | GET / POST / PUT / PATCH / DELETE |
+| 請求路徑（Request path） | 是 | 包含路徑參數（path params） |
+| 請求標頭（Request headers） | 僅必要者 | 不要過度指定可選標頭 |
+| 請求 body schema | 是（針對寫入操作） | schema 層級，而非字面值 |
+| 回應狀態（Response status） | 是 | 所有預期的狀態碼 |
+| 回應 body schema | 是 | schema 層級；使用 matcher 而非字面值 |
+| 回應標頭（Response headers） | 僅必要者 | 例如 `Content-Type` |
+
+**寧可不足指定，也不要過度指定。** 只斷言 consumer 實際使用到的部分。
+
+---
+
+## 向後相容視窗
+
+| 發布類型 | 相容性要求 |
+|-------------|--------------------------|
+| Patch | 100% 向後相容；不預期有合約變更 |
+| Minor | N-1 consumer 合約版本仍須通過 |
+| Major | 需要棄用期；通知 consumer；舊合約歸檔 |
+
+**破壞性變更政策**：若任何作用中的 consumer 合約呈紅色，provider 不得部署（MAY NOT deploy）。破壞性變更需要：
+1. 採用僅新增（additive-only）變更的新 provider 版本
+2. Consumer 遷移至新版本
+3. 舊合約明確標示棄用並歸檔
+
+---
+
+## 發布閘門準則
+
+| 準則 | 硬性下限 | 警告區間 |
+|-----------|-------------|-----------|
+| 所有作用中的 consumer 合約 | 100% 綠燈 | —（二元：全有或全無） |
+| N-1 向後相容 | 100% 綠燈 | — |
+| 棄用合約清理 | 舊合約於 30 天內歸檔 | > 30 天 = WARN |
+
+Pact Broker 中的 `can-i-deploy` 指令封裝了這道閘門：
+
+```bash
+pact-broker can-i-deploy \
+  --pacticipant <provider-service> \
+  --version <version> \
+  --to-environment production
+```
+
+結束碼（Exit code）0 = PASS；非零 = FAIL（阻擋發布）。
+
+---
+
+## 實作指引
+
+### Consumer 端
+
+```typescript
+// Pact consumer test (TypeScript example)
+const interaction = {
+  state: "user 42 exists",
+  uponReceiving: "a request for user 42",
+  withRequest: {
+    method: "GET",
+    path: "/users/42",
+    headers: { Accept: "application/json" },
+  },
+  willRespondWith: {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+    body: like({           // schema matcher, not literal
+      id: integer(),
+      name: string(),
+      email: email(),
+    }),
+  },
+};
+```
+
+### Provider 端
+
+```bash
+# Provider verification in CI
+PACT_BROKER_BASE_URL=https://pact-broker.internal \
+PACT_PROVIDER_VERSION=$GIT_SHA \
+npm run test:pact:provider
+```
+
+### Pact Broker 標籤
+
+| 標籤 | 意義 |
+|-----|---------|
+| `main` | main 分支的最新版本 |
+| `production` | 目前部署於 production 的版本 |
+| `<feature-branch>` | 功能分支合約（暫時性） |
+
+---
+
+## 反模式
+
+- **測試整個 API 表面** —— 只測試 consumer 實際使用的部分；過度指定會造成不必要的合約中斷
+- **字面值比對** —— 使用 schema matcher（`like()`、`eachLike()`、`integer()`）而非精確值；合約應能容忍實際資料的合理變化
+- **略過 provider 驗證** —— 發布 consumer 合約卻不進行 provider 驗證，代表該合約毫無強制效力
+- **未執行 `can-i-deploy`** —— 只檢查個別合約狀態並不足夠；`can-i-deploy` 會評估整個部署矩陣
+
+---
+
+## 與其他標準的關係
+
+- **`api-design-standards.md`** —— 合約測試強制執行 API 設計中所宣告的向後相容保證
+- **`release-readiness-gate.md`** —— Dimension 4（Tier-3：當存在 API consumer 時適用）
+- **`integration-testing.md`** —— 合約測試補足但不取代整合測試
+- **`versioning.md`** —— 語意化版本與上述向後相容視窗互相關聯
+
+---
+
+## 另見
+
+- [Pact 文件](https://docs.pact.io/)
+- [Can I Deploy](https://docs.pact.io/pact_broker/can_i_deploy)
+- [消費者驅動合約（Consumer-Driven Contracts）](https://martinfowler.com/articles/consumerDrivenContracts.html) —— Martin Fowler
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|---------|------|---------|
+| 1.0.0 | 2026-05-05 | 初版發布：消費者驅動合約流程、向後相容視窗、發布閘門準則 |
+
+---
+
+## 授權
+
+本標準依 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)