用 Claude Code 升級套件：查相容性、分批改、驗證行為

先決定升去邊個版本

接手舊專案，見到一大堆警告，唔代表應該立即執行全套更新。先確認目前鎖定版本、執行環境、支援期限同安全問題，再揀一個有明確理由嘅目標。

例如舊文章經常用 Node 18 升 20 做示範，但唔應該照住歷史例子當成今日嘅升級目標。應查Node.js 官方版本狀態，再核對框架、建置工具同部署平台支援。

1. 升級前留低基準

先喺現有版本執行專案已有嘅型別檢查、測試同建置，記低本來已經失敗嘅項目。保存目前改動，喺獨立分支或者 worktree 工作。

目前版本：[填寫]。目標版本：[填寫]。

讀取鎖定檔、套件設定、執行環境同官方升級指南，列出實際受影響檔案。每項附官方來源，分成必須修改、需要驗證同可選改善。

檢查同版本有依賴關係嘅套件。先提供計劃，唔安裝、唔修改部署設定。查唔到資料就標明，唔好靠記憶補齊。

新增寫法唔等於舊寫法即時失效。例如框架提供新 API，未必要求你升級時一併重構所有舊用法。將必要遷移同順手改善分開，差異先容易審閱。

2. 一組相容依賴一齊處理

一次升一個套件係好起點，但有啲套件必須成組升，例如 React 同 React DOM，或者框架同指定 peer dependencies。由相容性要求決定批次，唔好硬拆到無法安裝。

沿用專案嘅套件管理器同鎖定檔。唔好為咗消除警告直接刪其他鎖定檔，亦唔好用忽略 peer dependency 衝突嘅參數掩蓋問題。

安裝後先讀鎖定檔差異：改動係咪只涵蓋預期範圍？有冇新增安裝腳本、間接依賴大幅更替，或者執行版本要求改咗？

3. 按一種問題逐批修正

以下係升級前後嘅檢查結果：[填寫或指定記錄檔]。

先分開原有錯誤同今次新增錯誤。按同一種根本原因分組，解釋每組對應邊條升級要求，再提出最小差異。

唔好用 any、停用規則或者刪測試令檢查變綠。官方有 codemod 時，先解釋適用範圍，執行後亦要覆檢結果。

每批完成後重跑受影響檢查，保留進度清單。單靠搜尋舊 API 字串唔夠：重新匯出、封裝函數、產生程式同第三方套件內部用法都可能漏。

4. 驗證用戶行為，同埋型別睇唔到嘅變化

建置通過之後，按專案重要性揀流程：首頁、導覽、資料載入、表單錯誤同成功狀態。涉及伺服器渲染時，要用正式建置模式試，唔只開開發伺服器。

另外逐項檢查可能無型別錯誤嘅行為：快取、空值、日期、序列化、重試同預設值。用同一組測試資料比對升級前後結果，唔好將「頁面開到」當成冇退步。

資料庫驅動升級要另外測交易、讀寫同資料形狀；只做唯讀測試不足以證明寫入正常。所有測試先喺隔離環境做，唔好順手套用 schema 改動。

交付時保留乜

留低目標版本、官方來源、相容套件、實際修改、已跑檢查同未覆蓋行為。復原安排亦要包括原有依賴同執行環境；如果新版本已經改咗外部資料，單單降返套件未必足夠。

Claude 可以幫你整理遷移工作，但唔應承諾一個鐘完成、固定觀察一星期就安全，或者測試綠燈就一定冇退步。範圍清楚、每一步有證據，先容易交畀下一位同事審閱。