十條核心信念
與 blueprint 的關係:這十條就是預設藍圖的
principles欄位,init會將它們逐字轉譯進專案的手冊與 AI Agent 守則。十條全部由 Agent 在每次改動時把關,而不是交給 lint —— 原因正是第七條自己。運作機制見運作契約。
所有規則收斂之後,即為以下十條底層信念。手冊其餘各部分均為這些信念的展開。
1. 依責任切分,而非依大小切分
切分的訊號是「此處做了幾件事」,而非「檔案過長」。行數屬於衍生訊號;max-lines 是唯一以行數為準的最後防線(max-statements 與函式層級的量測僅供初篩)。
2. 單一真實來源
衍生值一律以推導方式取得(computed / useMemo),不得存為可能失去同步的可變狀態;同一筆資料不得在兩處各自維護。
3. 介面收窄
輸入收窄、輸出精簡 —— 使非法狀態在型別層面即無法表達,並使呼叫端僅依賴其真正需要的部分。
4. 知識置於需要它的位置
衍生邏輯下放至子元件;可寫狀態置於「最靠近的共同讀寫者」;生命週期內建於擁有該職責的單元 —— 不向上堆疊。
5. 對後端資料:不破壞、不造假、不代為修補
保留後端資料的原始結構;對結構漂移設置防護;資料缺漏時如實呈現空白或錯誤狀態 —— 不以假資料充當後備,亦不以前端手段掩蓋應由後端解決的問題。
6. 死碼要麼刪除、要麼明確標示
沒有使用者的抽象即為死碼;完成修改時應一併清除孤兒檔案;確有保留必要的停用程式碼,以 @deprecated 標註並指向說明文件。
7. 程式碼檢查是審查的起點,而非結論
機械性量測(行數、複雜度、依賴數量)僅供初篩;內聚性、狀態是否經過建模、是否維持單一真實來源、不變量是否具備結構保證,唯有程式碼審查能夠判定。檢查全數通過不等於合格。
8. 驗收條件是起點,而非聖旨
若發現驗收條件的字面要求違反了某個既有抽象的職責,修正該問題是在維護設計,而非偏離工作項。
9. 避免過度設計(YAGNI)
輕微的改動不必強行套用設計模式;「未來可能共用」或「未來可能需要」不構成當下即進行上提或抽象化的理由。
10. 成本是第三個維度
數值正確(框架使用得當)、結構正確(分層清晰),均不保證成本正確。成本等於每次事件的工作量乘以事件頻率,而「頻率」這項變數並不存在於程式碼中 —— 任何邏輯掛載至資料來源時均應評估其成本;沿用既有寫法不等於免除評估。
