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

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/core/ai-instruction-standards.md

@@ -1,5 +1,5 @@
 ---
-source: core/ai-instruction-standards.md
+source: ../../../core/ai-instruction-standards.md
 source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2026-01-14