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

package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md

@@ -0,0 +1,333 @@
+---
+source: ../../../docs/USAGE-MODES-COMPARISON.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-01-12
+status: current
+---
+
+# 使用模式比較：Skills vs 規範文件 vs 兩者並用
+
+> **語言**: [English](../../../docs/USAGE-MODES-COMPARISON.md) | 繁體中文
+>
+> **版本**: 1.0.0
+> **最後更新**: 2026-01-12
+
+本文件比較安裝 Universal Development Standards (UDS) 後三種使用模式的效果差異。
+
+---
+
+## 目錄
+
+1. [概覽](#概覽)
+2. [模式比較](#模式比較)
+3. [詳細比較](#詳細比較)
+4. [使用場景建議](#使用場景建議)
+5. [功能覆蓋](#功能覆蓋)
+6. [定量比較](#定量比較)
+7. [結論](#結論)
+
+---
+
+## 概覽
+
+### 模式 A：僅使用 Skills
+
+**配置方式**：
+- 安裝時選擇 `standardsScope: minimal`
+- Skills 位置：Plugin Marketplace（推薦）
+- 最小化規範文件複製到專案
+
+**包含內容**：
+- 16 個 Claude Code Skills（互動式命令）
+- 最小化規範文件（僅 reference 類別）
+
+### 模式 B：僅使用規範文件
+
+**配置方式**：
+- 安裝時選擇 `standardsScope: full`
+- 跳過 Skills 安裝（或選擇非 Claude Code 工具）
+- 完整規範文件複製到 `.standards/`
+
+**包含內容**：
+- 17 個核心規範文件
+- 整合檔案（.cursorrules、CLAUDE.md 等）
+- 無互動式 Skills
+
+### 模式 C：同時使用 Skills 與規範文件
+
+**配置方式**：
+- 安裝時選擇 `standardsScope: full` + Skills 安裝
+- 或透過 `contentMode: full` 獲得完整規範
+
+**包含內容**：
+- 16 個 Claude Code Skills
+- 17 個核心規範文件
+- 整合檔案
+
+---
+
+## 模式比較
+
+### 快速比較表
+
+| 面向 | 僅 Skills | 僅規範文件 | Skills + 規範文件 |
+|------|----------|-----------|------------------|
+| 互動式命令 | 16 個 | 無 | 16 個 |
+| 規範深度 | 中 | 高 | 高 |
+| Token 消耗 | 低 | 中-高 | 高 |
+| 多工具支援 | 僅 Claude Code | 全部 9 個 AI 工具 | 全部 9 個 AI 工具 |
+| 版本控制 | 外部管理 | Git 追蹤 | 混合 |
+| 自訂擴展 | 受限 | 完整 | 完整 |
+| 學習曲線 | 低 | 高 | 低 |
+
+### 最適合場景
+
+| 模式 | 推薦對象 |
+|------|---------|
+| **僅 Skills** | 個人開發者，專門使用 Claude Code |
+| **僅規範文件** | 多工具團隊、企業環境、離線使用 |
+| **Skills + 規範文件** | 完整體驗、學習 UDS、團隊入職 |
+
+---
+
+## 詳細比較
+
+### 互動性與使用體驗
+
+| 面向 | 僅 Skills | 僅規範文件 | Skills + 規範文件 |
+|------|----------|-----------|------------------|
+| 互動式命令 | 16 個可用 | 無 | 16 個可用 |
+| 上下文感知 | 自動偵測 | 需手動閱讀 | 自動偵測 |
+| 工作流程引導 | 逐步引導 | 需自行理解 | 逐步引導 |
+| 學習曲線 | 低 | 高 | 低 |
+
+**說明**：
+- Skills 提供 `/commit`、`/tdd`、`/review` 等命令進行互動引導
+- 規範文件需要開發者主動閱讀並應用
+- Skills 可自動偵測上下文（如 git status、專案語言）
+
+### 內容完整性
+
+| 面向 | 僅 Skills | 僅規範文件 | Skills + 規範文件 |
+|------|----------|-----------|------------------|
+| 規範深度 | 中 | 高 | 高 |
+| 範例數量 | 精簡 | 豐富 | 豐富 |
+| 決策矩陣 | 部分 | 完整 | 完整 |
+| 版本追蹤 | 否 | 是 | 是 |
+| 跨語言範例 | 部分 | 完整 | 完整 |
+
+**說明**：
+- Skills 提取規範文件的精華，但省略部分細節
+- 規範文件包含完整的決策樹、範例、和邊界情況
+- 如大規模重構模式（`refactoring-standards.md`）在 Skills 中無對應功能
+
+### 工具支援
+
+| 工具 | 僅 Skills | 僅規範文件 | Skills + 規範文件 |
+|------|----------|-----------|------------------|
+| Claude Code | 完整 | 基礎 | 完整 |
+| Cursor | 不支援 | 支援 | 支援 |
+| Windsurf | 不支援 | 支援 | 支援 |
+| Cline | 不支援 | 支援 | 支援 |
+| GitHub Copilot | 不支援 | 支援 | 支援 |
+| 其他 AI 工具 | 不支援 | 支援 | 支援 |
+
+**說明**：
+- Skills 僅支援 Claude Code
+- 規範文件可整合到所有 9 個支援的 AI 工具
+- 多工具團隊需要規範文件
+
+### 維護與更新
+
+| 面向 | 僅 Skills | 僅規範文件 | Skills + 規範文件 |
+|------|----------|-----------|------------------|
+| 更新方式 | Plugin 自動更新 | `uds update` | 混合 |
+| 版本控制 | 外部管理 | Git 追蹤 | 部分 |
+| 自訂擴展 | 受限 | 完整 | 完整 |
+| 團隊同步 | 需各自安裝 | Git 同步 | 混合 |
+
+**說明**：
+- Skills 在 Plugin Marketplace 集中管理，但無法版本控制
+- 規範文件可放入 Git，團隊自動同步
+- 自訂規則需要修改規範文件
+
+### Token 使用效率
+
+| 面向 | 僅 Skills | 僅規範文件 | Skills + 規範文件 |
+|------|----------|-----------|------------------|
+| 基礎 Token 消耗 | 低 | 中-高 | 高 |
+| 按需載入 | 是 | 否 | 部分 |
+| 重複內容 | 無 | 無 | 有 |
+
+**說明**：
+- Skills 按需載入，只在呼叫時消耗 token
+- 規範文件整合到 CLAUDE.md 後，每次對話都會載入
+- 同時使用時，Skills 與規範文件有部分內容重疊
+
+---
+
+## 使用場景建議
+
+### 場景 1：個人開發者 + 僅使用 Claude Code
+
+**推薦模式**：僅使用 Skills（模式 A）
+
+**原因**：
+- Token 消耗最低
+- 互動體驗最佳
+- 無需管理額外文件
+- `/commit`、`/tdd`、`/review` 命令足夠日常使用
+
+**配置方式**：
+```bash
+uds init -y --skills-location marketplace
+# standardsScope 將自動設為 minimal
+```
+
+### 場景 2：團隊開發 + 多種 AI 工具
+
+**推薦模式**：同時使用 Skills + 規範文件（模式 C）
+
+**原因**：
+- 規範文件可 Git 同步，確保團隊一致性
+- 非 Claude Code 使用者可使用規範文件
+- Skills 提供 Claude Code 使用者更好的體驗
+
+**配置方式**：
+```bash
+uds init -y --skills-location marketplace --content-mode index
+# 在互動提示中選擇多個 AI 工具
+```
+
+### 場景 3：嚴格規範要求的企業環境
+
+**推薦模式**：僅使用規範文件（模式 B）
+
+**原因**：
+- 可完全自訂規範內容
+- 完整的版本控制和審計追蹤
+- 不依賴外部 Plugin Marketplace
+- 適合需要離線工作的環境
+
+**配置方式**：
+```bash
+uds init -y --skills-location none --content-mode full
+```
+
+### 場景 4：學習 UDS 標準體系
+
+**推薦模式**：同時使用 Skills + 規範文件（模式 C）
+
+**原因**：
+- Skills 提供引導式學習
+- 規範文件提供深入參考
+- 可對照 Skills 行為與規範內容
+
+---
+
+## 功能覆蓋
+
+### Skills 強項但規範文件較弱的功能
+
+| 功能 | 對應 Skill |
+|------|-----------|
+| 方法論切換 | `/methodology switch` |
+| 階段檢查點提醒 | `methodology-system` |
+| 自動提交訊息生成 | `/commit` |
+| 互動式 TDD 循環 | `/tdd` |
+
+### 規範文件提供但 Skills 未涵蓋的功能
+
+| 功能 | 對應規範文件 |
+|------|-------------|
+| 大規模重構模式（Strangler Fig） | `refactoring-standards.md` |
+| 技術債評估矩陣 | `refactoring-standards.md` |
+| 完整錯誤碼分類體系 | `error-code-standards.md` |
+| 日誌採樣策略 | `logging-standards.md` |
+| 專案類型映射矩陣 | `documentation-writing-standards.md` |
+
+### 兩者均完整覆蓋的功能
+
+| 功能 | Skill | 規範文件 |
+|------|-------|---------|
+| Conventional Commits | `commit-standards` | `commit-message-guide.md` |
+| 測試金字塔 | `testing-guide` | `testing-standards.md` |
+| 代碼審查清單 | `code-review-assistant` | `code-review-checklist.md` |
+| 語義化版本 | `release-standards` | `versioning.md` |
+| CHANGELOG 格式 | `changelog-guide` | `changelog-standards.md` |
+
+---
+
+## 定量比較
+
+### 內容量比較
+
+| 指標 | 僅 Skills | 僅規範文件 | Skills + 規範文件 |
+|------|----------|-----------|------------------|
+| 檔案數量 | ~16 Skills | ~17 規範 | ~33 總計 |
+| 估計行數 | ~3,000 | ~8,000 | ~11,000 |
+| 估計 Token | ~15K | ~40K | ~50K |
+
+### 各領域功能覆蓋率
+
+| 領域 | 僅 Skills | 僅規範文件 | Skills + 規範文件 |
+|------|----------|-----------|------------------|
+| 版本管理 | 90% | 100% | 100% |
+| 測試規範 | 85% | 100% | 100% |
+| 代碼審查 | 95% | 100% | 100% |
+| 重構指引 | 30% | 100% | 100% |
+| 錯誤處理 | 70% | 100% | 100% |
+| 日誌規範 | 60% | 100% | 100% |
+
+---
+
+## 結論
+
+### 效果差異總結
+
+1. **互動性**：Skills > 規範文件（Skills 提供主動引導）
+2. **完整性**：規範文件 > Skills（規範文件涵蓋更多細節）
+3. **效率**：Skills > 規範文件（按需載入，token 消耗低）
+4. **靈活性**：規範文件 > Skills（可自訂、可版本控制）
+5. **多工具支援**：規範文件 > Skills（Skills 僅限 Claude Code）
+
+### 最佳實踐建議
+
+```
+個人開發者 + Claude Code
+  └─ 推薦：僅 Skills（模式 A）
+     └─ 配置：standardsScope: minimal + Plugin Marketplace
+
+團隊開發 + 混合工具
+  └─ 推薦：Skills + 規範文件（模式 C）
+     └─ 配置：standardsScope: full + Plugin Marketplace
+     └─ 規範文件納入 Git 管理
+
+企業環境 + 合規要求
+  └─ 推薦：僅規範文件（模式 B）
+     └─ 配置：standardsScope: full + 無 Skills
+     └─ 可完全離線使用
+```
+
+### 總體評價
+
+| 模式 | 適合對象 | 評分 |
+|------|---------|------|
+| 僅 Skills | 個人快速開發 | ★★★★☆ |
+| 僅規範文件 | 多工具團隊/企業 | ★★★★☆ |
+| Skills + 規範文件 | 完整體驗/學習 | ★★★★★ |
+
+**結論**：三種模式各有優勢，選擇取決於團隊規模、工具組合、和合規要求。對於希望獲得最完整體驗的用戶，建議同時使用 Skills 與規範文件。
+
+---
+
+## 相關文件
+
+- [CLI 初始化選項](CLI-INIT-OPTIONS.md) - 完整 CLI 選項指南
+- [採用指南](../../../adoption/ADOPTION-GUIDE.md) - 標準採用指南
+- [Skills README](../../../skills/claude-code/README.md) - Claude Code Skills 文件
+
+---
+
+**由 Universal Dev Standards 團隊維護**

package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md

@@ -0,0 +1,215 @@
+---
+source: ../../../docs/WINDOWS-GUIDE.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Windows 開發指南
+
+本指南提供使用和貢獻 Universal Development Standards 的 Windows 特定說明。
+
+---
+
+## 先決條件
+
+### 必要
+
+- **Node.js** >= 18.0.0 ([下載](https://nodejs.org/))
+- **Git for Windows** ([下載](https://git-scm.com/download/win))
+  - 包含 Git Bash 用於執行 shell 腳本
+
+### 推薦
+
+- **Windows Terminal** - 更好的終端體驗
+- **Visual Studio Code** - 跨平台編輯器
+- **PowerShell 7+** - 現代 PowerShell ([下載](https://github.com/PowerShell/PowerShell))
+
+---
+
+## 安裝選項
+
+### 選項一：npm（推薦）
+
+```powershell
+npm install -g universal-dev-standards
+uds init
+```
+
+### 選項二：本地開發
+
+**PowerShell：**
+```powershell
+git clone https://github.com/AsiaOstrich/universal-dev-standards.git
+cd universal-dev-standards\cli
+npm install
+npm link
+```
+
+**Git Bash：**
+```bash
+git clone https://github.com/AsiaOstrich/universal-dev-standards.git
+cd universal-dev-standards/cli
+npm install
+npm link
+```
+
+---
+
+## 安裝 Claude Code Skills
+
+**推薦：Plugin Marketplace**
+```bash
+/plugin marketplace add AsiaOstrich/universal-dev-standards
+/plugin install universal-dev-standards@asia-ostrich
+```
+
+**替代方案：手動複製（PowerShell）**
+```powershell
+New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.claude\skills
+Copy-Item -Recurse skills\claude-code\commit-standards $env:USERPROFILE\.claude\skills\
+```
+
+Skills 會安裝到：`%USERPROFILE%\.claude\skills\`
+
+---
+
+## 翻譯同步檢查
+
+**PowerShell：**
+```powershell
+.\scripts\check-translation-sync.ps1
+
+# 帶區域參數
+.\scripts\check-translation-sync.ps1 -Locale zh-TW
+```
+
+**Git Bash：**
+```bash
+./scripts/check-translation-sync.sh
+
+# 帶區域參數
+./scripts/check-translation-sync.sh zh-TW
+```
+
+---
+
+## Git 鉤子
+
+Git 鉤子使用 Husky 設定，透過 Git Bash（包含在 Git for Windows 中）自動運作。不需要額外設定。
+
+當您在 `cli/` 目錄執行 `npm install` 時，Husky 會自動設定 pre-commit 鉤子。
+
+---
+
+## 常見問題與解決方案
+
+### 1. 腳本執行政策
+
+**問題：** 「此系統上已停用腳本執行」
+
+**解決方案：**
+```powershell
+# 以系統管理員身份執行 PowerShell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+### 2. 換行符問題
+
+儲存庫包含 `.gitattributes` 自動處理換行符。如果您遇到問題：
+
+```bash
+# 在 Git Bash 中
+git config core.autocrlf true
+git rm --cached -r .
+git reset --hard
+```
+
+### 3. 路徑長度限制
+
+在 Git 中啟用長路徑：
+
+```bash
+git config --system core.longpaths true
+```
+
+### 4. PowerShell 版本
+
+- **Windows PowerShell** (v5.1) - 內建於 Windows
+- **PowerShell** (v7+) - 跨平台，推薦
+
+本專案的腳本在兩個版本都能運作。
+
+### 5. npm 全域安裝路徑
+
+如果全域安裝後找不到 `uds` 命令：
+
+```powershell
+# 檢查 npm 全域 bin 路徑
+npm config get prefix
+
+# 如需要，添加到 PATH（替換為您的實際路徑）
+$env:PATH += ";C:\Users\YourName\AppData\Roaming\npm"
+```
+
+---
+
+## 環境變數
+
+CLI 支援 Unix 和 Windows 環境變數：
+
+| Unix | Windows | 說明 |
+|------|---------|------|
+| `$HOME` | `$env:USERPROFILE` | 主目錄 |
+| `~/.claude/skills/` | `%USERPROFILE%\.claude\skills\` | Skills 位置 |
+
+---
+
+## 開發工作流程
+
+```powershell
+# 1. 克隆儲存庫
+git clone https://github.com/AsiaOstrich/universal-dev-standards.git
+cd universal-dev-standards
+
+# 2. 安裝 CLI 依賴
+cd cli
+npm install
+
+# 3. 執行測試
+npm test
+
+# 4. 執行程式碼檢查
+npm run lint
+
+# 5. 連結以進行本地測試
+npm link
+
+# 6. 測試 CLI 命令
+uds list
+uds init --help
+```
+
+---
+
+## 終端推薦
+
+| 終端 | 最適合 | 備註 |
+|------|--------|------|
+| **Windows Terminal** | 日常使用 | 現代化，可自訂 |
+| **Git Bash** | 執行 shell 腳本 | 類 Unix 環境 |
+| **PowerShell 7** | Windows 腳本 | 跨平台 |
+| **VS Code Terminal** | 開發 | 整合體驗 |
+
+---
+
+## 相關文件
+
+- [主 README](../../README.md) - 專案概述
+- [CLI README](../../cli/README.md) - CLI 文件
+- [採用指南](../adoption/ADOPTION-GUIDE.md) - 完整採用指南
+
+---
+
+**需要協助？** 在 [GitHub Issues](https://github.com/AsiaOstrich/universal-dev-standards/issues) 開啟 issue

package/bundled/locales/zh-TW/integrations/codex/AGENTS.md

@@ -0,0 +1,115 @@
+---
+source: ../../../../integrations/codex/AGENTS.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-01-13
+status: current
+---
+
+# 通用開發標準
+
+本專案遵循通用文件規範，以確保高品質、無幻覺的程式碼與文件。
+
+---
+
+## 規格驅動開發 (SDD) 優先
+
+**規則**：當專案中整合了 SDD 工具（如 OpenSpec、Spec Kit 等）並提供特定命令時，你必須優先使用這些命令，而非手動編輯檔案。
+
+**偵測方式**：
+- OpenSpec：檢查是否有 `openspec/` 目錄或 `openspec.json`
+- Spec Kit：檢查是否有 `specs/` 目錄或 `.speckit` 配置
+
+**原因**：
+- **一致性**：工具確保規格結構遵循嚴格的 schema
+- **可追溯性**：命令自動處理日誌、ID 和連結
+- **安全性**：工具內建驗證以防止無效狀態
+
+參考：`core/spec-driven-development.md`
+
+---
+
+## 防幻覺協議
+
+參考：`core/anti-hallucination.md`
+
+### 1. 證據基礎分析
+
+- 在分析檔案之前，你必須先讀取檔案。
+- 不要猜測 API、類別名稱或函式庫版本。
+- 如果你還沒看過程式碼，請說明：「我需要讀取 [檔案] 來確認」。
+
+### 2. 來源標註
+
+每個關於程式碼的事實陳述都必須標註來源：
+- 程式碼：`[來源: 程式碼] 路徑/檔案:行號`
+- 外部文件：`[來源: 外部] http://網址 (存取日期: 日期)`
+
+### 3. 確定性分類
+
+使用標籤表示信心程度：
+- `[已確認]` - 已從來源驗證
+- `[推論]` - 邏輯推論
+- `[假設]` - 合理假設
+- `[未知]` - 無法確定
+
+### 4. 建議
+
+當提供選項時，你必須明確說明「推薦」的選擇及其理由。
+
+---
+
+## 文件與提交
+
+### Commit 訊息
+
+遵循 Conventional Commits 格式（參考：`core/commit-message-guide.md`）：
+
+```
+<類型>(<範圍>): <主題>
+
+<內文>
+
+<頁尾>
+```
+
+**類型**：feat、fix、docs、chore、test、refactor、style
+
+### 檔案結構
+
+遵循文件結構指南（參考：`core/documentation-structure.md`）。
+
+### 品質檢查
+
+完成前，依據 `core/checkin-standards.md` 驗證工作：
+- [ ] 程式碼編譯成功
+- [ ] 所有測試通過
+- [ ] 無硬編碼的秘密資訊
+- [ ] 如適用，已更新文件
+
+---
+
+## 程式碼審查標準
+
+參考：`core/code-review-checklist.md`
+
+審查程式碼時，檢查：
+1. **功能性** - 是否按預期運作？
+2. **安全性** - 無漏洞（OWASP Top 10）？
+3. **效能** - 演算法和查詢是否高效？
+4. **可維護性** - 程式碼是否整潔、易讀？
+5. **測試** - 測試覆蓋率是否足夠？
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-01-09 | 初始 OpenAI Codex 整合 |
+
+---
+
+## 授權
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。