Skip to content

工作紀律

與 blueprint 的關係:本頁就是預設藍圖的 playbook 欄位 —— 工具管不到的判斷規則。init 會將它們轉譯進專案的手冊與 Agent 守則,讓它們在每次改動時都在場。

共四個主題。

資料完整性與後端邊界

  • 不得使用假資料後備。 「後端欄位缺漏時以假資料頂替」(payload.field || fixture.field)的寫法是缺陷而非保護網:它掩蓋了資料完整性的問題。正式環境應如實呈現空白、錯誤或載入中的狀態。
  • 刻意保留的防護應表述為「防範後端結構漂移」,而非「支援某欄位缺漏的資料」。移除防護的前提:無漂移疑慮,且測試能證明呼叫點為零。
  • 本質屬於後端的問題,不主動提出前端繞路方案。 當問題根源在後端、且我方立場已公開表明時,提出「前端可暫時處理」等於為對方提供將工作推回前端的臺階。
  • Service 層保留後端的多語系資料結構。 於 service 層即解析為單一字串,會遺失其他語系變體,並將呈現邏輯混入 service —— 應對外提供完整結構(如 { zh_cn, en }),由畫面層解析。

執行期負載紀律

資料進入系統後的下一個問題不是「正確與否」,而是「進入的頻率有多快」—— 這是程式碼檢查與結構規範均無法察覺的維度。本節隸屬於信念第十條。

  • 掛載處理常式前先評估成本。 掛載至 WebSocket、輪詢、捲動或輸入事件之前,應回答三個問題:每秒觸發幾次?每次攜帶多少資料?每次事件的處理成本是何種數量級?無法回答者不得合併。「與既有寫法一致」正是此類失誤的放大器 —— 頻率不存在於程式碼中。
  • 高頻更新採取就地、欄位層級的寫入。 保持容器與未變動節點的參照恆定;整體替換僅用於基線重建。單次事件後出現「參照改變、數值未變」的屬性邊界,即為病徵。寫入模式不得跨框架照搬 —— React 依賴不可變資料與記憶化,Vue 依賴屬性層級的追蹤。
  • 渲染診斷四步驟,無一步依靠猜測。 何者在渲染(效能分析器)→ 何者觸發渲染(渲染追蹤)→ 何者產生新參照(搜尋賦值點)→ 是否值得(對照事件資料量)。
  • 效能主張必須可驗收。 「減少重新渲染」是形容詞;「單一事件的重新渲染不超過 N 個元件」才是驗收條件。以渲染計數或參照穩定性測試予以固定 —— 未經測試固定的效能主張,形同不存在。

死碼與抽象紀律

  • 抽象必須在同一個 Pull Request 內接上至少一個正式環境的使用者 —— 僅有自身測試作為呼叫者的抽象,是偽裝成架構工作的死碼。
  • 移除某段程式碼唯一的呼叫點時,應於同一個 Pull Request 將因此不可達的程式碼一併刪除。
  • 停用但須保留的程式碼,以 @deprecated 標註並指向狀態文件 —— 標註停用的實體本身,而非其測試。
  • 將反模式搬移至相鄰檔案並加上檢查豁免註解,不構成「修復」;逐行豁免亦不構成遷移。

重構與協作

  • 保護網先行的三階段流程:補齊邊界測試 → 拆分或修改 → 整理測試。每階段一個提交,審查範圍互不重疊。
  • 自原始碼抽取,不憑記憶重寫 —— 抽取完成後與版本歷史比對;「測試通過」不是抽取正確的唯一證明。
  • 抽取前遞迴掃描依賴 —— 涵蓋所有識別字,不僅限於響應式參照。
  • 保護網測試不得鎖定重構本身預定修改的介面。
  • 架構修正應表述為「維護設計」,而非「偏離工作項」—— 先陳述受維護的原則,再說明按字面執行工作項為何違反該原則。
  • 不重啟已定案的設計討論;確有疑慮時一次陳述完整、附上理由,不以選項清單的形式拋回。
  • 「使用者可以繞過」不構成擱置問題的理由 —— 判斷標準在於影響範圍與獨立影響程度。