用 Claude Code 接手舊專案：先畫地圖，再追一條真實流程

先了解點運作，唔急住重寫

接手幾年歷史嘅專案，文件過時、原作者離開，最難通常唔係讀某個函數，而係知道邊條路先係實際用緊。

Claude Code 可以幫你整理入口同關係，但唔應叫佢「睇晒成個 repo」之後就相信一份完整架構圖。分範圍閱讀，要求每個結論附檔案證據，會容易核對得多。

1. 先建立一張有範圍嘅地圖

我啱啱接手呢個專案。先唯讀檢查根目錄、套件與鎖定檔、建置設定、測試入口同現有文件。

列出語言、框架、主要資料夾、啟動指令同服務入口。每項附實際路徑，分開已確認、推測同未讀範圍。

唔安裝套件、唔啟動會連正式服務嘅程式、唔改檔案。先列出下一輪最值得讀嘅檔案及原因。

過時唔只係版本舊，要核對支援狀態、安全公告同實際使用情況。亦唔好因為 CI 最近冇改，就直接判斷佢唔可靠。

2. 追一條重要請求

揀一個你即將維護嘅功能，例如訂單列表，從路由開始，追到權限檢查、業務邏輯、資料存取同回應。再睇相關測試，核對程式實際保證乜。

請追蹤 [功能或路由]，由入口一路到回應。

每一步列出檔案、函數、輸入、輸出同錯誤處理。指出同步／非同步界線、外部服務同設定依賴。未找到呼叫端就講未找到，唔好推斷一定冇人用。

最後列三個需要我向原團隊確認嘅問題。

架構圖只畫已證實關係。圖上每條箭嘴，都應該搵到程式或設定支持，唔好用「一般專案通常係咁」填補空白。

3. 揀值得優先理解嘅位置

大檔案、改動密、測試少，都可以係線索，但唔係單獨判斷風險嘅答案。格式整理會令好多檔案同時出現喺 Git 記錄；少改動嘅舊程式亦可能係核心功能。

結合業務影響、錯誤紀錄、實際邏輯改動同測試質素，揀幾個重點。第一步可以只係補一個特徵測試，記錄目前行為，唔一定即刻重構。

4. 無用程式只列候選，唔即刻搬走

檢查指定模組嘅引用、路由註冊、設定、排程同公開介面。

列出疑似未使用項目，每項附搜尋範圍、證據及仍可能存在嘅動態或外部引用。暫時唔刪除或搬位。

如果要確認，需要邊種測試、觀察或團隊資料，逐項寫明。

「搬去廢棄資料夾觀察」亦可能立即令匯入或部署失效，唔比刪除天然安全。先確認相容性同外部使用者，再另開有測試嘅清理工作。

5. 整理一份可維護嘅接手指南

內容可以包括專案用途、啟動方式、已驗證資料流、重要檔案、測試方法、已知問題同待確認清單。每個操作指令都標明有冇實際執行，唔好將 Claude 猜出嚟嘅 setup 步驟寫成已驗證。

接手後每完成一件真實任務，就更新相關段落。新發現有誤，修正文件，唔好為咗配合原本架構圖而硬解釋程式。

需要升級或者現代化時，先根據風險同產品需求排次序。舊寫法未必值得改，新寫法亦未必更適合。接手指南嘅價值，係令你知道下一步要查邊度，同邊啲結論仲未有足夠證據。