Recovery Workflow Checklist：給真實 AI Coding 工作流程的復原順序

什麼時候該執行復原流程？

並不是每次 AI 產生程式碼出問題都需要啟動正式復原。只有當滿足以下任一項進入條件時，才應該執行完整的 Recovery Workflow Checklist：

• AI 助手連續 3 次以上無法提供有效修復，且生成內容出現重複、幻覺或上下文遺失。
• 專案程式碼變更後出現編譯/測試失敗，且失敗原因不屬於常見語法錯誤，而是涉及多個文件的狀態不一致。
• 你在同一個問題上反覆打轉，回退後又向前執行，但缺乏明確的回滾點記錄。

如果不滿足以上條件，可能只需要重試或手動修改一行程式碼。沒必要把恢復流程做成每次迭代的標配——這會消耗不必要的注意力，反而降低效率。

恢復的第一步：不要直接重試

當進入恢復狀態後，最常見的錯誤是立即讓 AI 重試或重新產生。這在很多情況下是無效的，因為問題根源通常不在最後一次生成，而在更早的狀態丟失。

正確的檢查順序應該是：

1. 確認目前程式碼狀態：開啟版本控制工具（如 Git）檢查最近的提交記錄。了解最後一次可工作的提交是哪一個，它與當前工作區之間的差異是否被記錄。
2. 檢查 AI 的上下文視窗：如果使用 Cursor 或 Claude Code，確認 AI 是否記住了專案結構和先前的對話歷史。很多時候，AI 的上下文已經偏移，導致它基於錯誤的假設產生程式碼。
3. 重新載入專案索引：許多 AI 編碼工具依賴專案索引來提供程式碼建議。如果索引過期，AI 可能看不到你剛剛修改的檔案。嘗試重新啟動工具或手動觸發索引重建。
4. 分段驗證變更：不要一次回退到上一個穩定版本，而是考慮將最近的變更拆分成幾個邏輯單元，逐一測試。這樣能更快定位到具體哪一步引入了問題。

權限與依賴：最容易被忽略的斷點

恢復流程中，權限和依賴問題遠比想像中常見。我遇到過這樣一個真實場景：團隊的 AI 編碼代理在執行自動化修復時，突然無法讀取某個配置文件，導致所有後續操作失敗。原因是該檔案在先前的復原過程中被錯誤地修改了權限。

權限檢查清單：

• 檔案系統權限：確認 AI 工具（如 Claude Code 的 CLI 進程）對專案目錄擁有讀取和寫入權限。特別是在 Docker 或 CI 環境中，權限容易遺失。
• API 令牌與金鑰：如果 AI 工具依賴外部 API（如 OpenAI、Anthropic），檢查 API 金鑰是否過期或配額是否已用完。有時恢復流程本身會消耗大量 token，導致限流。
• 環境變數：在復原過程中，某些環境變數可能會被重置或移除。檢查 .env 檔案或系統變數是否與您的預期一致。

依賴檢查清單：

• 套件管理器鎖定檔：AI 自動安裝的依賴可能使用了錯誤的版本。檢查 package-lock.json、requirements.txt 或 Cargo.lock 是否與專案需求相符。
• 外部服務連線：如果項目依賴資料庫、快取或訊息佇列，確認這些服務在復原過程中未受到影響。例如，回滾資料庫遷移後，應用程式碼可能無法與之相容。
• 工具版本：AI 編碼工具本身可能更新了版本，導致行為改變。檢查工具版本與專案中使用的 API 是否相容。

恢復後的驗證：不只測試通過

當復原流程執行完成後，許多人以「測試通過」作為結束標誌。但這遠遠不夠。恢復後的驗證需要更全面的檢查：

1. 功能回歸測試：運行完整的測試套件，包括單元測試、整合測試和端到端測試。如果測試覆蓋率不足，手動測試關鍵使用者流程。
2. 程式碼一致性檢查：使用 linter 和格式化工具確保復原後的程式碼符合專案規格。 AI 產生的程式碼有時會引入不一致的縮排或命名約定。
3. 上下文記錄：將本次復原的原因、步驟和結果記錄在專案文件或 wiki 中。這不僅是知識沉澱，也是未來快速復原的參考。如果下次遇到同樣問題，你可以直接呼叫這份 checklist 的前置條件。
4. 警報與監控檢查：如果項目有生產環境監控，確認恢復後沒有觸發新的警報。特別是效能指標－某些恢復操作可能引入了效能回歸。

一個真實失敗複盤

我自己的一個教訓：在使用 Cursor 進行大規模重構時，AI 提議一次重寫三個模組。我信任了它的上下文，沒有分段提交。結果重建一半時，AI 的上下文溢出，產生的程式碼開始引用不存在的函數。

當時我直接讓 AI 重新產生－這是錯誤的順序。我應該先回退到上次提交，然後逐模組重寫。最終我丟失了接近 4 個小時的工作進度，因為沒有任何 checkpoint。從那以後，我堅持每完成一個邏輯單元就提交一次，並在 AI 工作前後強制檢查上下文視窗狀態。

替代方案：當 Checklist 本身失敗時

Recovery Workflow Checklist 不是銀彈。在某些場景下，它可能無效：

• AI 工具本身存在 Bug：如果你使用的工具版本有已知問題，復原流程可能永遠無法成功。此時應考慮降級或切換工具。
• 專案結構極度複雜：大型 monorepo 中，依賴關係錯綜複雜，手動恢復可能成本過高。可以考慮使用專案級的備份還原工具（如 Git 自動備份、快照還原）。
• 團隊成員工作流程不一致：如果團隊中有人不遵循一致的工作流程，恢復操作可能會覆蓋他人的未提交變更。此時需要溝通和流程對齊。

如果 Checklist 仍然無法解決問題，最後的備選方案是：

1. 從版本控制中完整回退到最後一個穩定標籤。
2. 記錄失敗原因，並在下次迭代中修正工作流程。
3. 考慮更換 AI 編碼工具，或調整工具配置（如增加上下文視窗大小、啟用離線索引）。

下一步：從普通開發者到 Agent 工程師

掌握 Recovery Workflow 只是要成為高效率 AI 開發者的第一步。如果你想系統性地理解 AI 程式設計代理程式的上下文管理、權限設計和復原策略，可以進一步閱讀我們的原始付費文章和 AI 程式設計進階課程。這些內容將幫助你從「會用 AI 寫程式碼」升級到「設計自主修復的 Agent」。