Claude Code 接手老項目：先讀懂代碼庫、用 /init 生成 CLAUDE.md、再用計劃模式小步修改

本文根據 Claude Code 官方文檔《Common workflows》《How Claude remembers your project》《Best practices for Claude Code》《Commands》《Checkpointing》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

• 剛接手一個沒人講得清楚的老項目，打算讓 Claude Code 幫忙上手的人；
• 已經用過 Claude Code，但每次開新會話都要重新解釋項目結構的人；
• 想知道 /init 到底生成什麼、生成之後該怎麼改的人。

通用的「讓 AI 讀懂陌生代碼」思路本站已有 /guides/ai-read-unfamiliar-codebase，本文只講 Claude Code 自己的做法：命令、文件和設定。

結論先說

1. 先探索，後動手：官方的做法是從寬到窄提問，先要整體概覽，再追問架構、數據模型、認證流程，這一步不改任何文件。
2. /init 生成 CLAUDE.md 只是起點：官方說它會分析代碼庫，寫出它發現的構建命令、測試說明和項目約定；已有 CLAUDE.md 時，它給出改進建議而不是覆蓋。生成後的工作主要是刪行。
3. CLAUDE.md 只寫 Claude 讀代碼讀不出來的東西：官方建議每個文件控制在 200 行以內，寫得具體、能驗證。
4. 改動前先進計劃模式，Claude 只讀文件、提方案，你批准後才會動手；每一步都讓它跑測試，並用 /rewind 兜底。

圖：本站根據 Claude Code 官方文檔：Common workflows 整理的示意圖

第一步：只讀探索，不要急着改

官方的流程很樸素：進入項目根目錄，輸入 claude 啟動，然後先問高層問題。官方給的例子是 give me an overview of this codebase，接着再追問 explain the main architecture patterns used here、what are the key data models?、how is authentication handled?。官方的小貼士有三條：先寬後窄；問項目用到的編碼約定；讓它整理一份項目專用術語表。

找某個功能的代碼時，官方也是三步：先讓它找出相關文件，再問這些文件怎麼配合，最後讓它沿着執行流程從前端追到數據庫。提問時多用項目裏的專業詞彙。

提示詞 1：只讀概覽（可直接複製）

text
這是一個我剛接手的項目，請先只讀不改，不要創建或修改任何文件。
請給我一份概覽：1）這個項目是做什麼的；2）目錄結構和每個頂層目錄的職責；3）用了哪些主要技術和框架；4）怎麼安裝依賴、啟動、跑測試（給出具體命令，並說明你是從哪個文件看到的）；5）你看不懂或覺得可疑的地方，單獨列出來。
凡是你沒有在代碼裏直接看到的內容，請標註「推測」，不要寫成確定的事實。

讀大倉庫時，探索會往上下文裏塞很多文件內容。官方的建議是把探索交給子智能體（subagent）：它在自己的上下文窗口裏讀文件，只把結論彙報回來。官方的寫法是直接說 use a subagent to investigate how our auth system handles token refresh。

提示詞 2：交給子智能體調查

text
請用一個子智能體去調查「訂單狀態是怎麼流轉的」：從接口入口追到數據庫寫入，列出涉及的文件和函數，畫出狀態變化的順序。
只把結論和關鍵文件路徑彙報給我，不要把大段源碼貼回來。

第二步：用 /init 生成 CLAUDE.md，然後刪行

在會話裏運行 /init。官方說明：Claude 會分析代碼庫並生成一個起始 CLAUDE.md，包含它發現的構建命令、測試說明和項目約定；如果文件已經存在，它建議改進而不是覆蓋。如果項目裏有 Cursor 規則（.cursor/rules/ 或 .cursorrules）或 Copilot 指令（.github/copilot-instructions.md），/init 會把相關部分讀進來。想要更完整的交互式流程，可以先把環境變量 CLAUDE_CODE_NEW_INIT 設為 1，再運行 /init，這時它會問你要設定哪些東西（CLAUDE.md、技能、鉤子）。另有 /import 命令，可以把別的編碼代理的配置（例如 AGENTS.md）帶進來。

生成之後別直接用。官方在最佳實踐裏的判斷標準是兩個問題：這件事 Claude 讀代碼能找到嗎？它真的會去找嗎？兩個都是「是」就別寫。適合留下的是：

• 怎麼驗證工作：測試、類型檢查、靜態檢查的確切命令，以及怎麼只跑一個測試文件；
• 代碼裏有誤導性的地方：滿處都是但新代碼不該照抄的老寫法，看起來沒用其實還在用的目錄；
• 倉庫裏沒有的決定：團隊約定的錯誤處理方式、部署流程、哪些改動要做遷移評審；
• 你已經糾正過兩次以上的事。

官方給的 CLAUDE.md 示例只有十來行：命令、約定、坑三段。官方還建議：每個 CLAUDE.md 控制在 200 行以內；寫法要具體可驗證（「使用 2 空格縮進」而不是「格式要規範」）；只對部分目錄有用的規則放進 .claude/rules/ 並用 paths: 限定範圍；個人偏好放 CLAUDE.local.md 並加進 .gitignore。

寫完後在會話裏運行 /context all，檢查「Memory files」列表裏有沒有它；運行 /doctor 可以建議刪掉哪些 Claude 本來就能從代碼推出來的內容，/doctor prompt-audit 會找出過時、指向不存在的文件或互相矛盾的指令，但官方說明它只出報告，你讓它改它才改。關於 CLAUDE.md 與 AGENTS.md 的關係，見 /guides/claude-md-agents-md。

提示詞 3：精簡剛生成的 CLAUDE.md

text
請檢查項目根目錄的 CLAUDE.md：
1）刪掉你讀代碼就能知道的內容；
2）保留並補全：安裝、啟動、跑全部測試、跑單個測試文件、類型檢查、靜態檢查的確切命令；
3）把「這個項目裏容易踩的坑」單獨列一節，每條一句話，並註明依據的文件；
4）總長度控制在 100 行以內。
先給我修改後的全文和刪減清單，我確認後再寫入文件。

第三步：計劃模式，先看方案再動手

官方提供三種進入計劃模式的方式：啟動時 claude --permission-mode plan；會話中按 Shift+Tab 切換，直到狀態欄出現 ⏸ plan mode on；或者直接 /plan 加一句描述，例如 /plan fix the auth bug。計劃模式下 Claude 讀文件、提方案，批准之前不會改文件。更多說明見 /guides/claude-code-plan-mode。

提示詞 4：計劃模式下的小改動

text
我要修改的是：【具體需求，例如：訂單列表按創建時間倒序，目前是正序】。
請只讀不改，先告訴我：1）要改哪些文件、哪幾個函數；2）現有的測試在哪裏、能否覆蓋這個改動；3）改動可能影響哪些調用方；4）你建議的最小改法，以及需要新增的測試。
不要順手重構無關代碼。

不知道自己想要什麼的時候，官方還給了一個辦法：讓 Claude 採訪你，寫成規格文件。例如「Interview me until you could write the spec, then write it to SPEC.md」，之後開一個新會話照着 SPEC.md 做。

第四步：小步改、跑檢查、能回退

官方的重構建議是小步、可測試地增量進行，並要求保持行為不變；改完讓它運行測試。最佳實踐裏更強調：給 Claude 一個能返回通過或失敗的檢查，比如測試文件、構建的退出碼、靜態檢查工具，沒有它，Claude 只能憑「看起來做完了」收工。

提示詞 5：帶檢查的小步修改

text
按剛才確認的方案實施，只改計劃裏列出的文件。
改完後運行【測試命令】，如果有失敗，讀輸出並修復後再跑，直到通過。
最後告訴我：改了哪些文件，運行了什麼命令，輸出結果是什麼。不要只說「測試通過」，要把命令和關鍵輸出貼出來。

出錯了怎麼辦：連按兩次 Esc，或輸入 /rewind，可以選擇回退代碼、回退對話，或兩者同時回退。但官方明確說明有邊界：只由 Bash 命令改動、且 Claude 沒用文件編輯工具改過的文件不會被追蹤，這類改動要用 Git 來撤銷。老項目務必先確認工作區是乾淨的，或者先建一個分支。回退細節見 /guides/claude-code-rewind-checkpoints-undo。

圖：本站根據官方 Best practices 與 Checkpointing 文檔整理的示意圖

常見問題

Q：對話越來越長，Claude 開始忘事怎麼辦？

重要結論寫進 CLAUDE.md，別隻留在對話裏；對話本身的整理見 /guides/claude-code-context-compact。官方還提到，會話中可以用 /context 看是什麼佔滿了上下文。

Q：下次接着做，怎麼找回上次的會話？

官方寫的是 claude --continue 恢復當前目錄最近的會話，claude --resume 從列表裏選。

Q：大型 monorepo 也這樣做嗎？

官方有單獨一頁講 monorepo 和大型代碼庫的配置，思路是在子目錄放嵌套的 CLAUDE.md，讓規則只在對應目錄生效。

訂閱和額度

Claude Code 需要付費訂閱帳號登入，讀大項目、跑多輪會話會消耗較多額度。想了解訂閱選擇可以看 /chongzhi/claude-code，價格和額度以官方頁面當前顯示為準。

相關教學

• /guides/claude-code-getting-started：安裝、登入和第一個任務
• /guides/claude-code-best-practices：官方最佳實踐整理
• /guides/ai-read-unfamiliar-codebase：通用的讀陌生代碼思路

參考資料

• Claude Code 文檔：Common workflows — https://code.claude.com/docs/en/common-workflows
• Claude Code 文檔：How Claude remembers your project — https://code.claude.com/docs/en/memory
• Claude Code 文檔：Best practices for Claude Code — https://code.claude.com/docs/en/best-practices
• Claude Code 文檔：Commands — https://code.claude.com/docs/en/commands
• Claude Code 文檔：Checkpointing — https://code.claude.com/docs/en/checkpointing