決策筆記
清楚區分使用者拒絕、失敗的嘗試、比較後未選擇的方案、延期項目以及範圍外項目。不要將它們都視為永久不可行。
筆記非用於未解決的提案、完整需求、實作步驟、任務進度或故障排除紀錄。將提案與實作計畫保留在設計與計畫文件中；在所屬子系統文件中維護當前行為，並與原始碼比對驗證。在筆記中維護長期理由；在其他位置摘要並連結至此。
1. 決策與變更前先搜尋
在開始以下工作前，查閱適用的專案層級限制、相關子系統文件及相關筆記：
- 提出具體解決方案、確定行為或做出關鍵設計取捨。
- 變更相關實作或行為測試；對於跨子系統工作，應涵蓋相關介面與共享限制。
- 建立或變更決策記錄；首先搜尋相同主題的既有結論。
當使用者詢問歷史、發現決策指引或出現衝突時，直接閱讀相關記錄。純粹的拼寫、格式與狀態更新，若不涉及已確立的限制，則無需再次搜尋。
按以下順序定位與評估紀錄：
- 使用專案的Agent進入點尋找實際的筆記位置及適用的全域限制。使用子系統文件定位當前職責、合約、原始碼、測試及相關筆記。一個子系統可能橫跨多個套件或儲存庫，而一則筆記可能關聯多個子系統。
- 遵循連結，然後根據需要按問題、機制、解決方案名稱及限制進行搜尋。缺乏連結、對應的原始碼或匹配的名稱，並不能證明沒有相關歷史。如果不存在子系統頁面，則根據可用資料與任務主題定位相關上下文；不要預先建立空文件。
- 從標題、
Status、Scope及結論開始；必要時閱讀理由、替代方案與證據。優先參考當前有效的紀錄，然後根據相關性追溯歷史。當重新考慮舊方案或當前指引不足時，可直接搜尋歸檔紀錄。根據所涉及的範圍追溯取代關係；不要任意沿著鏈條追溯到最後。 - 確認紀錄的適用性與當前事實。如果目錄確實不存在，則繼續進行；僅在首次需要紀錄時才建立它。讀取失敗或搜尋無結果並不代表沒有歷史。
在同一個任務中，重複使用已驗證且仍適用的查詢結果。當範圍、關鍵前提或相關紀錄變更，或出現衝突時，重新檢查受影響的部分。不要僅僅因為輪次或技能改變就重新掃描所有內容。
僅在舊方案的前提條件已明確改變時，才主動再次提出該方案，並說明為何之前未被選中、哪些條件發生了變化以及影響為何。如果使用者明確變更了先前的決定，則遵循新的指示，無需再次請求批准。一般的實作授權不會自動取消既有的拒絕或範圍限制。
2. 決定是否建立紀錄
新的紀錄應滿足以下所有條件：
- 結論已確定。 它已被採用、拒絕、延期或限定範圍，或者存在失敗的結果及值得長期保留的條件。未解決的提案及待驗證的假設應屬於設計文件與計畫。
- 具有持久價值。 若無此理由，未來的Agent可能再次提出舊方案、重複有意義的失敗嘗試，或意外變更重要的限制。僅複述當前行為不符此門檻。
- 需要獨立的紀錄。 已搜尋過相關歷史，且無法透過更新事實、添加證據或釐清範圍來捕獲資訊。真正的決策變更需要根據取代規則建立新的紀錄。不要按日期、交付次數或替代方案的數量機械地建立紀錄。
典型主題包括：非顯而易見的子系統邊界、介面或持久性與相容性選擇；重要的選擇及未選擇替代方案的原因；刻意避免快取或自動重試的理由；可能被再次提出的重大拒絕或延期；以及有證據支持的長期失敗結論或跨任務政策。
通常，不要為格式化、機械式重新命名、從程式碼與測試即可理解的普通實作或修正、例行性依賴升級、一般故障排除嘗試、日誌、TODO 或進度建立筆記。大小不是標準。若現有筆記因工作而變得不準確，則維護它；若工作產生了符合門檻的新決策，則記錄之。
如果沒有明確的長期價值需要保留，不要為了填模板而建立紀錄。如果使用者明確要求保留某個重要決策，則重複使用或建立適當的來源；不要無聲地丟棄它。
3. 及時記錄真正的結論
一旦明確，立即記錄重要的結論；不要等到完成、會話結束或提交批准。決策可能來自使用者，或來自Agent在授權範圍內所做的選擇。記錄並不增加批准步驟，正在等待使用者決定的取捨也不能透過撰寫筆記來解決。
在撰寫之前，請閱讀格式與範例。預設位置是目標專案中的 .agents/notes/YYYY-MM-DD-topic.md；優先使用現有的專案位置。每個檔案保持一個決策主題及穩定的路徑。不要按狀態或子系統將筆記組織到目錄中。
- 保留標題、
Status及Scope。主體圍繞結論、理由及取捨展開；按需添加其他章節。除非專案有一致的語言，否則主體文字預設為英文。不要發明替代方案、要求固定數量或強制標記正面/負面後果。 - 說明每個結論的範圍與條件。不要將已採用但尚未實作的目標描述為當前實作、遷移或部署事實。設計與計畫文件擁有實作進度。
- 如果缺少理由，則說明其未被提供或記錄。對於失敗，保留其條件、結果及必要的證據或證據缺口；不要推斷為永久不可行。不要僅依賴後續會話無法存取的交談或暫存輸出。
4. 更新、取代與整理
| 狀態 | 意義 |
|---|---|
active | 已明確採用且在其聲明範圍內仍然適用；有效的拒絕與延期也使用此狀態 |
superseded | 整個範圍已被一個或多個新決策取代 |
retired | 無任何內容仍有效，且無新決策完全接管此範圍 |
狀態不表示實作進度或候選解決方案的處理狀態。如果事實、名稱、路徑或證據發生變化但決策不變，則更新現有紀錄。當核心選擇或限制發生明顯變更時，建立新的紀錄。當證據失效時重新評估；不要自動變更決策。
在變更狀態、取代決策、處理部分取代或恢復舊方案之前，請閱讀狀態與取代。按範圍交叉連結新舊紀錄；在部分取代後保留剩餘的限制。如果舊方案被再次採用，請建立新紀錄，而不是抹去中間的決策。
在歸檔、合併或刪除之前，請閱讀保留與整理。預設保留紀錄。邏輯歸檔不移動路徑；合併不得抹去真正的決策變更；刪除前需遷移唯一資訊並更新參考。僅整理受當前任務影響的紀錄；完整的清理必須在範圍之內。
5. 交付前檢查
檢查與此工作相關的紀錄及相關範圍。即使沒有建立新筆記，也要檢查變更是否導致現有筆記不準確。
- 遺漏與重複： 重要的結論與長期理由是否已保存？它們是否僅存在於對話中？現有紀錄是否已經足夠？
- 真實性與證據： 不要將建議描述為決策、將目標描述為當前狀態、將失敗描述為永久拒絕、將未選擇的方案描述為禁止、或將延期描述為實作承諾。準確陳述未知、未提供及未驗證的資訊。
- 狀態與範圍： 範圍與條件是否準確？部分取代是否保留了剩餘義務？是否存在針對相同範圍與條件的衝突性有效結論？歸檔是否隱藏了當前的限制？
- 文件所有權： 更新受影響的子系統文件、設計、計畫與筆記；每個來源擁有其資訊，其他位置連結至該來源。
- 連結與取代鏈： 必要的來源是否可以定位？結論是否可以按範圍追溯，而無自引用連結、損壞連結或循環？整理是否保留了獨特的理由、證據及有意義的歷史參考？
- 驗證： 執行專案中已可用的相關檢查並審查其結果。如果沒有配置，則手動檢查。不要自動添加依賴項、腳本、CI 或格式遷移。修正發現的實際問題；不要捏造內容。當相關內容未變更時，重複使用成功的結果。
通過格式檢查並不證明理由正確、檢索完整或實作遵循決策。如果當前事實與紀錄衝突，請區分過渡安排、過時文件、不完整實作及實際衝突。修正已驗證的錯誤。如果關鍵判斷仍不清楚，請解釋衝突並請求決策；不要覆蓋新的使用者指示或聲稱完成。繼續進行不依賴答案的工作。
當新增、大幅更新、取代或整理筆記時，簡要說明變更內容、原因及任何差距，並附上連結。當沒有相關內容變更時，不要發出固定的「未新增筆記」訊息。
將程式碼、相關文件及筆記一起保留作為一個待交付成果。完成本輪的變更與檢查並展示結果後，詢問工作是否完成以及是否可以建立本地提交。如果使用者提供更多回饋，則繼續編輯。儲存或驗證筆記並不授權提交、推送或發布，也不要求提前提交筆記。