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

package/bundled/locales/zh-TW/core/anti-hallucination.md

@@ -0,0 +1,691 @@
+---
+source: ../../../core/anti-hallucination.md
+source_version: 1.3.1
+translation_version: 1.3.1
+last_synced: 2025-12-25
+status: current
+---
+
+# AI 協作防幻覺標準
+
+> **語言**: [English](../../../core/anti-hallucination.md) | 繁體中文
+
+**版本**: 1.3.1
+**最後更新**: 2025-12-24
+**適用範圍**: 所有使用 AI 助理協作的軟體專案
+
+---
+
+## 目的
+
+本標準定義 AI 助理的嚴格準則，以防止在分析程式碼、提出建議或撰寫系統文件時產生幻覺（生成錯誤或未經驗證的資訊）。
+
+---
+
+## AI 助手互動規範
+
+### 對話語言
+
+AI 助手應適應使用者的偏好語言。當專案指定對話語言時，請遵循以下準則:
+
+| 情境 | 準則 | 範例 |
+|------|------|------|
+| 對話互動 | 使用專案指定語言 | 繁體中文、英文等 |
+| 確定性標籤 | 使用專案指定語言 | `[已確認]` 或 `[Confirmed]` |
+| 錯誤訊息解釋 | 使用專案指定語言 | 以使用者語言解釋編譯/執行錯誤 |
+| 技術術語 | 保留原文 | JWT、BCrypt、API、Token |
+| 程式碼註解 | 遵循專案慣例 | 通常為英文 |
+| Commit 訊息 | 遵循專案慣例 | 如 `feat(auth): 新增登入功能` |
+
+### 選項建議原則
+
+**規則**: 當提供多個選項時，必須同時提出最推薦的選項並說明理由。
+
+| 情境 | 要求 | 範例 |
+|------|------|------|
+| 提供 2+ 選項 | 必須明確標示推薦選項並說明理由 | 「推薦選項 A，因為...」 |
+| 選項優劣明顯 | 直接推薦最佳選項，說明理由 | 「建議使用 BCrypt，因為安全性較高」 |
+| 選項各有優劣 | 推薦最適合當前情境的選項，說明權衡考量 | 「考量專案需求，推薦選項 B」 |
+| 無法判斷優劣 | 說明需要哪些資訊才能給出推薦 | 「需要確認效能需求才能推薦」 |
+
+**範例**:
+
+❌ **錯誤**:
+```
+有三個選項:
+1. 使用 Redis 快取
+2. 使用記憶體快取
+3. 使用檔案快取
+
+請選擇一個。
+```
+
+✅ **正確**:
+```
+有三個選項:
+1. 使用 Redis 快取
+2. 使用記憶體快取
+3. 使用檔案快取
+
+**推薦: 選項 1 (Redis)**: 考量專案已有 Redis 基礎設施且需要跨實例共享快取，Redis 是最適合的選擇。
+```
+
+### 下一步建議
+
+**規則**: 當完成一項任務或子任務時，AI 助手**必須**建議合理的下一步工作，並明確標示**最推薦**的選項。
+
+**指引**:
+- **主動性**: 不要等待使用者問「接下來呢？」。
+- **情境相關**: 建議應遵循專案的工作流程（如：提案 -> 實作 -> 測試）。
+- **明確推薦**: 使用 `[推薦]` 或 `[Recommended]` 標示最佳路徑。
+
+**範例**:
+
+✅ **正確**:
+```
+任務完成: API 端點已實作。
+
+**建議下一步**:
+1. **[推薦]** 為新端點新增單元測試 (`src/tests/api/`)
+2. 更新 API 文件 (`docs/api-reference.md`)
+3. 開始前端整合
+```
+
+---
+
+## 核心原則
+
+### 1. 僅基於證據的分析
+
+**規則**: 僅分析和引用已明確提供或讀取的內容。
+
+**指引**:
+- ✅ 分析已使用檔案讀取工具讀取的程式碼檔案
+- ✅ 引用已擷取的文件
+- ✅ 引用已檢查的設定檔
+- ❌ 不要推測未見過的 API、函式或設定
+- ❌ 不要在未驗證的情況下假設框架行為
+- ❌ 不要捏造需求細節
+
+**範例**:
+
+✅ **正確**:
+```
+[證據] 在 src/auth/service.ts:45，JWT 驗證邏輯使用 'jsonwebtoken' 函式庫
+[證據] package.json 檔案（第 12-18 行）列出 Express 4.18.2 作為相依項目
+```
+
+❌ **錯誤**:
+```
+此系統使用 Redis 進行快取（程式碼未審查）
+UserService 應該有 authenticate() 方法（API 未驗證）
+需求指出我們需要 SSO 登入支援（需求未確認）
+```
+
+---
+
+### 2. 明確來源標註
+
+**規則**: 所有引用必須包含來源類型、位置與可驗證性資訊。
+
+#### 2.1 來源類型
+
+| 來源類型 | 標籤 | 說明 | 可靠度 |
+|---------|------|------|--------|
+| 專案程式碼 | `[來源: 程式碼]` | 直接從程式碼庫讀取 | ⭐⭐⭐⭐⭐ 最高 |
+| 專案文件 | `[來源: 文件]` | README、Wiki、程式碼註解 | ⭐⭐⭐⭐ 高 |
+| 外部文件 | `[來源: 外部]` | 官方文件（附 URL） | ⭐⭐⭐⭐ 高 |
+| 網路搜尋 | `[來源: 搜尋]` | 搜尋結果（包含日期） | ⭐⭐⭐ 中 |
+| AI 知識 | `[來源: 知識]` | AI 訓練資料（需驗證） | ⭐⭐ 低 |
+| 使用者提供 | `[來源: 使用者]` | 使用者對話中的資訊 | ⭐⭐⭐ 中 |
+
+#### 2.2 標註格式
+
+**程式碼引用**:
+```
+[來源: 程式碼] 檔案路徑:行號 - 描述
+```
+
+**外部文件**:
+```
+[來源: 外部] URL - 描述（版本: x.x.x，存取: YYYY-MM-DD）
+```
+
+**AI 知識**:
+```
+[來源: 知識] 主題 - 描述（⚠️ 需要驗證）
+```
+
+#### 2.3 範例
+
+✅ **正確**:
+```
+[來源: 程式碼] UserService.cs:142 - 密碼雜湊使用 BCrypt
+[來源: 程式碼] app.config:23-28 - 資料庫連線字串設定為 SQL Server
+[來源: 文件] README.md:15 - 專案需要 .NET 8.0 SDK
+[來源: 外部] https://react.dev/reference/react/useState - useState hook API（版本: React 18，存取: 2025-12-10）
+[來源: 搜尋] "Express.js middleware order" - 中介軟體依註冊順序執行（搜尋: 2025-12-10）
+[來源: 知識] HTTP 狀態碼 - 404 表示資源未找到（⚠️ 一般知識，請驗證您的 API）
+[來源: 使用者] 使用者在對話中表示 - 驗證必須支援 OAuth2
+```
+
+❌ **錯誤**:
+```
+驗證服務使用 BCrypt（無來源類型，無檔案引用）
+設定檔案中某處有資料庫連線（模糊引用）
+我認為 README 提到 .NET 8（不確定語言，無來源）
+React useState 的運作方式是...（無版本，無引用）
+```
+
+#### 2.4 版本敏感性
+
+**規則**: 引用函式庫、框架或 API 時，必須包含版本資訊（如有）。
+
+**為何重要**:
+- API 在不同版本間會改變
+- 已棄用的功能可能仍出現在 AI 訓練資料中
+- 安全性漏洞是版本特定的
+
+**範例**:
+```
+✅ [來源: 外部] Next.js App Router (v14.x) - Server Components 是預設值
+✅ [來源: 程式碼] package.json:12 - 使用 "express": "^4.18.2"
+❌ "Next.js 使用 Server Components"（哪個版本？v12 和 v14 行為不同）
+```
+
+---
+
+### 3. 分類確定性等級
+
+**規則**: 明確區分已確認事實、推測與未知事項。
+
+**分類標籤**:
+
+| 標籤 | 使用時機 |
+|-----|---------|
+| `[已確認]` | 直接來自程式碼/文件的證據 |
+| `[推測]` | 基於現有證據的邏輯推論 |
+| `[假設]` | 基於常見模式（需驗證）|
+| `[未知]` | 資訊不可得 |
+| `[需確認]` | 需要使用者澄清 |
+
+**範例**:
+
+✅ **正確**:
+```
+[已確認] src/database/connection.ts:12 - 使用 PostgreSQL 驅動程式 'pg'
+[推測] 基於 src/repositories/ 中的 repository 模式，可能使用依賴注入
+[假設] 專案可能使用 OAuth2，但需要審查驗證設定
+[未知] API 速率限制策略未記錄
+[需確認] 新功能是否應支援多租戶？
+```
+
+❌ **錯誤**:
+```
+系統使用 Redis（無分類，無證據）
+我們應該實作快取（以事實呈現，非建議）
+使用者需要 SSO 支援（假設以已確認需求呈現）
+```
+
+---
+
+### 4. 禁止行為
+
+**AI 助手不得**:
+
+1. **捏造 API 或函式簽名**
+   - ❌ 不要編造方法名稱、參數或回傳類型
+   - ✅ 要讀取實際原始碼或詢問使用者
+
+2. **假設需求**
+   - ❌ 不要猜測使用者需求或業務規則
+   - ✅ 當需求模糊時要提出澄清問題
+
+3. **推測未讀取的程式碼**
+   - ❌ 不要描述未審查檔案的功能
+   - ✅ 要明確表示「需要讀取 [檔案] 以確認」
+
+4. **編造設定**
+   - ❌ 不要假設環境變數、設定鍵或資料庫結構
+   - ✅ 要審查實際設定檔
+
+5. **憑空產生錯誤或 Bug**
+   - ❌ 不要在無證據的情況下聲稱程式碼有問題
+   - ✅ 要分析實際程式碼並引用特定行號
+
+6. **提出選項但不推薦**
+   - ❌ 不要列出選項後要求使用者選擇而不提供指引
+   - ✅ 要永遠包含推薦選項並附理由
+
+#### 詳細範例
+
+##### 1. 捏造 API 或函式名稱
+
+❌ **錯誤**:
+```
+助理: 「你可以呼叫 UserService.GetUserById(int id) 來取得使用者」
+```
+**問題**: 方法不存在或簽名不同。
+
+✅ **正確**:
+```
+助理: 「讓我讀取 UserService 檔案以找到正確的方法簽名。」
+
+[讀取 src/services/UserService.cs 後]
+
+[來源: 程式碼] UserService.cs:45 - 找到方法: FindUser(Guid userId)
+實際方法使用 Guid 而非 int 作為使用者 ID 參數。
+```
+
+---
+
+##### 2. 假設使用者需求
+
+❌ **錯誤**:
+```
+助理: 「系統需要支援 OAuth 和 SAML 以提供企業 SSO。」
+```
+**問題**: 使用者只詢問認證，未指定協議。
+
+✅ **正確**:
+```
+助理: 「[需確認] 您提到需要驗證功能。
+能否澄清:
+1. 這是給內部使用者、外部客戶，還是兩者都有？
+2. 您需要企業 SSO（OAuth/SAML）還是簡單的使用者名稱/密碼？
+3. 有任何需要整合的現有身分提供者嗎？
+
+這將幫助我推薦最適合的方法。」
+```
+
+---
+
+##### 3. 描述未讀取的程式碼功能
+
+❌ **錯誤**:
+```
+助理: 「PaymentService 處理信用卡處理並與 Stripe 整合。」
+```
+**問題**: 檔案未讀取，功能僅從名稱假設。
+
+✅ **正確**:
+```
+助理: 「我在您的專案結構中看到名為 PaymentService.cs 的檔案。
+
+[未知] 我尚未讀取此檔案，因此無法確認其功能。
+
+您想讓我讀取 src/services/PaymentService.cs 以了解:
+- 它使用哪個支付提供者？
+- 支援哪些支付方式？
+- 交易如何處理？」
+```
+
+---
+
+##### 4. 編造設定細節
+
+❌ **錯誤**:
+```
+助理: 「設定 DATABASE_URL 環境變數以連線到 PostgreSQL。
+您的連線字串應在 appsettings.json 的 'ConnectionStrings:DefaultConnection' 下。」
+```
+**問題**: 設定結構和變數名稱未經驗證即假設。
+
+✅ **正確**:
+```
+助理: 「讓我檢查您的實際設定檔。」
+
+[讀取 appsettings.json 後]
+
+[來源: 程式碼] appsettings.json:8-12 - 找到資料庫設定:
+- 連線字串鍵: "ConnectionStrings:MainDb"（非 "DefaultConnection"）
+- 使用 SQL Server，非 PostgreSQL
+- 額外設定 "CommandTimeout": 30
+
+您的專案使用與 .NET 預設不同的鍵名稱。
+```
+
+---
+
+##### 5. 斷言程式碼有 Bug（無證據）
+
+❌ **錯誤**:
+```
+助理: 「您的驗證程式碼有安全性漏洞 -
+您沒有正確進行密碼雜湊。」
+```
+**問題**: 未讀取實際程式碼即聲稱有 Bug。
+
+✅ **正確**:
+```
+助理: 「讓我審查您的驗證實作。」
+
+[讀取 src/auth/AuthService.cs 後]
+
+[已確認] AuthService.cs:67 - 找到密碼雜湊實作:
+- 使用 BCrypt，work factor 為 12 ✅
+- Salt 自動生成 ✅
+- 未偵測到時序攻擊漏洞 ✅
+
+您的密碼雜湊實作遵循安全性最佳實務。
+在審查的程式碼中未發現問題。
+```
+
+---
+
+##### 6. 選項未附推薦
+
+❌ **錯誤**:
+```
+助理: 「您可以使用: 1) JWT 2) Session 3) OAuth。您偏好哪個？」
+```
+**問題**: 列出選項但未提供指引或考慮情境。
+
+✅ **正確**:
+```
+助理: 「基於您的需求:
+
+**選項**:
+1. JWT - 無狀態、可擴展、適合 API
+2. Session - 伺服器端狀態、傳統 Web 應用程式
+3. OAuth - 第三方身分提供者
+
+**推薦: JWT**
+
+[推測] 基於您的微服務架構（見於 docker-compose.yml），
+JWT 是最適合的，因為:
+- 無狀態: 跨服務不需要 session 儲存
+- 可擴展: 每個服務可獨立驗證 token
+- 標準: 在您的技術堆疊（.NET、React）中有良好支援
+
+如果之後需要社交登入，可以在 JWT 之上加入 OAuth。」
+```
+
+---
+
+## 實施檢查清單
+
+在對程式碼、需求或架構做出任何陳述前，請驗證:
+
+- [ ] **來源已驗證**
+  - 我是否已讀取實際的檔案/文件？
+
+- [ ] **來源類型已標註**
+  - 我是否已指定來源類型？（`[來源: 程式碼]`、`[來源: 外部]`、`[來源: 知識]` 等）
+
+- [ ] **引用已標註**
+  - 我是否已包含檔案路徑與行號（程式碼）？
+  - 我是否已包含 URL 與存取日期（外部文件）？
+
+- [ ] **版本已標註**
+  - 我是否已包含適用的函式庫/框架版本？
+
+- [ ] **確定性已分類**
+  - 我是否已標註為 [已確認]、[推測]、[假設]、[未知] 或 [需確認]？
+
+- [ ] **AI 知識已標記**
+  - 我是否已對 `[來源: 知識]` 標記 ⚠️ 驗證警告？
+
+- [ ] **無捏造**
+  - 我是否避免了捏造 API、設定或需求？
+
+- [ ] **使用者澄清**
+  - 我是否對模糊點請求澄清？
+
+- [ ] **包含推薦**
+  - 當提出選項時，我是否包含了推薦選項？
+
+---
+
+## 審查情境
+
+### 情境 1: 程式碼分析
+
+**使用者請求**: 「審查驗證邏輯」
+
+**❌ 不良回應**:
+```
+您的驗證系統使用 JWT 搭配 RS256 簽名。
+Token 在 1 小時後過期。
+您應該加入 refresh token 支援。
+```
+**問題**: 未讀取程式碼即做出聲明，假設實作細節。
+
+**✅ 良好回應**:
+```
+[需確認] 哪個檔案包含驗證邏輯？
+可能的位置包括:
+- src/auth/
+- src/services/auth
+- src/middleware/
+
+請引導我找到正確的檔案，以便我提供準確分析。
+
+或者，我可以搜尋程式碼庫中與驗證相關的檔案。
+```
+
+---
+
+### 情境 2: 架構建議
+
+**使用者請求**: 「我應該如何架構新的付款模組？」
+
+**❌ 不良回應**:
+```
+基於您現有的架構，您應該:
+1. 在 src/services/ 建立 PaymentService
+2. 使用 Stripe API
+3. 將交易儲存在 payments 資料表
+```
+**問題**: 未經證據即假設架構、支付提供者和資料庫結構。
+
+**✅ 良好回應**:
+```
+為了提供準確的建議，我需要了解您目前的架構:
+
+[需確認]
+1. 您計劃使用哪個支付提供者？（Stripe、PayPal、自訂等）
+2. 您現有的服務層結構是什麼？
+3. 您使用什麼資料庫？
+
+能否分享:
+- 專案結構（ls -R src/ 或類似）
+- 現有服務範例
+- 資料庫結構或 ORM 模型
+
+一旦我審查了這些，就能建議與您的模式一致的結構。
+```
+
+---
+
+### 情境 3: Bug 調查
+
+**使用者請求**: 「登入失敗」
+
+**❌ 不良回應**:
+```
+問題可能在您的 validateCredentials() 函式中。
+您可能需要在比對前對密碼進行雜湊。
+```
+**問題**: 未看程式碼即猜測原因。
+
+**✅ 良好回應**:
+```
+要調查登入失敗，我需要更多資訊:
+
+[需確認]
+1. 您看到什麼錯誤訊息？（主控台日誌、錯誤回應）
+2. 哪個檔案包含登入邏輯？
+3. 能否分享相關的程式碼片段或日誌？
+
+建議的除錯步驟:
+- 分享登入控制器/服務程式碼
+- 提供主控台/伺服器的錯誤日誌
+- 描述預期與實際行為
+
+一旦我審查了實際程式碼和錯誤，就能找出根本原因。
+```
+
+---
+
+### 情境 4: 技術選型
+
+**使用者請求**: 「我應該使用什麼快取解決方案？」
+
+**❌ 不良回應**:
+```
+您有幾個選項:
+1. Redis
+2. Memcached
+3. 記憶體快取
+
+讓我知道您想使用哪一個。
+```
+**問題**: 列出選項但未推薦或考慮情境。
+
+**✅ 良好回應**:
+```
+基於可用的選項:
+1. Redis - 分散式、持久化、豐富的資料結構
+2. Memcached - 簡單、快速、分散式
+3. 記憶體快取 - 僅本機、無需設定
+
+**推薦: Redis**
+
+[需確認] 在最終決定前，我想了解:
+- 您需要跨多個實例共享快取嗎？
+- 需要資料持久化嗎？
+- 您現有的基礎設施是什麼？
+
+如果您已有 Redis 基礎設施或需要跨實例共享，
+Redis 是最佳選擇。如果這是單實例應用程式且有
+簡單的快取需求，記憶體快取就足夠了。
+```
+
+---
+
+## AI 助理工作流程
+
+```
+┌─────────────────────────────────┐
+│  收到使用者請求                  │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  識別所需資訊                    │
+│  - 程式碼檔案？                  │
+│  - 設定？                        │
+│  - 需求？                        │
+└─────────────┬───────────────────┘
+              │
+              ▼
+         ┌────┴────┐
+         │  可取得？ │
+         └────┬────┘
+              │
+      ┌───────┴───────┐
+      │               │
+     是              否
+      │               │
+      ▼               ▼
+┌──────────┐   ┌─────────────┐
+│  讀取/   │   │  向使用者   │
+│  分析    │   │  詢問資訊   │
+└────┬─────┘   └──────┬──────┘
+     │                │
+     ▼                ▼
+┌─────────────────────────────────┐
+│  為回應加上標籤:                 │
+│  - [已確認] 用於事實             │
+│  - [推測] 用於推論               │
+│  - [需確認] 用於缺口             │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  引用來源（檔案:行號）           │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  包含推薦                        │
+│  （如提出選項）                  │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  提供回應                        │
+└─────────────────────────────────┘
+```
+
+---
+
+## 語言無關應用
+
+本標準適用於任何程式語言、框架或領域:
+
+- **Web 開發**: 未經證據不假設 Express/Django/Spring Boot
+- **行動開發**: 未經證據不假設 React Native/Flutter
+- **資料科學**: 未經證據不假設 TensorFlow/PyTorch
+- **DevOps**: 未經證據不假設 Docker/Kubernetes
+
+**通用規則**: 先讀取，再分析，永遠以證據報告。
+
+---
+
+## 與程式碼審查整合
+
+執行程式碼審查時，應用這些原則:
+
+1. **引用行號**: 所有審查評論必須引用特定行號
+2. **以證據分類嚴重性**:
+   - `[已確認 Bug]` - 程式碼明顯損壞
+   - `[潛在問題]` - 程式碼可能造成問題
+   - `[建議]` - 改善想法（非缺陷）
+3. **避免假設**: 如不確定設計意圖，詢問作者
+
+**審查評論範本**:
+```
+[檔案:行號] - [嚴重性]
+[問題描述與程式碼摘錄]
+[證據或推理]
+[建議修正或澄清問題]
+```
+
+---
+
+## 相關標準
+
+- [測試標準](testing-standards.md) - 確保驗證 AI 分析結果（或使用 `/testing-guide` 技能）
+- [程式碼審查清單](code-review-checklist.md) - 審查 AI 生成內容
+- [程式碼簽入標準](checkin-standards.md) - AI 協作簽入流程
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.3.1 | 2025-12-24 | 新增: 相關標準章節 |
+| 1.3.0 | 2025-12-22 | 增強: 禁止行為章節，新增詳細對比範例 |
+| 1.2.0 | 2025-12-15 | 新增: AI 助手互動規範章節（對話語言、推薦原則） |
+| 1.1.0 | 2025-12-10 | 增強來源標註，新增來源類型、版本敏感性與可靠度評級 |
+| 1.0.0 | 2025-11-12 | 初版發布 |
+
+---
+
+## 授權
+
+本標準以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
+您可以自由調整用於您的專案，但需註明出處。
+
+---
+
+**專案特定化**
+
+專案可透過以下方式擴充本標準:
+- 領域特定驗證需求（如醫療領域的 HIPAA 合規檢查）
+- 工具特定指引（如如何驗證 Terraform 設定）
+- 團隊特定證據格式（如 JIRA ticket 引用）
+- AI 助手對話的語言偏好