Claude Code 處理舊 codebase：點樣接手一個 5 年舊項目

情境

你新入職 / 接手一個項目。開 repo：

• 5 年舊 codebase
• 150 個檔案、2 萬幾行代碼
• 無 README（或者得返啲寫住「How to set up」嘅過時草稿）
• 無架構文件
• 3 個原作者已離職
• CI 跑得過，但無人解釋啲依賴 (dependencies) 之間嘅關係

你第一個禮拜要搞清楚呢個 codebase 點運作，先可以推出新功能。資深開發者嘅預設工作流程：

1. 隨機開檔案、係咁碌、嘗試搵規律（一頭霧水）
2. 跑 grep 搵類似關鍵字
3. 喺 Slack 問前同事（覆得慢 / 已離職）
4. 1 個禮拜後仲係一頭霧水

呢篇用 Claude Code 自動梳理個 codebase，2 個鐘出一份接手指南，比起盲摸摸搞足一個禮拜快好多。

跟住做

1. Codebase 首次掃瞄

cd legacy-project
claude

入 Claude Code 之後：

我啱啱接手呢個 codebase。冇 README 同架構文件。我要喺 1-2 個鐘內理解個項目。請：
掃瞄 repo 結構：最頂層資料夾 + 主要子資料夾，用 2-3 句話描述每個負責乜
搵出進入點：main、index、server start file、test runner
梳理主要數據流：由進入點開始，搵 1-2 條最重要嘅代碼路徑（用戶請求 → 業務邏輯 → 回應）
技術棧清單：語言、框架、主要 library、構建工具、測試框架
項目老化信號：package.json / pyproject.toml 嘅依賴是否過時、是否有 lock file 唔一致、CI 文件嘅最新更新日期
輸出一份「Onboarding doc v0」（markdown），約 1-2 頁。寫成新開發者第一日必讀嘅文件。唔好幻想——任何唔肯定嘅嘢標示「⚠️ Needs verification」。

Claude Code 會花 5-10 分鐘掃瞄，出初步文件。

2. 搵出熱點 (hotspots)

基於第一步嘅梳理，幫我搵 5 個「熱點」——即係：
最複雜檔案（最多行數 / 最多 function / 最多層層疊邏輯）
最頻繁改動嘅檔案（用 git log 搵近 1 年 commit 最多嘅）
最關鍵嘅業務邏輯（例如 payment / auth / data layer）
最脆弱嘅檔案（無測試覆蓋、或有測試但失敗率高）
最「有陣陳年味」嘅檔案（大量俾人 comment 起咗嘅代碼、5 個以上 TODO、已知嘅反面模式）
每個 hotspot 畀返：檔案路徑、原因、估計複雜度（1-5 星）、建議嘅第一步行動（閱讀 / 重構 / 測試 / 唔好搞住）。

3. 搵無用代碼 (dead code)

請幫我識別潛在嘅無用代碼：
已 export 出嚟但從未被引用嘅 function
branch / case 入面永遠行唔到嘅代碼
已 comment 起、而且超過 1 年未掂過嘅代碼
喺 .env.example 有但 codebase 從來冇讀取過嘅環境變數
輸出一份「dead code candidates」清單。每個附上：
檔案 + 行數
確定程度（高 / 中 / 低）
建議下一步行動：刪除 / 搬去廢棄資料夾 / 留低 + 加 TODO
注意：呢類偵測永遠有誤判（例如透過 reflection 引用、外部 API 合約等）。行動之前要人手驗證每個高確定性嘅候選項目。

4. 生成接手指南落 repo

基於第 1-3 步嘅發現，整一份完整嘅接手指南寫落 docs/ONBOARDING.md：結構：
項目一覽（1 段 + 技術棧圖表）
架構圖（用 ASCII / Mermaid）
設定教學（參考現有設定腳本，加返我發現嘅已知問題做備註）
主要代碼路徑（2-3 個流程拆解）
必知熱點（指出關鍵檔案畀新開發者睇）
已知技術債（列出無用代碼、廢棄寫法、需要重構嘅地方）
接手清單（新開發者頭 1-7 日要做嘅嘢）
寫成新資深開發者第一日嘅參考資料。語氣：直接、對複雜度坦白（唔好扮「輕鬆上手」）。

5. 邊學邊更新

接手指南 v0 唔會係完美。接住 2-4 個禮拜你做新功能嘅時候，每次有新理解就更新份文件。

呢份持續更新嘅文件嘅回報：3 個月後下個新開發者入嚟，佢有你記錄低嘅學習成果，唔需要由零開始。

變化例子

變化 1：針對特定除錯摸索

我撞到一個 bug：[描述病徵]。請幫我：
由病徵倒推最有可能嘅根本原因（列出 3-5 個假設，按可能性排）
對每個假設，指引我去驗證邊個檔案 / function
由最有可能嗰個開始帶我睇代碼
呢個係「摸石過河」唔係機械式修補——你係我嘅資深開發者拍檔。

變化 2：測試覆蓋率檢視

請審視我嘅測試覆蓋率：
列出測試框架 + 而家覆蓋率 %
搵出 5 個關鍵業務邏輯檔案但缺測試
對每個建議最基本嘅測試案例（順利流程 + 2 個邊緣情況）
建議測試優先次序：邊個寫先（按風險權重）
估計追返到 60% 覆蓋率（基本目標）所需要嘅功夫

變化 3：現代化路線圖

我想將個 codebase 現代化（升級依賴、重構舊寫法）。請：
盤點依賴清單 + 標示過時（落後咗主要版本）
搵出破壞性改動（升級邊個依賴會引起連鎖反應）
建議次序：邊個升級先做（低風險）、邊個等吓先（高風險）
估計功夫 + 風險
建議用「絞殺者模式 (strangler pattern)」嘅重構方法（漸進式，唔好一次過大換血）
呢個係 3-6 個月嘅路線圖，唔係 1 個禮拜做完。

拆解：點解 work，同邊度會仆街

跟到上面就已經用得。下面呢段係畀**想由「梳理一次 demo OK」做到「份接手指南真係信得過、唔會帶錯路」**嘅人——初學者可以跳過，唔影響你跟住做。

舊 codebase 梳理最危險嘅地方係：Claude 講得好肯定，唔代表佢講得啱。佢冇你嘅 production 記憶，只睇到眼前嘅文字，所以呢幾個位會爆，你要預咗：

1. Claude 會「填補空白」當係事實

冇 README、冇架構文件嘅時候，Claude 傾向用「呢類項目通常點」嚟補返佢睇唔到嘅嘢——出嚟好似好肯定，其實係估。

• 會出事：份 Onboarding doc 寫到頭頭是道，但有幾段係幻想出嚟嘅架構，新人照住信，第一個 PR 就撞板。
• 點救：prompt 已經叫佢標「⚠️ Needs verification」要堅持執行——任何冇直接喺代碼見到證據嘅 claim 都當未確認，自己逐條開檔對返先寫死落 docs/ONBOARDING.md。

2. 偵測 dead code 睇唔到動態引用

第三步搵無用代碼，靠嘅係靜態睇「邊度 import、邊度 call」。但好多舊項目用 reflection、字串砌出嚟嘅 function 名、route 自動註冊、或者畀外部 service 直接 call 嘅 endpoint——靜態睇全部似「冇人用」。

• 會出事：你照「高確定性」清單刪咗一個睇落 dead 嘅 function，結果係某個 cron job 或者第三方 webhook 唯一入口，靜默壞咗，幾日後先有人發現。
• 點救：刪之前 grep 埋字串形式嘅引用（function 名、route 路徑），睇 config / job 排程 / 對外合約；寧願「搬去廢棄資料夾 + 觀察一個 release cycle」，唔好直接 delete。

3. Codebase 太大，塞唔晒入 context

2 萬行、150 個檔案，Claude 唔會一次過讀晒。佢實際係抽樣睇咗一部分檔案就落結論。

• 會出事：「主要數據流」「最複雜檔案」呢類結論，可能漏咗佢根本冇打開過嗰半邊 codebase，得出片面嘅地圖。
• 點救：分批做，唔好叫佢「睇晒成個 repo」。逐個 module / 逐個資料夾梳理，每次明確指定範圍；最後問佢「你呢次實際讀咗邊幾個檔案」對返數，未掂過嘅範圍自己補。

4. git log 嘅「頻繁改動」會誤導

第二步用 git log 搵熱點係好招，但 commit 次數多唔一定等於「核心又脆弱」。一個大型 reformat、改 import 路徑、或者 rename，會喺 history 留低大量 commit，但其實同風險無關。

• 會出事：你照住「改動最多」嘅清單去重點睇 / 重構，結果花咗時間喺一啲純粹被批量改過、其實好穩定嘅檔案。
• 點救：叫佢區分「邏輯改動」同「機械式改動（rename / format / 搬位）」，熱點要結合「改得密 + 出過 bug / revert 過」一齊睇，唔好淨係數 commit 次數。

呢幾個位，就係「梳理一次 demo OK」同「份接手指南真係帶得啱路」之間嘅距離。

一個思維紀律

接手舊 codebase 嘅最大陷阱：「呢啲代碼寫得好差，我要全部重寫」。

幾乎永遠都係錯。原因：

• 你睇唔到原作者面對嘅限制（時間、工具、團隊背景）
• 現有代碼有 5 年經過生產環境測試嘅 bug fix 係你睇唔到嘅
• 重寫嘅成本永遠超估算 2-3 倍

正確心態：尊重接手嘅代碼，當佢係原作者盡心盡力嘅初步嘗試；了解清楚之後先做策略性改善，唔好為咗滿足自我而盲目重寫。

Claude Code 嘅用處喺呢個理解階段——將「我要 1 個月睇代碼」嘅阻力，降到「2 個鐘梳理 + 持續更新」。

呢個解鎖嘅唔係「重寫」，係有充足資訊下嘅漸進式改善。資深開發者嘅真實價值，係知道保留乜嘢同改變乜嘢。Claude Code 幫你達到嗰個有知情權嘅狀態，剩低嘅判斷仍然喺你手。