universal-dev-standards 4.1.0 → 4.2.0

package/bundled/locales/zh-TW/core/ai-friendly-architecture.md

@@ -0,0 +1,306 @@
+# AI 友善架構標準
+
+> **語言**: [English](../../../core/ai-friendly-architecture.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-01-21
+**適用範圍**: 所有與 AI 助手協作的軟體專案
+
+---
+
+## 目的
+
+本標準定義能最大化 AI 輔助開發效能的架構與文件實踐。遵循這些指南，專案將更容易被 AI 工具分析、理解和修改，同時保持人類可讀性。
+
+**參考概念**:
+- RLM（遞迴語言模型）上下文管理原則
+- 考慮 Token 的文件設計
+- 支援 AI 理解的模組化架構
+
+---
+
+## 目錄
+
+1. [核心原則](#核心原則)
+2. [模組設計標準](#模組設計標準)
+3. [上下文邊界標記](#上下文邊界標記)
+4. [文件分層](#文件分層)
+5. [元資料標準](#元資料標準)
+6. [查詢介面設計](#查詢介面設計)
+7. [AI 上下文配置](#ai-上下文配置)
+8. [反模式](#反模式)
+9. [實施清單](#實施清單)
+
+---
+
+## 核心原則
+
+### 1. 明確勝過隱含
+
+AI 助手在行為和結構明確記錄時表現最佳，而非依賴慣例推測。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   明確 vs 隱含                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ❌ 隱含（AI 難以理解）                                      │
+│  └── 魔術命名慣例                                            │
+│  └── 未記錄的資料夾結構                                      │
+│  └── 基於慣例的路由                                          │
+│  └── 假定框架行為已知                                        │
+│                                                              │
+│  ✅ 明確（AI 友善）                                          │
+│  └── 記錄模組職責                                            │
+│  └── 清楚標註進入點                                          │
+│  └── 明確宣告依賴關係                                        │
+│  └── 自我說明的配置檔案                                      │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2. 分層上下文
+
+以層次結構組織文件，讓 AI 可以根據任務複雜度存取適當的詳細程度。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  上下文分層策略                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  第一層：快速參考（< 500 tokens）                            │
+│  └── 單行描述                                                │
+│  └── 僅 API 簽名                                             │
+│  └── 關鍵進入點                                              │
+│                                                              │
+│  第二層：詳細指南（< 5,000 tokens）                          │
+│  └── 完整 API 文件                                           │
+│  └── 使用範例                                                │
+│  └── 配置選項                                                │
+│                                                              │
+│  第三層：完整範例（無限制）                                  │
+│  └── 完整實作範例                                            │
+│  └── 邊界案例文件                                            │
+│  └── 遷移指南                                                │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3. 語義邊界
+
+設計清楚的模組邊界，讓 AI 可以獨立分析元件，而不需要完整專案上下文。
+
+### 4. 可探索的結構
+
+確保專案結構可以透過分析配置檔案和進入點來理解，而不需閱讀所有原始碼。
+
+---
+
+## 模組設計標準
+
+### 模組層級單一職責
+
+每個模組應有明確定義的單一目的，可以用一句話總結。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   模組標頭範本                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  /**                                                         │
+│   * @module auth                                             │
+│   * @description 處理應用程式的使用者驗證和                  │
+│   *              Session 管理。                              │
+│   *                                                          │
+│   * @responsibility 驗證和授權                               │
+│   * @dependencies [database, crypto, config]                │
+│   * @exports {login, logout, verify, refreshToken}          │
+│   * @entrypoint ./index.ts                                  │
+│   */                                                         │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 清楚的輸入/輸出契約
+
+每個公開介面都應有明確的型別定義或文件說明。
+
+| 元素 | 要求 | 範例 |
+|------|------|------|
+| 函式參數 | 型別 + 描述 | `@param {string} email - 使用者電子郵件` |
+| 回傳值 | 型別 + 可能值 | `@returns {Promise<User \| null>}` |
+| 副作用 | 明確記錄 | `@sideeffect 寫入資料庫` |
+| 錯誤條件 | 所有可能錯誤 | `@throws {AuthError} 無效憑證` |
+
+### 明確的依賴宣告
+
+依賴應在模組層級宣告，而非隱藏在實作細節中。
+
+---
+
+## 上下文邊界標記
+
+### 模組標頭註解
+
+使用 AI 可以解析的標準化標頭註解，快速理解模組。
+
+```javascript
+/**
+ * ═══════════════════════════════════════════════════════════
+ * 模組：付款處理
+ * ═══════════════════════════════════════════════════════════
+ *
+ * 用途：處理所有付款相關操作，包括
+ *       處理、退款和訂閱管理。
+ *
+ * 依賴：
+ *   - stripe: 付款閘道整合
+ *   - database: 交易儲存
+ *   - events: 付款事件發布
+ *
+ * 匯出：
+ *   - processPayment(amount, method): 處理單筆付款
+ *   - refund(transactionId): 發出退款
+ *   - createSubscription(plan): 開始訂閱
+ *
+ * ═══════════════════════════════════════════════════════════
+ */
+```
+
+---
+
+## 文件分層
+
+### 第一層：快速參考（< 500 tokens）
+
+在每個主要模組建立 `QUICK-REF.md`：
+
+```markdown
+# Auth 模組 - 快速參考
+
+## 用途
+使用者驗證和 Session 管理。
+
+## 關鍵函式
+- `login(email, password)` → `Promise<Session>`
+- `logout(sessionId)` → `void`
+- `verify(token)` → `Promise<User | null>`
+
+## 配置
+- `AUTH_SECRET`: JWT 簽名密鑰
+- `SESSION_DURATION`: Session 生命週期（預設：24h）
+
+## 進入點
+`src/auth/index.ts`
+```
+
+### 第二層：詳細指南（< 5,000 tokens）
+
+主要 `README.md` 包含完整文件。
+
+### 第三層：完整範例（無限制）
+
+獨立的 `examples/` 目錄包含完整實作。
+
+---
+
+## 元資料標準
+
+### .ai-context.yaml 配置
+
+專用的 AI 上下文配置檔案：
+
+```yaml
+# .ai-context.yaml - AI 上下文配置
+version: 1.0.0
+
+project:
+  name: my-project
+  type: web-app  # web-app | library | cli | api | monorepo
+  primary-language: typescript
+
+modules:
+  - name: auth
+    path: src/auth/
+    entry: index.ts
+    description: 驗證和授權
+    dependencies: [database, crypto]
+    priority: high
+
+analysis-hints:
+  entry-points:
+    - src/main.ts
+  ignore-patterns:
+    - node_modules
+    - dist
+
+context-strategy:
+  max-chunk-size: 50000
+  overlap: 500
+  analysis-pattern: hierarchical
+```
+
+---
+
+## 反模式
+
+### ❌ 應避免的模式
+
+| 反模式 | 問題 | 解決方案 |
+|--------|------|----------|
+| **魔術字串** | AI 無法追蹤常數 | 使用有文件的型別常數 |
+| **隱含路由** | 隱藏行為 | 明確記錄路由映射 |
+| **全域狀態** | 不可預測的依賴 | 依賴注入，明確連結 |
+| **循環依賴** | 上下文混亂 | 清楚的層次依賴 |
+| **巨大檔案** | 上下文溢出 | 分割成專注的模組 |
+
+---
+
+## 實施清單
+
+### 快速開始（< 1 小時）
+
+- [ ] 建立 `.ai-context.yaml` 包含模組清單
+- [ ] 在專案根目錄新增 `QUICK-REF.md`
+- [ ] 在 README 中記錄進入點
+- [ ] 在主要檔案中新增模組標頭
+
+### 標準實施（< 1 天）
+
+- [ ] 完成 `.ai-context.yaml` 配置
+- [ ] 為每個主要模組新增 `QUICK-REF.md`
+- [ ] 記錄所有公開 API 的型別資訊
+- [ ] 在大型檔案中新增區段分隔
+- [ ] 建立依賴文件
+
+### 完整實施（< 1 週）
+
+- [ ] 所有模組的三層文件
+- [ ] 可搜尋的程式碼註解
+- [ ] 使用案例的範例目錄
+- [ ] 架構圖
+- [ ] 整合 CI 進行文件驗證
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-01-21 | 初始版本 |
+
+---
+
+## 相關標準
+
+- [專案結構](./project-structure.md) - 目錄組織
+- [文件結構](./documentation-structure.md) - 文件組織
+- [反幻覺](./anti-hallucination.md) - AI 準確性標準
+
+---
+
+## 授權
+
+本標準以 [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/docs/AI-AGENT-ROADMAP.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../docs/AI-AGENT-ROADMAP.md
-source_version: 2.2.0
-translation_version: 2.2.0
-last_synced: 2026-01-15
+source_version: 2.3.0
+translation_version: 2.3.0
+last_synced: 2026-01-22
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **語言**: [English](../../../docs/AI-AGENT-ROADMAP.md) | 繁體中文 | [简体中文](../../zh-CN/docs/AI-AGENT-ROADMAP.md)
 
-**版本**: 2.2.0
-**最後更新**: 2026-01-15
+**版本**: 2.3.0
+**最後更新**: 2026-01-22
 
 本文件提供 Universal Development Standards (UDS) 對 AI Agent 支援的完整參考。
 
@@ -19,16 +19,57 @@ status: current
 
 ## 目錄
 
-1. [快速參考](#1-快速參考)
-2. [整合深度](#2-整合深度)
-3. [Skills 系統](#3-skills-系統)
-4. [配置參考](#4-配置參考)
-5. [資源](#5-資源)
-6. [附錄：未來發展](#附錄未來發展)
+1. [UDS CLI 實作狀態](#1-uds-cli-實作狀態)
+2. [快速參考](#2-快速參考)
+3. [整合深度](#3-整合深度)
+4. [Skills 系統](#4-skills-系統)
+5. [配置參考](#5-配置參考)
+6. [資源](#6-資源)
+7. [附錄：未來發展](#附錄未來發展)
 
 ---
 
-## 1. 快速參考
+## 1. UDS CLI 實作狀態
+
+> **重要**: 本節描述的是 UDS CLI 對各工具的實作狀態，而非工具的原生能力。關於原生能力，請參閱[快速參考](#2-快速參考)。
+
+### 狀態定義
+
+| 狀態 | 定義 |
+|------|------|
+| `complete` | Skills + Commands 完整支援，已測試且生產就緒 |
+| `partial` | Skills 可用，Commands 受限或不支援 |
+| `preview` | 功能可用但為預覽版，可能有邊緣案例 |
+| `planned` | CLI 中程式碼存在但未完整測試 |
+| `minimal` | 僅生成規則檔，不支援 Skills/Commands |
+
+### 實作矩陣
+
+| AI 工具 | UDS 狀態 | Skills | Commands | 設定檔 | 備註 |
+|---------|:--------:|:------:|:--------:|--------|------|
+| **Claude Code** | ✅ complete | ✅ | 內建 | `CLAUDE.md` | Marketplace + User + Project 三層級 |
+| **OpenCode** | ✅ complete | ✅ | ✅ | `AGENTS.md` | 完整實作，可讀取 Claude 規則 |
+| Cline | 🔶 partial | ✅ | - | `.clinerules` | Skills 透過 fallback，Commands 使用 Workflow |
+| GitHub Copilot | 🔶 partial | ✅ | ✅ | `copilot-instructions.md` | 補充 Copilot Chat |
+| OpenAI Codex | 🔶 partial | ✅ | - | `AGENTS.md`（共用） | Skills 可用 |
+| Gemini CLI | 🧪 preview | ✅ | ✅ (TOML) | `GEMINI.md` | Commands 自動轉換為 TOML |
+| Roo Code | ⏳ planned | ✅ | ✅ | - | 實作存在，待測試 |
+| Cursor | 📄 minimal | - | - | `.cursorrules` | 僅規則檔 |
+| Windsurf | 📄 minimal | - | - | `.windsurfrules` | 僅規則檔 |
+| Antigravity | 📄 minimal | - | - | `INSTRUCTIONS.md` | 僅規則檔 |
+
+### 兩種「支援」的區別
+
+| 概念 | 定義 | 記錄位置 |
+|------|------|----------|
+| **工具原生能力** | AI 工具本身支援什麼功能 | [快速參考](#2-快速參考) |
+| **UDS CLI 實作** | UDS CLI 對該工具的實作程度 | 本節 |
+
+範例：Cursor 原生不支援 SKILL.md（工具能力），但 UDS CLI 可以為它生成 `.cursorrules`（實作狀態 = minimal）。
+
+---
+
+## 2. 快速參考
 
 ### 配置檔
 
@@ -43,6 +84,7 @@ status: current
 | Windsurf | `.windsurfrules` | 設定 UI | 6K/檔，總計 12K |
 | Gemini CLI | `.gemini/GEMINI.md` | `~/.gemini/GEMINI.md` | 支援 `@import` |
 | Cursor | `.cursor/rules/*.mdc` | `~/.cursor/rules/` | 需要 YAML frontmatter |
+| Antigravity | `.antigravity/` | `~/.antigravity/` | 最低支援，手動模式 |
 
 ### Skills 路徑
 
@@ -57,6 +99,7 @@ status: current
 | Windsurf | ✅ 完整 | `.windsurf/rules/` | 設定 UI | 2026/01 起支援 Skills |
 | Gemini CLI | ✅ 預覽 | `.gemini/skills/` | `~/.gemini/skills/` | v0.23+ 預覽版 |
 | Cursor | ❌ 否 | `.cursor/rules/` | `~/.cursor/rules/` | 僅 Rules，不支援 SKILL.md |
+| Antigravity | ❌ 否 | `.antigravity/skills/` | `~/.antigravity/skills/` | 不支援 SKILL.md |
 
 ### 斜線命令
 
@@ -71,6 +114,7 @@ status: current
 | Windsurf | ✅ | Rulebook | 自動產生 | 從 `.windsurfrules` |
 | Gemini CLI | ✅ | 系統 + 自訂 | `/clear`, `/memory`, `/mcp` | `.gemini/commands/*.toml` |
 | Cursor | ✅ | 內建 + 自訂 | `/summarize`, `/models` | `.cursor/commands/*.md` |
+| Antigravity | ❌ | N/A | N/A | N/A |
 
 ### 平台支援
 
@@ -82,7 +126,7 @@ status: current
 
 ---
 
-## 2. 整合深度
+## 3. 整合深度
 
 > **說明**: 截至 2026 年 1 月，Agent Skills (SKILL.md) 已成為業界標準。大多數主流 AI 程式碼工具現在都支援相同的 Skills 格式。
 
@@ -111,11 +155,20 @@ status: current
 - 尚未支援 SKILL.md 格式
 - 社群已提出功能請求
 
+### 最低支援
+
+**工具**: Antigravity
+
+- 不支援 SKILL.md
+- 不支援 AGENT.md
+- 僅手動執行模式
+- 為完整性而收錄
+
 ---
 
-## 3. Skills 系統
+## 4. Skills 系統
 
-### 3.1 UDS Skills 相容性
+### 4.1 UDS Skills 相容性
 
 | # | Skill | 斜線命令 | Claude | OpenCode | Cursor | Copilot |
 |---|-------|----------|:------:|:--------:|:------:|:-------:|
@@ -138,7 +191,7 @@ status: current
 | 17 | project-structure-guide | `/config` | 完整 | 完整 | 部分 | 無 |
 | 18 | logging-guide | - | 完整 | 完整 | 完整 | 完整 |
 
-### 3.2 Skills 路徑與啟用
+### 4.2 Skills 路徑與啟用
 
 #### Skills 探索路徑
 
@@ -153,6 +206,7 @@ status: current
 | Windsurf | `.windsurf/rules/` | 設定 UI | ✅ 是 |
 | Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` | ✅ 是 |
 | Cursor | `.cursor/rules/` | `~/.cursor/rules/` | ❌ 否 |
+| Antigravity | `.antigravity/skills/` | `~/.antigravity/skills/` | ❌ 否 |
 
 #### 啟用方式
 
@@ -167,10 +221,11 @@ status: current
 | Windsurf | 手動（@提及）、始終開啟、模型決定 |
 | Gemini CLI | 自動觸發、透過設定啟用/停用 |
 | Cursor | Glob 模式、`alwaysApply` 旗標（僅 rules） |
+| Antigravity | 僅手動 |
 
 **建議**：使用 `.claude/skills/` 作為預設安裝路徑 — 大多數工具都可讀取以獲得跨工具相容性。
 
-### 3.3 跨平台可攜性
+### 4.3 跨平台可攜性
 
 > **業界標準**: 截至 2025 年 12 月，SKILL.md 已被 OpenAI、GitHub、Google 及更廣泛的 AI 程式碼生態系統採用。
 
@@ -185,6 +240,7 @@ status: current
 | Windsurf | ✅ 完整 | 2026/01/09 |
 | Gemini CLI | ✅ 預覽版 | 2026/01/07 |
 | Cursor | ❌ 尚未 | 已請求 |
+| Antigravity | ❌ 否 | N/A |
 
 **跨平台安裝器**:
 - [skilz](https://github.com/skilz-ai/skilz) - 通用 Skills 安裝器（14+ 平台）
@@ -193,9 +249,9 @@ status: current
 
 ---
 
-## 4. 配置參考
+## 5. 配置參考
 
-### 4.1 配置檔
+### 5.1 配置檔
 
 | AI Agent | 專案配置 | 全域配置 | 字元限制 |
 |----------|----------|----------|----------|
@@ -208,8 +264,9 @@ status: current
 | GitHub Copilot | `.github/copilot-instructions.md` | 個人設定 | ~8KB |
 | OpenAI Codex | `AGENTS.md` | `~/.codex/AGENTS.md` | 32KB |
 | Gemini CLI | `GEMINI.md` | `~/.gemini/GEMINI.md` | 1M tokens |
+| Antigravity | N/A | `~/.antigravity/` | N/A |
 
-### 4.2 配置合併行為
+### 5.2 配置合併行為
 
 | AI Agent | 合併策略 | 優先順序（高到低） |
 |----------|----------|-------------------|
@@ -221,8 +278,9 @@ status: current
 | GitHub Copilot | 組合 | 個人 > 儲存庫 > 組織 |
 | OpenAI Codex | 串接 | 覆寫檔 > 基礎，較近者優先 |
 | Gemini CLI | 串接 | 所有檔案支援 `@import` |
+| Antigravity | N/A | N/A |
 
-### 4.3 Skills 檔案格式
+### 5.3 Skills 檔案格式
 
 > **標準格式**: 帶有 YAML frontmatter 的 SKILL.md 是大多數工具支援的通用格式。
 
@@ -237,10 +295,11 @@ status: current
 | Windsurf | ✅ SKILL.md | `.windsurfrules` | YAML |
 | Gemini CLI | ✅ SKILL.md | `GEMINI.md` | YAML |
 | Cursor | ❌ `.mdc` | `.cursor/rules/` | YAML (globs, alwaysApply) |
+| Antigravity | ❌ N/A | N/A | N/A |
 
 ---
 
-## 5. 資源
+## 6. 資源
 
 ### 官方文件
 
@@ -304,6 +363,7 @@ status: current
 
 | 版本 | 日期 | 變更 |
 |------|------|------|
+| 2.3.0 | 2026-01-21 | 新增 Antigravity 至所有表格以與 CLI 保持一致 |
 | 2.2.0 | 2026-01-15 | 新增多 Agent 安裝、Gemini CLI TOML 轉換 |
 | 2.1.0 | 2026-01-15 | 更新所有工具的 Skills 支援狀態（業界廣泛採用） |
 | 2.0.0 | 2026-01-15 | 重大重構：整合內容、減少表格 |

package/bundled/locales/zh-TW/integrations/gemini-cli/GEMINI.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../../integrations/gemini-cli/GEMINI.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-01-13
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-01-24
 status: current
 ---
 
@@ -89,10 +89,42 @@ status: current
 
 ---
 
+## 重構指南
+
+參考：`core/refactoring-standards.md`
+
+### 三層策略
+
+| 層級 | 策略 | 時間尺度 |
+|------|------|----------|
+| **戰術** | 童子軍法則、準備性重構、紅綠重構 | 分鐘 |
+| **戰略** | 絞殺者無花果、防腐層、分支抽象 | 週至月 |
+| **安全** | 特徵測試、草稿重構、尋找接縫 | 前置作業 |
+
+### 決策樹
+
+1. 在生產環境？否 → 考慮重寫
+2. 理解程式碼？否 → 先寫特徵測試
+3. 覆蓋率 >60%？否 → 先加測試
+4. 架構可挽救？否 → 絞殺者無花果；是 → 漸進重構
+
+### 快速參考
+
+| 情況 | 策略 |
+|------|------|
+| 功能被雜亂程式碼阻擋 | **準備性重構** |
+| 修 bug 的機會 | **童子軍法則** |
+| 替換遺留系統 | **絞殺者無花果** |
+| 與遺留系統共存 | **防腐層** |
+| 未測試的遺留程式碼 | **先寫特徵測試** |
+
+---
+
 ## 版本歷史
 
 | 版本 | 日期 | 變更 |
 |------|------|------|
+| 1.1.0 | 2026-01-21 | 新增重構指南章節 |
 | 1.0.0 | 2026-01-09 | 初始 Gemini CLI 指令檔案 |
 
 ---