Codebase Convergence
讓儲存庫更容易理解與修改，無需重新設計。偏好證據、小型介面與局部修復，而非推測性抽象。
防護措施
- 在進行多步驟變更前，先說明範圍、假設、受保護內容與成功檢查點。
- 在判斷架構前，請先閱讀儲存庫說明文件、領域詞彙表與相關的架構決策記錄（ADR）。使用儲存庫的領域名稱。
- 僅觸碰與請求相關的檔案。保留使用者未相關的修改，僅移除因本次工作而變得多餘的匯入、程式碼或文件。
- 將明確受保護的領域文字、標題、資料定義與使用者指定的副本視為鎖定內容。保持原樣複製。若其狀態不明確，則將其納入決策封包，而非直接編輯。
- 未經明確核准，不得更改任何數值或其表示形式——包括設定、閾值、餘額、比率、限制或文件記錄值。
- 未經明確核准，不得私自更改業務規則、狀態轉換、互動行為、公開介面或視覺契約。除非修復是直接隱含的且保持行為不變，否則將其視為需要決策的事項。
- 維護每個事實的單一事實來源。不要建立僅僅重複其他文件的文件。
工作流程
1. 建立基準線
- 檢視工作目錄（worktree），僅辨識出被請求的區域。記錄不相關的修改；不要暫存或更改它們。
- 繪製相關的程式碼路徑、狀態/資料所有權、UI 流程、測試與 Markdown 檔案。在閱讀實作這些領域與決策的檔案之前，先閱讀目前定義這些領域與決策的文件。
- 記錄每個發現事項並附上證據：檔案、衝突的陳述或路徑、對使用者的影響，以及是否可以直接安全解決。
- 將發現事項分類：
- 直接收斂：重複、失效連結、互相矛盾的非鎖定散文，或具有行為保持修復的局部實作/UI 缺陷。
- 需要決策：任何數值、規則、行為、受保護內容、公開介面或模糊的資料來源。
- 架構候選：潛在的更深層模組，或其接縫（seam）尚未達成共識的變更。
2. 一次性提出重要決策
完成探索後再提問。發送一個包含所有未解決項目的決策封包；不要在多次對話中零散地提出問題。
對於每個數值項目，請包含其識別碼與檔案、當前數值、不一致的證據、影響，以及建議，或清楚表明未提出任何數值。在獲得使用者明確核准前，不要編輯、正規化、移動或移除受影響的數值表達式。
在同一封包中包含其他重要的不確定事項：鎖定內容狀態、行為選擇、所有權衝突與架構選擇。在等待核准期間，繼續獨立執行直接收斂。
3. 套用直接收斂
保持每次修改精確且可追溯至發現事項。
文件
- 賦予每個文件一個責任。遵守現有慣例；否則維持最小集合：入口概述、架構/系統圖表、領域或產品規則、決策記錄，以及目前工作/狀態。
- 合併重疊的產品需求文件（PRD）、計畫與工作記錄時，保留權威內容一次。將持久的理由移至專案的決策記錄，並保持操作狀態簡短。
- 在搬遷鎖定區塊時，保持原樣複製。如果合併會改變鎖定區塊或數值表達式，則將該區塊留待核准。
- 移除重複、失效的參照與衝突的非鎖定說明。在移動後更新連結，並避免建立重複規格的摘要文件。
程式碼與 UI
- 在編輯 UI 程式碼前，追蹤使用者操作從狀態所有權到最終渲染結果的完整路徑。
- 修正具體不一致：重複的呈現狀態、不匹配的事件/資料名稱、無效的條件流程、本次變更產生的無效程式碼，或阻礙局部修復的元件責任。
- 保持版面配置、互動、無障礙性與響應式行為穩定，除非使用者核准產品或視覺變更。
- 偏好一個清晰的狀態轉換擁有者與一個標準的資料表示形式。不要在未經證實的需求下引入抽象化、設定或錯誤處理。
4. 分開評估架構候選
一致地使用這些術語：
- 模組：一個具有介面與實作的單元。
- 介面：呼叫方必須知道的所有內容，包括不變量與錯誤模式。
- 接縫：可以在不編輯呼叫方的情況下改變行為的位置。
- 深度：透過小型介面提供的實質行為所帶來的槓桿效益；局部性：相關的知識與變更保持在一起。
應用刪除測試：如果刪除一個模組僅是將其複雜性移轉給呼叫方，則該模組有其存在的價值；如果複雜性隨之消失，則該模組很可能太過淺薄。不要為單一轉接器（adapter）建立接縫。
對於會更改介面、行為或所有權的候選方案，不要立即實作。僅在視覺比較有幫助時，在作業系統臨時目錄中建立一個簡潔的自包含 HTML 報告。報告內容應包含檔案、證據、變更前/後圖表、預期的局部性與槓桿效益、任何與 ADR 的衝突，以及建議強度。在設計介面之前，請使用者選擇一個候選方案。
5. 驗證與交接
- 檢查最終差異（diff）的範圍、鎖定內容的保留、重複的事實來源，以及非預期的數值或行為變更。
- 執行相關的現有格式化工具、lint、型別檢查、測試、建置與 UI 驗證。不要僅為此任務新增工具或廣泛的測試套件。區分既有失敗與引入的失敗。
- 在合併後確認 Markdown 連結與標題，並驗證每個修改過的陳述與其規範來源一致。
- 以簡潔的方式回報直接變更、未解決的決策項目、驗證結果與風險。每個變更行都必須能追溯到所要求的收斂工作。