principle-build-the-lever | 把工作做成可重跑工具

本頁以 pstack-claude 0.9.126 為基準。原文標示 user-invocable: false，通常由 poteto-mode 按需讀取。可以用自然語言要求代理套用這個原則，但它不是獨立命令。

定位與適用情境

非瑣碎工作應留下能執行或證明工作的工具，而不只留下「已人工確認」的結論。槓桿可以是程式碼轉換工具（Codemod）、產生器、分析腳本或可重跑檢查。即使只做一次，若沒有工具就很難核對，也值得建立。

例如要把一批教材的舊分類欄位轉成新格式，並證明每篇仍屬於原本對應的分類。只比較總篇數不夠，因為兩篇互換分類時總數仍相同。工具必須驗證它宣稱涵蓋的資料關係。

準備

保留原始資料副本，列出可修改檔案及不得觸碰的目錄。
選一個代表性檔案作為手動範本，寫明欄位轉換規則。
定義逐篇分類、總數與必要輸入等檢查項目。
確認專案已有的腳本執行環境，不為這個工具先建一套框架。

操作步驟

先手動完成一個單位。 在測試副本轉換範本，確認差異正是預期結果。這一步用來學習規則，不是直接手工完成全部資料。
建立最小工具並與範本對照。 讓腳本處理同一份原始輸入，將結果與手動版逐項比對。工具應有明確輸入、輸出與錯誤回報，不能靠人工記憶補步驟。
確認可安全重跑。 再執行一次不應重複新增欄位或改壞已轉換資料。先在測試副本觀察差異，確定邊界符合允許範圍。
用已知錯誤挑戰比對器。 分別改壞總數、交換兩篇分類但保留總數，再移除必要輸入。每項比較主張都要有對應反例。工具須報告不一致或無法判定，不能把缺資料視為相符。
才處理其餘單位並交付工具。 執行轉換與檢查，保留輸入條件、反例及重跑方式。若腳本已能一次處理所有檔案，就不要改派多人手工套用。

可直接使用的提示詞

套用 principle-build-the-lever。
任務是在核准的教材副本中轉換分類欄位，並證明每篇分類對應沒有改變。
先手動完成一個代表性檔案，再建立最小腳本，對照手動結果。
確認第二次執行不會產生額外變更。
比對工具需分別偵測總數改錯、分類互換但總數相同、必要輸入缺失。
缺少必要輸入時回報無法判定，不可回報相符。
交付工具檔案、反例、結果與重跑方式，不建立框架，不提交或推送。

預期結果與驗收

交付物應包含真正的工具檔案，而不只是一段說明「可自動化」的文字。維護者能從原始測試輸入重跑轉換，取得與範本一致的結果，也能觀察到每個故意放入的錯誤被攔下。

驗收還要檢查重跑後是否沒有額外差異、是否只碰到核准檔案，以及缺必要輸入時是否明確拒絕或回報無法判定。單一綠燈不能證明工具比較了每個應比較的面向。

常見誤用是為小修改打造大型通用框架，或把非確定性的人工判讀包成一個永遠輸出成功的腳本。另一種是聲稱已套用原則，卻沒有留下任何工具檔案。

限制與權限

幾個一眼可確認的瑣碎修改可以不建立工具。門檻是工作是否瑣碎，不是是否重複。工具也不能自動證明超出它檢查範圍的語意。

上游另提到多人工作可共用一份規則與驗證契約，並把契約放在寫手不可修改的位置。若要分派代理，這是要求而不是可選建議：提供所有代理共同讀取的配方、驗證契約與禁止修改範圍，契約放在代理寫入範圍之外。本原則不要求每項工作都使用子代理，契約也不能取代寫入隔離。若工具要跨工作階段保留，應納入專案交付；實際提交仍須取得授權。

本原則偏向眼前工作的產能與可檢查性。若目的是防止同一教訓反覆出現，應另看結構化規則的原則。

延伸閱讀與來源

教材分類轉換是本頁示例。手動範本、可重跑工具與已知錯誤控制皆依據上游原文。