m1nga/iteration-close

iteration-close — 提煉、捨棄、驗證接管、排練引導、播種下一輪

一個持續迭代的產品會累積兩項隱性債務，而這個技能會在每次迭代邊際同時償還這兩項債務——安全（不遺失任何東西）但無情（不留任何死的東西）：

• 廢棄檔案殘留並腐化為「雙重真相」——一個已棄用的樹狀結構可能擺上好幾週；一本操作手冊可能在元件上線後很久仍聲稱它「尚未建置」。
• 只存在於聊天視窗中的知識會隨著視窗關閉而消失——整個能運作的管線可能因此葬送在暫存區中；辛苦得來的決策會隨著對話結束而消失。保留教訓，而不是成品。

這是通用的：它可以透過讀取儲存庫自身的慣例來運作於任何儲存庫上；若缺乏慣例，它會建立最小必要的東西，而非假設或報錯。「一個新的視窗或機器可以繼續」在經過測試之前只是個「希望」；保持最新（pull）總是安全的，但發布（push）是刻意的選擇。請以使用者正在使用的語言回覆。

兩種執行方式

• 完整閉環（預設）：所有五個階段，按順序執行。當一個迭代/片段完成且使用者希望完整結束時使用。
• 僅清理（獨立清除）：當使用者僅要求清除舊/死/過時檔案時，僅執行第二階段——不要強迫他們執行完整的五幕閉環。前置條件仍然適用：執行步驟0（定向）、失敗關閉的拒絕檢查，以及範圍限定在刪除清單上的第一階段抽樣檢查——任何其教訓或決策僅存在於聊天中的項目，會先被提煉成已追蹤的檔案，否則排除在清單之外。所有第二階段的規則（包括明確許可閘門和隔離規則）不變地適用。

步驟 0 — 定向到「這個」儲存庫（探索，否則規劃建立）

讀取存在的任何入門文件——CLAUDE.md / AGENTS.md / README / 一個 docs/ 索引——並探索六件事。使用你找到的內容；若某項缺失，則將其記錄為本次閉環將填補的缺口（每個階段下方會說明如何填補），絕對不要編造一個不存在的路徑。

1. 教訓/決策記錄——這個儲存庫在哪裡存放決策？（CHANGELOG、docs/adr/、DECISIONS.md，或一個儲存庫專屬的註冊表。）如果沒有，第一階段會建立一個單一的 DECISIONS.md。
2. 確認上傳指令——一個刻意的推送步驟（bin/sync、make deploy、一個有文件的 git push 規範）？如果是，那就是上傳通道；永遠不要繞過它。如果沒有，第三階段a會使用普通的 git push，但會先顯示差異統計 + 確認。
3. 引導指令——一個全新的複製如何活起來？（bin/bootstrap、bin/sync-setup、install.sh、make setup、一個套件管理器的安裝指令。）如果沒有，第四階段會建立一個。
4. 測試指令——來自CI配置、package.json 腳本、一個Makefile，或語言預設值（pytest / go test / cargo test / npm test）。如果探索不到任何測試指令，代表該儲存庫還沒有可執行的測試套件：將此視為一個明確的狀態——絕對不要將其解讀為「綠色」，也絕對不要對一個正當沒有測試套件的儲存庫發出拒絕。
5. 基礎/閘門技能——一個產品基礎化或建置前閘門技能？如果是，它的「建置後」檢查清單就是你的閉環前閘門。（產品特定的閘門存在於產品儲存庫內部；這個技能保持通用，並會委託給它們。）
6. 宣告的資料/復原/隔離目錄——入門文件中命名為存放真實資料、復原材料或隔離檔案的目錄。這些目錄在所有「不得存在形似封存的目錄」規則中皆為豁免，且永遠不得出現在刪除清單上。

拒絕執行（失敗關閉）

不要在迭代中途閉環——你會連皮帶肉一起失去。在以下情況下拒絕（兩種執行模式皆適用）：目錄不是一個git儲存庫（停下來並說明——執行 git init 是使用者的決定）；測試套件存在而且真的在失敗（不存在的套件不等於失敗——見步驟0.4）；如果儲存庫有敵對閘門且該閘門處於待處理或需要修改狀態；或者另一個代理/工作線在你會觸及的路徑中有未提交的中途工作。說明阻擋的原因並停止。

在完整閉環中，按順序執行各個階段。每個階段都有一個退出測試；永遠不要越過失敗的退出測試進入下一個階段。

第一階段 — 提煉（保存閘門：在教訓被存入儲存庫之前，沒有任何東西會消失）

1. 掃描本次迭代中產生於聊天的決策，並將其存入儲存庫的決策記錄（步驟0.1），每個決策附上其狀態和來源。如果儲存庫目前沒有任何地方存放決策，建立記錄是此階段的一部分——在儲存庫根目錄建立一個單一的 DECISIONS.md 就足夠了。 只存在於聊天視窗中的決策等於不存在；不要讓已提煉的決策沒有可追蹤的歸宿。
2. 本次迭代中發現的新不變量/規則 → 儲存庫的合約檔案，如果沒有的話則放入決策記錄——理想情況下每個不變量都作為一個測試。如果兩者都不存在，建立決策記錄並將它們放入其中。刪除成品，保留不變量。
3. 僅限對話的能力檢查：本次迭代是否依賴於任何只存在於提示詞、暫存區或某人記憶中的東西？將其提升到儲存庫中（程式碼/技能/文件），或者記錄其刻意被排除的原因。明確地逐一命名——這就是管線死亡的所在。
4. 如果結構發生了變化，更新——或者，如果沒有任何結構文件且現在結構變得複雜——建立一個簡短的架構/系統備註，使其仍然能描述現實。如果儲存庫有狀態看板（例如進度文件），則使其保持最新。

退出測試：在儲存庫內部搜尋本次迭代的關鍵決策和不變量——每一個都應能在已追蹤的檔案中找到。任何只能在聊天中找到的東西 = 第一階段未完成。

第二階段 — 捨棄（無情刪除；git 歷史是唯一的封存）

1. 建立一個刪除清單，每行附上證據：路徑 | 為何已死 | 什麼取代了它。涵蓋：被取代的模組/規格、空的目錄、開發殘留物（暫存檔案、mktemp 風格的垃圾、真實形狀的儲存中的測試資料）、已完成的計劃/TODO文件，以及過時的文件——執行文件與程式碼的矛盾檢查；一份斷言與程式碼矛盾的文件比沒有更糟。將每一行標記為已追蹤或未追蹤（git ls-files --error-unmatch <path>），因為兩者有不同命運（規則3和4）。
2. 將完整的清單呈現給使用者，並在刪除任何東西之前等待明確的許可。 部分批准是可以的——只對已批准的行採取行動。代理絕不能自行按下不可逆的按鈕；「使用者要求清理」授權的是建立清單，而不是執行它。
3. 已追蹤的檔案：僅使用 git rm。不要 _archive/ 目錄，不要 .bak，不要 old-/legacy- 重新命名，不要被註解掉的屍體。復原方式 = git歷史，一個 git revert 的距離——那就是封存；在刪除前建立一個檢查點提交使其萬無一失。
4. 未追蹤或 .gitignore 中的檔案：絕對不要直接 rm——git 歷史無法復原從未被提交的東西。這是資料安全的底線。 改為將它們移動到儲存庫宣告的隔離目錄（步驟0.6）。如果沒有宣告的隔離目錄，現在建立一個：在儲存庫根目錄建立 .iteration-quarantine/，加入 .gitignore，在入門文件中用一行宣告（「待刪除未追蹤檔案的隔離區——由使用者手動清空」）。清空隔離區是使用者的行為——在未來的閉環中提供此選項，並需要明確的許可；永遠不要悄悄進行。
5. 永遠不要將產品的真實資料當作開發殘留物捨棄。 使用者/客戶狀態、已儲存的 session、使用者內容的真實封存可能看起來像垃圾，但卻是產品的靈魂。當一個目錄可能是資料時，將其視為資料並保留；在任何 git rm 之前先驗證。
6. 按主題分組提交刪除；每條訊息說明原因 + 取代它的內容。
7. 刪除後檢查（所有適用的都必須通過）：如果儲存庫有測試套件，它必須是綠色的；對每個已刪除模組/符號的懸空引用搜尋結果必須為空（對已刪除檔案的匯入會在啟動時崩潰——這是真實的傷痕）；入門文件和技能文件不得引用任何已刪除的路徑。

退出測試：git status 乾淨，不存在形似封存的目錄——除了入門文件宣告為資料、復原或隔離的目錄（步驟0.6）——懸空引用搜尋為空，且如果存在測試套件則為綠色。

第三階段 — 兩個就緒通道（不同需求；分別驗證）

上傳和可持續運行不是同一個問題。將它們混為一談就是一個儲存庫被「推送到雲端」但其真實狀態仍然存在於聊天記錄中的原因。分別驗證每個通道。

3a. 確認雲端上傳（傳輸問題）

1. 僅對已追蹤的檔案執行密碼掃描（sk-ant / ghp_ / gho_ / github_pat / AKIA / xox[baprs] / consumer_secret / access_token / Bearer / BEGIN PRIVATE KEY / .env 形狀）。任何命中 → 停止、清理、重新掃描。
2. 檢查 git remote。如果沒有遠端儲存庫，上傳需要使用者提供一個——新增遠端是配置變更，因此需與使用者確認，或記錄「尚無遠端——發布延期」並跳到3b，而不是在一個空的git指令上報錯。
3. 有遠端儲存庫時：顯示 git log @{u}..HEAD --oneline + 差異統計（當尚無上游時回退到「所有本地提交」）——這些是將要離開此機器的確切內容。
4. 在使用者確認後，透過儲存庫的確認上傳指令（步驟0.2）進行上傳；如果儲存庫沒有，則在差異統計和一個「是」之後使用 git push。絕不要自動推送。

3b. 無背景知識接管（知識完整性問題）——冷啟動探測

1. 讓一個真正無背景知識的讀者接觸該儲存庫——在Claude Code中：生成一個全新的子代理（Task工具）；在Codex中：執行一個全新的 codex exec 或一個沒有先前上下文的新session；在任何裸的框架上：開啟一個新session並僅貼上儲存庫路徑加上問題，絕對不要貼上本次對話。只給它儲存庫路徑和：「從入門文件冷啟動閱讀此儲存庫。然後回答：(1) 這個產品用一句話怎麼描述；(2) 工作進展到哪裡了（已完成 / 下一步是什麼）；(3) 你接下來會做什麼以及為什麼；(4) 說出三件你在這裡絕對不能做的事。」
2. 根據儲存庫的權威文件評分其答案。如果儲存庫根本沒有入門/權威文件，建立一個最小版本（用一句話描述產品、當前狀態已完成/下一步、三個絕對不能做的事）是本次閉環的一部分——這是探測所評分的成品。不要對空執行探測。
3. 每一個錯誤或缺失的答案都是一個「接管文件錯誤」，不是探測的錯。修正（或建立）文件，用一個新的無背景知識讀者重新執行。循環直到一個冷啟動讀者獲得4/4分，最多3輪——如果3輪後仍然失敗，列出剩餘差距並將決策交給使用者。

退出測試：探測通過4/4。只有到那時，「任何新視窗/機器都可以繼續」才是一個經過測試的事實。

第四階段 — 一鍵引導（經過排練，而非假設）

1. 確保儲存庫的引導指令（步驟0.3）存在且是最新的——冪等，安全地重新執行：驗證工具鏈版本；連接同步/配置；安裝依賴；如果存在則執行測試套件；列印當前狀態 + 任何缺少的本地秘密的名稱（永遠不要列印值，例如「config.local.json 不存在——僅在即時發布時需要」）；任何失敗則以非零退出碼退出並附上一行原因。如果尚無引導指令，本次迭代就是建立的時機。
2. 排練它：將儲存庫複製到一個暫存目錄（從原始URL，或者當尚無遠端儲存庫時從本地儲存庫路徑）並在那裡執行引導指令。它必須以綠色結束，且零手動步驟。排練完成後刪除暫存複製。
3. 「新機器故事」必須是一行且在這次排練後為真： git clone <原始URL> <目錄> && cd <目錄> && <引導指令>。如果尚無遠端儲存庫，請注意這一行在使用者設定之前還不是真的——不要讓它看起來像是可以運作就發布。

退出測試：排練複製的引導指令以綠色結束，未經人手觸碰。

第五階段 — 關閉 + 播種（連續性）

1. 標記迭代：git tag iter-<N>-<slug>（帶註解，單行摘要）。N = 1 + 現有 iter-* 標籤的數量（git tag --list "iter-*"）；第一次閉環是 iter-1。
2. 如果儲存庫有狀態看板/日誌，用一行更新：提煉了什麼、捨棄了多少檔案、探測4/4、引導已排練。
3. 將「下一次迭代種子」輸出到聊天：本次迭代浮現的未解決問題 + 一個可貼上的下一個片段的啟動提示（目標、驗收標準，以及如果儲存庫有的話，提醒在建置前執行其基礎閘門）。

主要迭代——當結構本身被取代時（同樣的規則，更大的風險）

結構性翻新——新的架構、新的模組樹，甚至「舊的做法是錯的」——仍然是同一個有機體的「一次迭代」，而不是重新開始。它保留其git歷史、其決策、其教訓；只有外殼是新的。重新開始會流血：每次一個專案在一個全新的儲存庫中重生時，有教訓價值的材料就會被遺留下來。所以：

• 在這個儲存庫中與舊結構並行生長新結構（strangler模式）：新樹先贏得測試和所有權；舊樹只有在沒有任何東西引用它時，才在第二階段死去。
• 開啟一個「新」儲存庫是昂貴的例外，而不是預設——它需要一個記錄的決策說明為何必須放棄這個歷史，並在任何檔案移動之前獲得批准。
• 同樣的五個階段；刪除清單只是更大，而冷啟動探測更重要——新結構的文件從未遇過陌生人。
• 如果產品名稱或進入命令改變，第四階段的單行故事在同一次迭代中更新。兩個活躍的名稱是一個雙重真相的錯誤。

護欄（不可協商）

• 階段順序是安全機制：永遠不要在提煉（第一階段）退出之前捨棄（第二階段）——在僅清理模式中，清單上的第一階段抽樣檢查就是那個閘門。
• 完整的刪除清單會顯示給使用者，沒有他們的明確許可，什麼都不會刪除。代理絕不能自行按下不可逆的按鈕。
• 未追蹤或 .gitignore 中的檔案會被隔離，永遠不會被 rm——git歷史無法復原它們。
• 刪除需要被取代的證據，而不是感覺。真的不確定？保留它「一個」迭代，並將疑慮記錄在決策記錄中。