AI Agent 文檔維護規範 (AI Agent Documentation Rules)

本文件定義所有 AI Agent（包含 Antigravity, GitHub Copilot, Gemini CLI, Claude 等）在協助維護、擴充與更新 OpenPassExam 專案時，必須強制遵循的文檔存放、術語規範與資安維護規則。

📌 核心規則 (Core Directives)

規則 1：所有安裝、建置與使用手冊一律集中於 app_docs/

• 範圍定義：
  • 專案或 App 的安裝教學 (Installation Guides)
  • 平台建置與編譯說明 (Build & Compilation Guides)
  • 使用者操作手冊 (User Manuals / Beginner Guides)
  • 雲端與伺服器部署步驟 (Deployment & Operations)
  • 常見問答與疑難排解 (Troubleshooting & FAQs)
• 要求：未來任何新增或修訂上述性質之 Markdown 文件，強制只能放在 app_docs/ 目錄，嚴禁在專案根目錄散落各類手冊。專案根目錄僅保留最基本的簡介與指向 app_docs/ 的導覽連結。

規則 2：繁體中文（台灣標準 zh-TW）原則

繁體中文文檔嚴格遵守台灣慣用網路、雲端與軟體工程技術術語：

• ✅ 伺服器 (Server) / ❌ 服務器
• ✅ 連接埠 (Port) / ❌ 端口
• ✅ 存放庫 / 儲存庫 (Repository) / ❌ 倉庫 / 代碼庫
• ✅ 路由 / 路由器 (Routing / Router) / ❌ 路由 / 路由器 (大陸發音與用法)
• ✅ 封包 (Packet) / ❌ 數據包
• ✅ 交換器 (Switch) / ❌ 交換機
• ✅ 快取 (Cache) / ❌ 緩存
• ✅ 無伺服器 (Serverless) / ❌ 無服務器
• ✅ 管線 (Pipeline) / ❌ 流水線
• ✅ 執行緒 (Thread) / ❌ 線程
• ✅ 身分驗證 (Authentication) / ❌ 認證
• ✅ 授權 (Authorization) / ❌ 鑑權
• ❌ 禁絕使用大陸非繁體中文術語。

規則 3：安全與機密嚴格零容忍 (Zero-Leakage Policy)

• 任何文檔或腳本中，絕對不得寫入或洩漏：
  • 實際的 API 金鑰 (API Keys, Token)
  • 服務帳戶私密憑證 (Service Account JSON)
  • 簽章金鑰密碼 (Keystore passwords, key.properties)
  • 使用者個人隱私資料
  • 具體真實之 GCP 專案 ID 或雲端機密路徑
• 必須一律採用環境變數、GCP Secret Manager 或預留佔位符（如 YOUR_PROJECT_ID、YOUR_API_KEY）表示。

規則 4：功能變更與文檔同步原則 (Documentation Sync)

• 當專案新增或調整以下重大架構時，必須主動同步修訂 app_docs/ 對應手冊：
  1. 認證與授權變更（如 Firebase Auth、Google Sign-in、RBAC 角色）。
  2. AI 模型調度與推論引擎升級（如 Gemini 版本升級、Gemma 4 端側引擎、降級級聯）。
  3. 部署管線與發布腳本更新（如 deploy.ps1、Cloud Run 參數、Firebase 網域授權）。