Development Standards / 开发要求与编码规范
一個技能、一套流程、兩種資源語言。
配對資源修訂 / 双语资源配对修订：2026-10-05.9。此識別碼標識資源包，不代表專案批准或驗證通過。
語言選擇 / Language Selection
- 優先遵循使用者明確指定的規則語言；否則，中文請求使用
zh-CN，英文請求使用en。其他語言使用英文資源，並以使用者的語言回覆。請勿從 UI 元數據或原始檔案的語言推斷使用者的偏好。 - 對話時，遵循使用者要求的語言，否則遵循其當前請求的語言。對於每份文件，優先遵循其明確要求的語言，否則遵循專案既有的文件慣例，最後才遵循對話語言。使用對應的範本；對於其他語言，可改編英文範本。請勿作為副作用而翻譯無關檔案或重新命名程式碼識別碼。
- 開始工作前，僅讀取下方對應的核心規範，然後僅讀取與任務相關的參考資料。請求的文件語言可能與規則語言不同；請不要因此載入兩套完整的資源集。
| 核心規範 / Baseline | 讀取條件 / When to read |
|---|---|
| 中文規範 | 規則語言為中文 |
| English Standards | 規則語言為英文或使用英文回退 |
共同約束 / Shared Invariants
- 正式開發時，先確認需求，再確認本次實施範圍的完整模組/架構設計；新專案還需明確確認技術棧。部分確認僅涵蓋指定的範圍，必要的相依項目也必須已確認，不得隱含納入。在適用的閘門通過之前，不得進行實作或初始化。重複使用真實且適用的確認，不得偽造。
- 在架構設計階段，複雜模組必須使用架構圖，複雜流程必須使用流程圖表示，並隨設計文件保存，且與模組/介面說明一致。缺少必要的圖示時，該範圍的設計視為不完整；圖示不取代合約，也不增加審批階段。簡單設計及唯讀/輕量任務不要求補畫全專案圖。
- 需要進行介面設計時，基於相同的範圍需求與代表性頁面，交付三套有實質差異、且可於瀏覽器中檢視的 HTML 視覺原型，重點關注美觀度、版面配置、排版及視覺層級。靜態 HTML/CSS 示意頁面即可，JavaScript 與輕量互動預設為可選；當使用者明確要求互動演示時，則按指定範圍實作。提供入口及真實渲染檢查結果，記錄取捨與使用者選擇後，再正式實施。隔離的設計工作不繞過需求/技術棧/架構閘門，也不授權真實服務操作；重複使用有效且適用的既有選擇，唯讀審查及維持既定設計的修復不強制重新選擇。
- 開始編碼時，檢查本次實施範圍是否使用資料庫。如果使用，則必須在資料庫相關程式碼之前輸出並保存其設計，預設為
docs/database-design.md：新資料庫需提出方案，既有資料庫需先核對並重複使用/更新現有設計。不使用資料庫則不產生該文件。此為編碼階段的交付物，不是架構批准的前置附件，不增加審批階段；仍需遵守範圍變更與資料操作安全要求，唯讀工作不授權編輯。 - 每次完整的專案程式碼變更，包括錯誤修復與重構，都必須按照既定方案，增加受影響產品的版本。交付前更新真實的版本入口及必要的同步項目，並報告舊值、新值與位置。以一次完整變更計數，而非每次檔案編輯或重試次數；純文件/唯讀工作不觸發產品版本更新；方案不明或權限衝突時需先釐清。版本更新不授權發布，也不豁免相容性要求。
- 合格的「低風險局部修復」旨在恢復明確的預期行為；合格「行為保持重構」則保留可觀察的行為、錯誤與副作用。兩者均須限於授權範圍內，不得新增功能、改變合約/邊界或涉及高風險。需簡述目標、依據、範圍與驗證方式，不要求追溯補寫歷史產品文件或重複審批。若有歧義需先釐清，當範圍或風險擴大時，需升級受影響的流程。
- 對於客戶端/伺服器產品，伺服器端的變更必須保持低版本產品 Agent 的協定、介面、欄位語義及核心流程，不得強制升級 Agent。受影響的互動需遵循使用者/專案的相容範圍，並提供實際的低版本證據；不相容、驗證失敗或缺失會阻斷合併/發布，而非僅是警告。此處的 Agent 指軟體客戶端，而非大型語言模型。
- 遵守使用者範圍、倉庫規則及更高優先級的指令。唯讀請求不授權編輯，批准不授予無關的提交、推送、PR、部署、生產資料或外部寫入權限。根據實際證據報告未驗證事項，自行審查不得冒充為獨立審查。
翻譯維護 / Translation Maintenance
| 術語 / Term | 含義 / Meaning |
|---|---|
| 必須 / Required | 適用時須滿足，非建議 |
| 不得 / Must not | 禁止的操作 |
| 建議 / Recommended | 優先採用，可依根據調整 |
| 已確認 / Approved | 對指定內容與範圍的真實確認 |
| 已驗證 / Verified | 相關檢查實際通過，不等同於批准或部署 |
references/zh-CN 和 assets/zh-CN 是中文規則/範本來源，對應的 en 檔案是譯文，不構成獨立的政策。修改時需同步更新對應的檔案、連結、README 及受影響的行為場景，並更新入口點、兩份 README 及資源頭部的配對修訂標識；標識一致不證明語義等價。保持上述術語表、任務模式、安全約束與證據標準等價。僅切換語言不使批准失效或授予實施權限。發現差異時應報告並僅核對受影響的中文來源，不得默默選擇更寬鬆的譯文；若無法核對來源，需說明不確定性，不得聲稱相關閘門已通過。更高優先級的指令始終優先。