---
source: ../../../core/ai-friendly-architecture.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-04-22
status: current
---

# 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)
