維護文件
1. 明確責任與當前範疇
使用此技能來決定是否建立或重用記錄、組織內容、驗證描述、揭露缺口，以及維護來源關係、狀態和導航。這需要工程判斷：在解釋當前機制時應調查實際路徑；不要僅重新格式化對話，或透過填寫模板來製造虛假確定性。
- 執行當前任務的代理處理技術選擇、取捨、任務分解、實作、除錯與驗證；當輸出需要保留時，請使用這些共享規則。對子系統文件進行有針對性的調查和更新是有效任務，不需要先啟動單獨的設計流程。
- 使用
to-docs來建立可供人員審閱、編輯和日後參考的可讀設計交付物。人類可讀設計可以是完整來源；此技能從文件保存之時起即引導文件所有權與一致性。不要先要求工程記錄，或在不同技能之間建立循環呼叫。 - 使用
grilling來深入釐清當前主題；grill-me是其明確的進入點。從已建立的內容繼續，無需重新開啟決策或為每次迭代增加批准關卡。 - 使用
decision-notes來尋找、記錄、取代和組織長期決策。此技能引用其結論；它不會建立單獨的面試流程或決策生命週期。當其觸發條件適用時即搜尋，即使沒有直接連結。 - 視需要使用
handoff來準備或驗證跨工作階段或跨代理的交接。此技能繼續維護工程材料與狀態；不要僅因為執行任務的人員變更就建立完整的副本，也不要在不同技能之間建立循環呼叫。 - 一般的閱讀、即時提問，以及不影響現有材料的小型變更，不會獨立觸發完整的維護流程；但仍需閱讀任務所需的材料。僅限文件的請求不會擴大更改產品行為、執行無關檢查或提交程式碼的權限；現有工程任務授權仍然有效。
使用環境中實際可用的名稱。如果某個技能無法被調用，請改讀取專案的配置指引；不要聲稱已調用不可用的技能。協作不得導致循環載入或重複搜尋。
2. 定位來源並決定是否建立或重用記錄
從專案實際的代理進入點開始，定位限制條件、需求與驗收標準、相關子系統、變更記錄與註解；驗證當前工作的範疇。對於現有專案，優先使用現有位置與名稱；不需要求遷移。對於跨子系統的工作，需涵蓋相關介面與共享限制。
重複使用已為同一任務讀取且驗證過的脈絡，前提是這些脈絡仍然適用。當範疇、關鍵前提或來源變更，或出現衝突時，重新檢查受影響區域。不要僅僅因為輪次或技能變更就重新掃描整個儲存庫或重啟面試。
在選擇位置、名稱、檔案分割或導航時，請閱讀 組織與來源。
- 首先尋找仍然適用的現有文件，針對的是同一項變更；相似的題目不一定代表同一變更。要繼續現有工作，請定位其原始記錄並驗證當前狀態，而不是自動撰寫完整的交接文件。
- 當需要保留目標設計、遷移計劃、相依性，或需要調查與驗證的問題以供後續實作、驗收或跨工作階段繼續時，建立或更新記錄。這同樣適用於調查與方案比較期間。
- 在當前輪次內完成的小型、明確的變更，可以僅透過對話交付，同時仍需根據既定規則維護受影響的現有文件和註解。如果用戶明確要求保存某些內容，則記錄下來，並優先選擇適當的現有來源。
- 不要根據行數、檔案數、對話輪次或提交次數來機械地建立記錄。不要預先建立空白頁面或整個文件庫，也不要每次都詢問是否要撰寫文件。
3. 根據目的驗證與維護材料
| 當前工作 | 按需閱讀 | 資訊所有權 |
|---|---|---|
| 驗證人類可讀設計與工程材料之間的所有權與一致性 | 組織與來源 | 人類可讀設計保留目標、場景與行為的完整來源；工程材料參考並補充它們 |
| 描述當前子系統或修正文件與實作之間的差異 | 子系統文件 | 當前職責、機制、合約，以及對原始碼、測試和註解的導航 |
| 記錄變更目標、設計、任務與繼續脈絡 | 變更設計與計劃 | 當前目標、與現有狀態的差距、未解決問題、實作與驗證計劃 |
| 更新狀態；完成、暫停、取消、恢復或關閉記錄 | 狀態與結案 | 總體進度、任務結果、實際驗證以及剩餘工作的處理方式 |
將每個事實維護在一個位置；在其他位置總結並連結到它。docs/designs/<主題>.md 可以是完整的可讀設計來源。僅在需要時將工程細節、相依性、驗證和進度添加到 .agents/changes/；不要重複設計。不要將現有來源的概述變成完整副本，不要在索引中建立第二個狀態或進度記錄，也不要在其註解來源之外維護長期理由。
工程變更進入點、README、計劃和總體狀態規則僅適用於需要工程變更記錄的工作；它們不會強加於人類可讀設計。設計中已確定或未確定的內容並非工程進度。不要引入強制性的設計狀態機，也不要為每個設計建立一個配套的工程目錄。
區分已確認的結論、未解決的建議、假設和需要調查的事項，以及原始碼驗證、現有測試覆蓋率和實際運行時驗證。連結應說明其支援的機制、涵蓋的行為或決策主題。測試的存在並不意味著它已成功執行。採用某個目標並不意味著它已實現，也不會自動消除轉換或相容性義務。
當文件與實作不一致時，請檢查相關的原始碼、測試、需求、適用的註解和實作狀態。確定文件是否過時、實作是否偏離預期行為，或者轉換是否未完成。修正已驗證的文件錯誤；在現有授權範圍內處理實作錯誤。不要將缺陷描述為正常合約，也不要用舊文件推翻新的用戶指示。如果關鍵行為或取捨仍不清楚，請描述衝突並請用戶決定，同時繼續不依賴該決策的工作。
4. 保持材料與實質變更同步
- 當子系統職責、邊界、主要路徑、介面、狀態、失敗行為、相容性行為或必要導航發生變更時，請在驗證變更的同時更新相關文件，而不是等到專案完成。不要在內部重構後機械地改寫仍然準確的描述，但要修復失效的連結。
- 當目標、範疇、關鍵選擇或前提明確變更時，更新設計；繼續將未解決的內容標記為未解決。當任務結果、相依性、阻礙或後續步驟的變更影響執行或繼續時，更新計劃。在執行受影響的步驟之前同步重要的時程變更；不要記錄每個工具操作。
- 在現有授權範圍內自主處理調整。文件更新不會增加批准要求，也不能取代必要的用戶決策。請用戶決定超出授權範圍的行為、範疇或關鍵取捨變更；不要重新確認已解決的事項。
- 在交付、暫停或交接之前，驗證需要持續保留的相關材料能讓下一個代理識別當前狀態、與目標的差距、剩餘工作以及下一步。不要等到這些時刻才進行首次記錄。
只處理當前任務相關的範疇。將當前事實保留在子系統文件中，長期決策保留在 decision-notes 中，讓其他位置引用它們。
5. 檢查與交付
檢查本次任務商定的範疇；不要將其變成倉庫範圍的審計：
- 覆蓋率與所有權：保留需要持續存在的內容；重用適當的來源，避免重複的散文、空白佔位符或僅留在臨時對話中的繼續脈絡。
- 準確性：明確呈現當前狀態、目標、已確定與未決定的點以及證據；不要混淆階段進度、程式碼變更、成功驗證和所需的人工驗收。
- 狀態與繼續：如果存在工程變更記錄，則僅在其變更進入點維護其總體狀態，並根據實際進度標記任務。使相關的阻礙、差距、後續步驟和剩餘工作可被定位；在結案記錄中保留必要的結論與證據。
- 連結與一致性：保持相關需求與驗收標準、設計、計劃、子系統和註解準確連結；確保連結有效。重新組織材料或記錄不得遺失唯一資訊。
- 驗證範疇：根據任務和專案執行適用的現有檢查，並審查結果；如果沒有專用工具，則進行人工審查。不要為了完成文件而強加不相關的檢查、完整的測試套件或新的工具鏈。當內容未變更時，重用已驗證的結果，並準確描述未驗證或受限的區域。
完成當前文件任務意味著商定的資訊是準確的、來源是可定位的、未知數與驗證差距已被揭露，並且材料支援繼續。這並不證明設計已足夠、實作是正確的或功能已完成。請使用 狀態與結案 單獨驗證整體變更的完成情況。
對本輪的變更、檢查和必要的差距進行簡潔的說明，並提供實際檔案的連結；將需要持續維護的結果放入儲存庫。將相關的程式碼、文件和註解作為待交付物放在一起。保存文件並不授權提交、推送、PR 或發佈；請遵循專案現有的提交確認規則，不要因為文件已保存而過早提交。