universal-dev-standards 4.2.0 → 5.0.0-beta.10

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

@@ -0,0 +1,214 @@
+---
+source: ../../../../skills/ai-instruction-standards/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-02-05
+status: current
+scope: partial
+description: |
+  建立和維護 AI 指令檔案（CLAUDE.md、.cursorrules 等）並採用適當結構。
+  使用時機：建立 AI 指令檔案、區分通用與專案特定規則、配置 AI 工具。
+  關鍵字：CLAUDE.md, cursorrules, windsurfrules, clinerules, AI instructions, system prompt, 指令檔案, AI 設定.
+---
+
+# AI 指令檔案標準指南
+
+> **語言**: [English](../../../../skills/ai-instruction-standards/SKILL.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-01-25
+**適用範圍**: Claude Code Skills
+
+---
+
+> **核心標準**: 本技能實作 [AI 指令檔案標準](../../core/ai-instruction-standards.md)。完整方法論文件請參閱核心標準。
+
+## 目的
+
+本技能協助建立和維護 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 |
+
+### 核心原則：通用 vs 專案特定
+
+| 類型 | 包含內容 | 範例 |
+|------|----------|------|
+| **通用** | 通用規則 | 「提交前執行測試」 |
+| **專案特定** | 具體命令 | 「提交前執行 `npm test`」 |
+
+### 建議配置
+
+```markdown
+# [專案名稱] - AI 指令
+
+## 通用標準
+<!-- 適用於任何專案的規則 -->
+- Commit 訊息格式
+- 程式碼審查清單
+- 測試標準
+- 反幻覺規則
+
+---
+
+## 專案特定配置
+<!-- 此專案獨有的設定 -->
+
+### 技術棧
+[你的技術在此]
+
+### 快速命令
+[你的建置/測試/部署命令]
+
+### 檔案結構
+[你的專案結構]
+```
+
+## 詳細指南
+
+完整標準請參閱：
+- [AI 指令檔案標準](../../core/ai-instruction-standards.md)
+
+### AI 優化格式（Token 效率）
+
+AI 助手可使用 YAML 格式檔案以減少 Token 使用：
+- 基礎標準：`ai/standards/ai-instruction-standards.ai.yaml`
+
+## 內容指南
+
+### 通用內容（保持通用）
+
+| 類別 | 良好範例 |
+|------|----------|
+| **提交標準** | 「遵循 Conventional Commits 格式」 |
+| **程式碼審查** | 「使用 BLOCKING、IMPORTANT、SUGGESTION 前綴」 |
+| **測試** | 「維持最低 80% 覆蓋率」 |
+| **AI 行為** | 「分析前務必先讀取程式碼」 |
+
+**通用區段應避免：**
+- 特定命令（`npm test`、`pytest`）
+- 固定路徑（`cli/src/`、`/var/www/`）
+- 版本號（`Node.js 18`、`Python 3.11`）
+- 專案名稱和 URL
+
+### 專案特定內容
+
+| 類別 | 範例 |
+|------|------|
+| **技術棧** | Node.js 18、React 18、PostgreSQL 15 |
+| **命令** | `npm run lint`、`./scripts/deploy.sh` |
+| **檔案結構** | `src/`、`cli/`、`tests/` |
+| **團隊慣例** | 繁體中文註解 |
+
+## 標籤慣例
+
+### 選項 A：區段標題
+
+```markdown
+## 通用標準
+[通用內容]
+
+## 專案特定配置
+[專案特定內容]
+```
+
+### 選項 B：行內標記
+
+```markdown
+> ⚠️ **專案特定**：本區段包含此專案獨有的配置。
+
+### 技術棧
+...
+```
+
+### 選項 C：註解標註
+
+```markdown
+<!-- 通用：以下適用於所有專案 -->
+### Commit 訊息格式
+...
+
+<!-- 專案特定：為你的專案自訂 -->
+### 快速命令
+...
+```
+
+## 多工具配置
+
+使用多個 AI 工具時，保持一致性：
+
+```
+project/
+├── CLAUDE.md              # Claude Code 指令
+├── .cursorrules           # Cursor 指令（可從 CLAUDE.md 匯入）
+├── .windsurfrules         # Windsurf 指令
+└── .github/
+    └── copilot-instructions.md  # Copilot 指令
+```
+
+**最佳實踐**：建立共用的 `docs/ai-standards.md` 並從各工具檔案引用，避免重複。
+
+## 維護檢查清單
+
+提交 AI 指令檔案變更前：
+
+- [ ] 通用區段不包含專案特定的路徑、命令或版本
+- [ ] 專案特定區段有明確標記
+- [ ] 標準文件的交叉引用正確
+- [ ] 格式與現有區段一致
+
+---
+
+## 配置偵測
+
+本技能支援專案特定配置。
+
+### 偵測順序
+
+1. 檢查是否存在 `CLAUDE.md` 或等效檔案
+2. 分析內容結構是否區分通用/專案特定
+3. 若未找到，**建議建立結構化 AI 指令檔案**
+
+### 首次設定
+
+若未找到 AI 指令檔案：
+
+1. 詢問：「此專案沒有 AI 指令檔案。是否要建立一個？」
+2. 確定專案類型和技術棧
+3. 產生包含適當區段的範本
+4. 若包含敏感資訊，新增到 `.gitignore`
+
+---
+
+## 相關標準
+
+- [AI 指令檔案標準](../../core/ai-instruction-standards.md) - 核心標準
+- [文件撰寫標準](../../core/documentation-writing-standards.md) - 撰寫指南
+- [反幻覺規範](../../core/anti-hallucination.md) - AI 準確性規則
+- [AI 友善架構](../../core/ai-friendly-architecture.md) - 上下文優化
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-01-25 | 初始發布 |
+
+---
+
+## 授權
+
+本技能以 [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/skills/atdd-assistant/SKILL.md

@@ -0,0 +1,71 @@
+---
+source: ../../../../skills/atdd-assistant/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-02-10
+status: current
+description: |
+  引導驗收測試驅動開發（ATDD）流程，用於定義和驗證使用者故事。
+  使用時機：定義驗收條件、使用者故事驗證、ATDD 流程。
+  關鍵字：atdd, acceptance, user story, INVEST, 驗收測試, 使用者故事, 驗收條件。
+---
+
+# ATDD 助手
+
+> **語言**: [English](../../../../skills/atdd-assistant/SKILL.md) | 繁體中文
+
+引導驗收測試驅動開發（ATDD）流程，用於定義和驗證使用者故事。
+
+## ATDD 循環
+
+WORKSHOP ──► DISTILLATION ──► DEVELOPMENT ──► DEMO ──► DONE
+
+## 工作流程
+
+### 1. WORKSHOP - 定義驗收條件
+PO 提出使用者故事，團隊提出澄清問題，共同定義驗收條件。
+
+### 2. DISTILLATION - 轉換為測試
+將驗收條件轉換為可執行的測試格式，消除歧義，取得 PO 簽核。
+
+### 3. DEVELOPMENT - 實作
+執行驗收測試（初始應失敗），使用 BDD/TDD 進行實作，迭代直到全部通過。
+
+### 4. DEMO - 向利害關係人展示
+展示通過的驗收測試，示範可運作的功能，取得正式驗收。
+
+### 5. DONE - 完成
+PO 已驗收，程式碼已合併，故事已關閉。
+
+## INVEST 準則
+
+| 準則 | 說明 | Criterion | Description |
+|------|------|-----------|-------------|
+| **I**ndependent | 可獨立開發 | Independent | Can be developed separately |
+| **N**egotiable | 可協商細節 | Negotiable | Details can be discussed |
+| **V**aluable | 提供商業價值 | Valuable | Delivers business value |
+| **E**stimable | 可估算工作量 | Estimable | Can estimate effort |
+| **S**mall | 一個 Sprint 可完成 | Small | Fits in one sprint |
+| **T**estable | 有明確驗收條件 | Testable | Has clear acceptance criteria |
+
+## 使用者故事格式
+
+```
+As a [role],
+I want [feature],
+So that [benefit].
+
+### Acceptance Criteria
+- Given [context], when [action], then [result]
+```
+
+## 使用方式
+
+- `/atdd` - 啟動互動式 ATDD 會話
+- `/atdd "user can reset password"` - 針對特定功能進行 ATDD
+- `/atdd US-123` - 針對現有使用者故事進行 ATDD
+
+## 參考
+
+- 詳細指南：[guide.md](./guide.md)
+- 核心規範：[acceptance-test-driven-development.md](../../../../core/acceptance-test-driven-development.md)

package/bundled/locales/zh-TW/skills/atdd-assistant/acceptance-criteria-guide.md

@@ -0,0 +1,428 @@
+---
+source: ../../../../skills/atdd-assistant/acceptance-criteria-guide.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-02-05
+status: current
+---
+
+# 驗收標準撰寫指南
+
+**版本**: 1.0.0
+**最後更新**: 2026-01-19
+
+---
+
+## 概述
+
+驗收標準（AC）定義用戶故事被視為完成必須滿足的條件。良好撰寫的 AC 確保共同理解並啟用自動化測試。
+
+---
+
+## 用戶故事的 INVEST 準則
+
+撰寫驗收標準前，確保用戶故事遵循 INVEST：
+
+| 原則 | 描述 | 要問的問題 |
+|------|------|----------|
+| **I**ndependent 獨立 | 可以不依賴其他故事開發 | 「這需要先完成另一個故事嗎？」 |
+| **N**egotiable 可協商 | 細節可以討論，非合約 | 「範圍有彈性嗎？」 |
+| **V**aluable 有價值 | 傳遞價值給使用者或企業 | 「為什麼這很重要？」 |
+| **E**stimable 可估算 | 團隊可以估算 | 「我們理解需要什麼嗎？」 |
+| **S**mall 小 | 小到可以在一個 Sprint 內完成 | 「我們可以在 < 1 週內完成嗎？」 |
+| **T**estable 可測試 | 可以通過測試驗證 | 「我們怎麼知道它完成了？」 |
+
+---
+
+## 驗收標準格式
+
+### Given-When-Then（推薦）
+
+```markdown
+### AC-1: [標準名稱]
+**Given** [前置條件 / 初始情境]
+**And** [額外前置條件]
+**When** [動作 / 事件]
+**And** [額外動作]
+**Then** [預期結果]
+**And** [額外預期結果]
+**But** [預期結果的例外]
+```
+
+### 範例
+
+```markdown
+### AC-1: 使用有效憑證成功登入
+**Given** 我在登入頁面
+**And** 我有一個已註冊帳號
+**When** 我輸入我的電子郵件 "user@example.com"
+**And** 我輸入我的密碼 "correctpassword"
+**And** 我點擊登入按鈕
+**Then** 我應該被重新導向到儀表板
+**And** 我應該看到帶有我名字的歡迎訊息
+```
+
+---
+
+## 完整用戶故事範本
+
+```markdown
+## 用戶故事: [US-XXX] [標題]
+
+**身為** [角色/人物]
+**我想要** [功能/能力]
+**以便** [好處/價值]
+
+---
+
+## 驗收標準
+
+### AC-1: [Happy path - 主要成功情境]
+**Given** [前置條件]
+**When** [動作]
+**Then** [預期結果]
+
+### AC-2: [替代路徑]
+**Given** [不同前置條件]
+**When** [動作]
+**Then** [不同預期結果]
+
+### AC-3: [錯誤處理]
+**Given** [前置條件]
+**When** [無效動作]
+**Then** [錯誤處理 / 復原]
+
+### AC-4: [邊界案例]
+**Given** [邊界條件]
+**When** [動作]
+**Then** [適當行為]
+
+---
+
+## 範圍外
+- [明確不包含的功能]
+- [延後至未來的增強]
+- [未涵蓋的變體]
+
+---
+
+## 技術備註
+- [實作限制]
+- [依賴]
+- [效能需求]
+- [安全考量]
+
+---
+
+## 開放問題
+- [ ] [需要澄清的問題]
+- [ ] [需要驗證的假設]
+
+---
+
+## 元資料
+- **優先級**: [高/中/低]
+- **估算**: [故事點數]
+- **Sprint**: [Sprint 編號]
+- **相關規格**: [SPEC-XXX 如適用]
+```
+
+---
+
+## 撰寫良好的驗收標準
+
+### DO's 和 DON'Ts
+
+| 應該做 | 不應該做 |
+|--------|---------|
+| 從使用者角度撰寫 | 從系統角度撰寫 |
+| 使用商業語言 | 使用技術術語 |
+| 具體且明確 | 模糊或抽象 |
+| 包含可衡量的結果 | 使用主觀用語 |
+| 保持標準獨立 | 建立相互依賴 |
+| 涵蓋 happy path 和邊界案例 | 只涵蓋 happy path |
+
+### 好與壞的範例
+
+```markdown
+# ❌ 壞：模糊且不可測試
+AC-1: 使用者可以輕鬆重設密碼
+AC-2: 系統快速發送電子郵件
+AC-3: 體驗對使用者友善
+
+# ✅ 好：具體且可測試
+AC-1: 密碼重設請求
+Given 我在登入頁面
+And 我有一個電子郵件為 "user@example.com" 的註冊帳號
+When 我點擊「忘記密碼」
+And 我輸入我的電子郵件 "user@example.com"
+Then 我應該看到「重設連結已寄至您的電子郵件」
+And 我應該在 5 分鐘內收到電子郵件
+And 電子郵件應該包含 24 小時有效的重設連結
+
+# ❌ 壞：技術術語
+AC-1: POST /api/auth/reset 回傳 202
+AC-2: Redis 佇列在 SLA 內處理
+AC-3: SendGrid webhook 已確認
+
+# ✅ 好：商業語言
+AC-1: 重設電子郵件送達
+Given 我已請求密碼重設
+When 系統處理我的請求
+Then 我應該在 5 分鐘內收到電子郵件
+And 電子郵件應該來自 "noreply@example.com"
+```
+
+---
+
+## 驗收標準類別
+
+### 1. Happy Path
+
+主要成功情境 - 一切正常運作時會發生什麼。
+
+```markdown
+### AC-1: 成功結帳
+Given 我的購物車有商品
+And 我有有效的付款方式
+When 我完成結帳流程
+Then 我的訂單應該被確認
+And 我應該收到確認電子郵件
+```
+
+### 2. 錯誤處理
+
+當事情出錯時會發生什麼。
+
+```markdown
+### AC-2: 付款被拒絕
+Given 我的購物車有商品
+When 我嘗試使用無效的卡片結帳
+Then 我應該看到「付款被拒絕」
+And 我的購物車仍應該包含我的商品
+And 不應該建立訂單
+```
+
+### 3. 邊界案例
+
+邊界條件和不尋常的情境。
+
+```markdown
+### AC-3: 購物車商品達到上限
+Given 我的購物車有 100 件商品（允許的最大數量）
+When 我嘗試新增另一件商品
+Then 我應該看到「購物車已滿」
+And 該商品不應該被新增
+```
+
+### 4. 授權
+
+誰可以做什麼。
+
+```markdown
+### AC-4: 僅限管理員存取
+Given 我以一般使用者身份登入
+When 我嘗試存取管理面板
+Then 我應該看到「存取被拒絕」
+And 我應該被重新導向到首頁
+```
+
+### 5. 驗證
+
+資料和輸入驗證。
+
+```markdown
+### AC-5: 電子郵件格式驗證
+Given 我在註冊表單上
+When 我輸入無效的電子郵件格式 "not-an-email"
+Then 我應該看到「請輸入有效的電子郵件地址」
+And 表單不應該被提交
+```
+
+### 6. 效能（如適用）
+
+非功能性需求。
+
+```markdown
+### AC-6: 搜尋回應時間
+Given 我在搜尋頁面
+When 我搜尋「筆電」
+Then 結果應該在 2 秒內顯示
+And 應該顯示至少 10 個結果
+```
+
+---
+
+## 驗收標準檢查清單
+
+完成 AC 前，驗證：
+
+```
+清晰度
+□ 新團隊成員能理解嗎？
+□ 沒有技術術語嗎？
+□ 足夠具體可以實作嗎？
+
+可測試性
+□ 可以自動化嗎？
+□ 結果可衡量嗎？
+□ 有明確的通過/失敗標準嗎？
+
+完整性
+□ Happy path 涵蓋了嗎？
+□ 錯誤情境涵蓋了嗎？
+□ 邊界案例考慮了嗎？
+□ 安全影響處理了嗎？
+
+獨立性
+□ 可以獨立測試嗎？
+□ 沒有依賴其他 AC 嗎？
+□ 沒有假設測試順序嗎？
+
+商業價值
+□ 傳遞使用者價值嗎？
+□ PO 能解釋為什麼重要嗎？
+□ 與商業目標一致嗎？
+```
+
+---
+
+## AC 反模式
+
+| 反模式 | 範例 | 問題 | 修復 |
+|--------|------|------|------|
+| **模糊** | 「系統應該快」 | 不可衡量 | 「回應時間 < 2 秒」 |
+| **技術性** | 「API 回傳 200 OK」 | 商業無法驗證 | 「使用者看到成功訊息」 |
+| **複合** | 「使用者可以建立、編輯和刪除」 | 太多行為 | 拆分為獨立 AC |
+| **缺少 Given** | 「當我點擊提交，訂單建立」 | 沒有情境 | 新增 Given 子句 |
+| **缺少 Then** | 「假設我已登入，當我點擊登出」 | 沒有驗證 | 新增 Then 子句 |
+| **相依** | 「假設 AC-1 通過...」 | 不獨立 | 自包含設定 |
+
+---
+
+## 各功能類型範例
+
+### 使用者認證
+
+```markdown
+## 用戶故事: 使用者登入
+
+**身為** 註冊使用者
+**我想要** 登入我的帳號
+**以便** 我可以存取我的個人化內容
+
+### AC-1: 成功登入
+Given 我在登入頁面
+And 我有一個電子郵件為 "user@example.com" 的註冊帳號
+When 我輸入我的電子郵件 "user@example.com"
+And 我輸入我正確的密碼
+And 我點擊登入按鈕
+Then 我應該被重新導向到我的儀表板
+And 我應該看到「歡迎回來，[使用者名稱]」
+
+### AC-2: 密碼錯誤登入失敗
+Given 我在登入頁面
+When 我輸入我的電子郵件 "user@example.com"
+And 我輸入錯誤的密碼
+And 我點擊登入按鈕
+Then 我應該看到「電子郵件或密碼無效」
+And 我應該停留在登入頁面
+And 密碼欄位應該被清空
+
+### AC-3: 帳號鎖定
+Given 我已失敗登入 3 次
+When 我嘗試再次登入
+Then 我應該看到「帳號暫時鎖定」
+And 我應該可以選擇密碼重設
+And 我應該在 15 分鐘內無法登入
+```
+
+### 電子商務結帳
+
+```markdown
+## 用戶故事: 套用折扣碼
+
+**身為** 客戶
+**我想要** 在我的訂單套用折扣碼
+**以便** 我可以在購買時省錢
+
+### AC-1: 有效的百分比折扣
+Given 我的購物車商品總計 $100
+When 我套用折扣碼 "SAVE10"
+Then 我的總計應該減少到 $90
+And 我應該看到「已套用 10% 折扣」
+
+### AC-2: 有效的固定金額折扣
+Given 我的購物車商品總計 $100
+When 我套用折扣碼 "FLAT5"
+Then 我的總計應該減少到 $95
+And 我應該看到「已套用 $5 折扣」
+
+### AC-3: 過期的折扣碼
+Given 我的購物車有商品
+When 我套用折扣碼 "EXPIRED2023"
+Then 我應該看到「此折扣碼已過期」
+And 我的總計應該保持不變
+
+### AC-4: 最低購買要求
+Given 我的購物車總計 $30
+When 我套用折扣碼 "MIN50"（需要最低 $50）
+Then 我應該看到「需要最低購買 $50」
+And 我的總計應該保持不變
+
+### AC-5: 每筆訂單一個折扣碼
+Given 我已套用折扣碼 "SAVE10"
+When 我嘗試套用另一個折扣碼 "SAVE20"
+Then 我應該看到「每筆訂單只能使用一個折扣碼」
+And 我原本的折扣應該保留
+```
+
+---
+
+## 將 AC 對應到測試
+
+### 從 AC 到 Gherkin
+
+```markdown
+### AC-1: 成功的密碼重設
+**Given** 我有一個註冊帳號
+**When** 我請求密碼重設
+**And** 我點擊電子郵件中的連結
+**And** 我輸入新的有效密碼
+**Then** 我的密碼應該被更改
+**And** 我應該能用新密碼登入
+```
+
+變成：
+
+```gherkin
+@AC-1
+Scenario: 成功的密碼重設
+  Given 我有一個電子郵件為 "user@example.com" 的註冊帳號
+  When 我為 "user@example.com" 請求密碼重設
+  And 我點擊電子郵件中的重設連結
+  And 我輸入新密碼 "NewSecureP@ss123"
+  And 我確認新密碼
+  Then 我應該看到「密碼已成功更改」
+  And 我應該能用 "NewSecureP@ss123" 登入
+```
+
+### 從 AC 到 FitNesse
+
+```
+!|Password Reset|
+|email|action|result|
+|user@example.com|request reset|link sent|
+|user@example.com|click expired link|error: expired|
+|user@example.com|click valid link|reset form shown|
+|user@example.com|submit new password|password changed|
+```
+
+---
+
+## 相關資源
+
+- [ATDD 工作流程指南](./atdd-workflow.md)
+- [ATDD 核心標準](../../../../core/acceptance-test-driven-development.md)
+- [Gherkin 指南](../bdd-assistant/gherkin-guide.md)
+- [需求助手](../requirement-assistant/SKILL.md)