principle-make-operations-idempotent | 讓重跑收斂到同一結果
本頁以 pstack-claude 0.9.126 為基準。原文設定 user-invocable: false，通常由 poteto-mode 按需讀取。以自然語言要求「套用 principle-make-operations-idempotent」，請代理檢查重複執行與中途崩潰的結果。
定位與適用情境
冪等性（Idempotency）在這裡指操作不論執行幾次、上次停在哪裡，都會收斂到正確終態。步驟應根據現在確實存在的狀態，而不是上次原本打算做的事。
本例要改進本機離線文件索引產生器。輸入是一組固定文件、現有索引與可能殘留的暫存檔。目標是重跑後得到同一份有效索引，而非每次附加一批重複項目。
準備
- 使用隔離的測試目錄，準備來源文件與預期索引內容。不要使用正式資料。
- 列出每個寫入點，包括暫存檔、完成標記與最終索引。
- 確認檔案系統的重新命名行為與工具可用的失敗注入方式。不先假設所有儲存環境都有相同保證。
操作步驟
- 定義目標與比較方式。 以固定輸入的索引內容作為終態，辨認現有產物是否已相符。不要以「上次已開始」或檔案建立順序判定完成。
- 讓每步只補差異。 讀取目前索引，內容相符就不再變更。需要更新時，先產生可驗證的暫存產物，驗證後再於支援的環境中重新命名替換。
- 設計殘留辨識。 為暫存檔及標記列出判定有效、未完成或過期的證據。對每個可能中斷點檢查這些證據仍成立，不只處理最常見的失敗位置。
- 驗證重跑與復原。 連續執行兩次，再於每個已列出的寫入邊界模擬中斷後重跑。比較最終內容，並確認未完成產物不會被當成有效索引。
可直接使用的提示詞
套用 principle-make-operations-idempotent。請檢查離線文件索引產生器的每個狀態變更，使用隔離測試目錄與固定文件集。
先列出目標內容、寫入邊界、殘留檔案，以及下次執行如何辨識它們。設計成讀取現況、比較目標、只套用差異，而非重複附加紀錄。
提出連跑兩次及每個寫入邊界中斷後重跑的測試。說明檔案替換依賴哪些環境保證。本輪只交付方案與測試矩陣，不寫入或刪除任何檔案。預期結果與驗收
預期得到狀態調和（Reconciliation）方案與可重現的故障測試矩陣。
- 第一次成功後再執行，不增加重複索引項目，內容仍等於目標。
- 每個列出的中斷點都有重跑路徑，不需靠人工猜測上次進度。
- 每種殘留狀態都有可驗證的辨識規則，不只寫「失敗時清理」。
- 報告區分已測案例與未覆蓋環境，不把有限測試當作所有崩潰情況的證明。
限制與權限
常見誤用是捕捉所有錯誤後無限重試，或只加「完成」旗標卻不處理旗標寫入前後的崩潰。重試本身不會讓操作冪等。
暫存後重新命名是原文提供的思路，不代表跨磁碟、遠端儲存或並行寫入都自動安全。本例不涵蓋多個寫入者的完整協調。冪等設計也不授權清除不明檔案或正式資料，清理仍要遵守確認規則。