# Claude Code 為什麼會重讀整個專案，以及如何解決

> Claude Code 不會為程式碼建立索引，並且每次都會從頭重讀專案，消耗大量 token。本文說明如何透過 MCP 為它加入持續保存的程式碼記憶，並降低用量。

Source: https://ailoot.ai/blog/zh-hant-tw/claude-code-rereads-project/
Canonical: https://ailoot.ai/blog/zh-hant-tw/claude-code-rereads-project/
Language: zh-Hant-TW
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-200
Revision: sha256-2a13b58bc5b2c03b135effd4bc0ffc3e1676d8994809348d4bc2ec9b3457ab2a


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重點摘要">

重點摘要

Claude Code 不會保留程式碼索引。每次工作階段都會重新搜尋專案，並從頭讀取檔案，因此 token 都花在摸索環境，而不是實際工作上。你可以透過程式碼記憶解決這個問題：透過 MCP 安裝索引伺服器，Claude 就能使用現成的專案地圖，不必重讀整個專案。

</div>



[Ailoot 文件：API、金鑰與連線](https://ailoot.ai/docs/)。

## Claude Code 為什麼每次都會從頭重讀專案？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重點摘要">

重點摘要

Claude Code 沒有內建程式碼索引。它會使用三種工具搜尋專案：依模式尋找檔案、搜尋文字中的字串，以及讀取整個檔案。這稱為代理式搜尋：模型自行決定要查看哪些地方，並在每個新任務中重複這個過程。它不會記得上一個工作階段，因此每次都從頭開始。

</div>

許多人以為這是錯誤。事實上，這就是 Claude Code 的設計方式：它沒有自己的專案索引。當你請它修正某個問題時，它手邊沒有現成的程式碼地圖，因此會再次探索專案：找出相關檔案、搜尋需要的字串，並將檔案讀入記憶體。

這種方法確實有優點。程式碼永遠是最新的，因為沒有可能過時的索引。也不需要設定任何東西。你的程式碼也不會被傳送到任何資料庫。

但它也有缺點：每個新任務都代表要重新搜尋並讀取檔案。即使 Claude 已經在上一個工作階段弄清楚所有內容的位置，仍會再次花費 token 摸索。專案越大，這些摸索的成本就越高。這正是代理看起來像在「把所有東西都讀一遍」的原因。

## 這樣到底會消耗多少 token？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重點摘要">

重點摘要

即使還沒重讀程式碼，Claude Code 每次請求也會傳送約 33,000 個 token 的系統資料。在實際工作設定中，你還沒輸入任何文字，總量就已達 75,000–85,000 個 token。接著還要加上重讀檔案的用量；根據官方文件，讀取檔案是最消耗上下文的項目。

</div>

成本在你送出請求前就開始了。一項獨立測量簡單地說明了這點：Claude Code 在讀取你訊息的第一個字元之前，就會傳送約 33,000 個 token 的系統提示和工具說明。相比之下，OpenCode 起始用量約為 7,000 個 token。

接著是重讀檔案。每次搜尋檔案和讀取檔案，都會增加上下文中的 token。Claude Code 官方文件直接指出：讀取檔案是上下文用量的主要來源。分析一個有 2,400 個 token 的 auth.ts，就代表 Claude 會讀取這 2,400 個 token；它在摸索過程中開啟的每個檔案也都是如此。

對我們的讀者來說，這代表金錢和使用額度。開始接觸 vibe coding 的人最害怕的事，就是「付了錢，結果額度白白用完」。如果代理每次都掃描專案，並從頭重讀檔案，上下文消耗速度就會加倍：先花在系統額外負擔，再花在摸索上。我在指南[〈Claude Code 的 token 都用到哪裡了〉](https://ailoot.ai/blog/zh-hant-tw/where-claude-code-tokens-go/)中，完整整理了 Claude Code 的 token 究竟花在哪些地方；重讀專案是其中九種模式之一。



## 什麼是持續保存的程式碼記憶？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重點摘要">

重點摘要

程式碼記憶是一份現成的專案地圖，代理可以查閱，而不必重讀檔案。另一個工具會掃描一次程式碼，建立函式、檔案和連結的結構，並將它儲存在磁碟上。之後，當你問「付款是在什麼地方處理的？」Claude 就能透過一次查詢從地圖取得答案，而不必逐一檢查每個檔案。

</div>

程式碼記憶正好補足 Claude 會重讀專案的缺口。概念很簡單：讓某個工具掃描一次所有程式碼、建立地圖，並隨時保留這份地圖。這樣代理每次就不必從頭搜尋，而是直接詢問地圖。

技術上來說，運作方式如下。另一個工具會掃描專案，並將它拆解成各個元件：有哪些函式和類別、誰呼叫誰，以及哪些檔案彼此相關。這個結構會儲存在磁碟上。當 Claude 需要了解付款邏輯在哪裡，或編輯某個函式會造成哪些影響時，只要對地圖進行一次目標明確的查詢，不必讀取數十個檔案。

這份地圖透過 MCP 連接。MCP 是將外部工具連接到 Claude Code 的標準方式（其他伺服器的連線方式可參閱指南[〈Claude Code 的 MCP 伺服器〉](https://ailoot.ai/blog/zh-hant-tw/mcp-servers-claude-code/)）。程式碼記憶工具會加入自己的地圖搜尋指令，Claude 需要了解專案情況時，就會自行使用這些指令。

實際差異就在於「為了找出一個函式而讀取整個資料夾」，還是「詢問地圖那個函式在哪裡」。前者會消耗數萬個 token，後者只要數百個。

## 兩種程式碼記憶方法有什麼不同？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重點摘要">

重點摘要

有兩種實用工具，而且都採用 MIT 授權，免費使用。Serena 為代理提供類似智慧型開發環境的程式碼導覽能力，適合精準編輯。claude-context 透過 embeddings 以語意搜尋，但需要外部資料庫和金鑰。它們記住的內容各不相同。

</div>

程式碼記憶工具的差別在於它們從專案建立的內容。最簡單的理解方式是：一種提供像外科醫師般精準編輯的能力，另一種則依語意搜尋。

| 比較項目 | Serena | claude-context |
|----|----|----|
| 記憶類型 | 透過開發環境引擎進行程式碼導覽 | 透過 embeddings 進行語意搜尋 |
| 可找到的內容 | 定義、實際呼叫位置、依符號編輯 | 依描述尋找程式碼：「付款邏輯在哪裡」 |
| 外部相依項目 | uv 套件管理工具；TypeScript 和 JavaScript 也需要 Node 20+ 和 npm | 外部資料庫 + 金鑰 + Node 20+ |
| 安裝方式 | 一個指令 | 含三項設定的指令 |
| token 節省 | 未公布確切百分比 | 品質相同時約 40% |
| GitHub 星數 | 26,468 | 12,138 |
| 優點 | 跨整個程式碼庫謹慎重構 | 不必知道確切名稱也能找到需要的內容 |
| 缺點 | 支援的語言較少，也沒有語意搜尋 | 設定繁瑣，需要雲端服務 |

GitHub 星數統計截至 2026 年 7 月 15 日（依據 GitHub API）。這兩種工具皆為免費開放原始碼，都能搭配 Claude Code 使用，也都能作為 MCP 伺服器連接。

給非程式設計師的簡短總結：Serena 就像外科醫師的雙手：當你要在專案中反覆編輯同一部分，而且精確度很重要時，就使用它。claude-context 是語意搜尋，能依描述尋找程式碼，但需要設定雲端資料庫和金鑰。

## 什麼時候該選 Serena 或 claude-context？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重點摘要">

重點摘要

需要精準編輯時，Serena 很實用：例如在整個專案中重新命名函式、替換函式本體，或找出所有實際呼叫位置。它使用與智慧型開發環境相同的引擎，依語意而非文字比對來編輯程式碼。如果你需要依描述搜尋程式碼，也不介意設定外部資料庫和金鑰，就選 claude-context。

</div>

這兩種工具並不是在爭奪同一個獎項。它們記住的內容各不相同，因此該選哪一種，取決於任務需求。

如果你經常進行重構，就選 Serena。它為代理提供類似智慧型開發環境的程式碼導覽能力：找出函式定義和所有實際呼叫位置，接著謹慎地在整個專案中重新命名函式或替換函式本體。作者這樣描述它的優點。

<figure>
<blockquote>
<p>透過 MCP 使用的一套強大程式碼工具：語意搜尋與編輯，宛如專為代理打造的開發環境。</p>
</blockquote>
<figcaption>— Serena, https://github.com/oraios/serena</figcaption>
</figure>

Serena 沒有公布確切的節省百分比，我也不會為它捏造數字。它的優點不同：一般搜尋可能回傳 40 個結果，其中包括註解和字串，之後 Claude 還要讀取四個完整檔案；Serena 則能透過幾次精確查詢給出答案。這代表呼叫次數和錯誤比對都更少，因此代理編輯錯誤內容的風險也更低。

如果你需要語意搜尋，也不介意設定過程，就選 claude-context。它會將程式碼轉換為向量（意義的數值指紋），並依描述搜尋：「找出付款邏輯在哪裡」，即使你不知道函式名稱也可以。這種搜尋的代價是需要額外設定。

<figure>
<blockquote>
<p>平均來說，claude-context 在維持相同搜尋品質的同時，可將 token 用量降低約 40%。</p>
</blockquote>
<figcaption>— zilliztech/claude-context, https://github.com/zilliztech/claude-context</figcaption>
</figure>

claude-context 需要外部向量資料庫、embeddings 服務商的金鑰，以及較新版本的 Node。在這兩種工具中，它的設定較繁瑣，因此我建議新手先從其他工具開始。

## 不使用第三方工具，直接在 Claude Code 中可以做什麼？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重點摘要">

重點摘要

內建指令能解決一半問題。`/context`會準確顯示哪些內容正在使用上下文。`/compact`會壓縮對話記錄，`/clear`會在開始新任務前重設記錄，`/doctor`則會找出不必要的項目並建議清理。使用精簡的 CLAUDE.md，而不是內容過多的版本，每則訊息就能省下數千個 token。

</div>

安裝第三方工具之前，先充分運用 Claude Code 已經提供的功能。這些指令免費，而且安裝後即可使用。

1. `/context`—即時顯示佔用上下文視窗的內容：系統提示、CLAUDE.md、記憶、工具和檔案。`/mcp`指令會顯示每個已連線伺服器的成本，`/memory`則會顯示啟動時載入的內容。
2. `/compact`—將對話記錄壓縮成簡短摘要，並繼續同一個任務。你可以在`/compact`後補充要保留的內容，引導摘要的重點。
3. `/clear`—清除整份記錄。官方建議在切換到不相關的任務時執行，避免舊對話擠占你需要的檔案空間。
4. `/doctor`（也稱為`/checkup`，於 2026 年 7 月 8 日推出）—診斷設定並提出修正建議：移除 CLAUDE.md 中的重複內容、找出未使用的工具和伺服器，以及偵測速度緩慢的處理程式。

另外談談 CLAUDE.md。每個工作階段開始時，這個檔案都會載入上下文並包含在每則訊息中。如果內容過多，你就得持續為它付出成本。官方建議將它控制在 200 行以內，並將參考細節移到需要時才載入的 skills。我在另一份指南[〈如何設定 CLAUDE.md〉](https://ailoot.ai/blog/zh-hant-tw/claude-md-template/)中介紹了正確整理 CLAUDE.md 的方法。

另一種內建的調整方式是使用子代理。它們有各自獨立的上下文，因此你可以將耗費大量篇幅的閱讀和摸索工作交給它們，而不會讓主要上下文視窗變得臃腫。Anthropic 在工程分析中如此說明這項一般原則。

<figure>
<blockquote>
<p>良好的上下文管理，代表找出能產生預期結果的最小資訊量 token 集合。</p>
</blockquote>
<figcaption>— Anthropic, https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents</figcaption>
</figure>

## 多加一個 MCP 伺服器會讓上下文變得更大嗎？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重點摘要">

重點摘要

這是合理的擔憂，但答案是否定的。自 2026 年起，Claude Code 預設不會將完整的 MCP 工具說明載入上下文，而是延後載入，只在實際需要時才讀取。啟動時只有名稱會納入上下文。因此，程式碼索引增加的系統額外負擔微乎其微，卻能省下原本用於重讀檔案的數千個 token。

</div>

「多一個伺服器就會增加上下文負擔」的說法過去是對的，但 Claude Code 已經改變了。MCP 工具說明現在預設會延後載入：工作階段啟動時，只有伺服器名稱會納入上下文；當任務需要特定工具時，才會載入完整說明。文件中直接說明了這一點。

<figure>
<blockquote>
<p>工具搜尋會延後載入工具說明，直到 Claude 需要時才讀取，以降低 MCP 的上下文用量。工作階段啟動時只會載入工具名稱，因此新增 MCP 伺服器幾乎不會影響上下文視窗。</p>
</blockquote>
<figcaption>— Claude Code Docs, https://code.claude.com/docs/en/mcp</figcaption>
</figure>

程式碼記憶的計算很簡單：工具名稱只有少量固定額外負擔，代理不再重讀檔案則能省下數千個 token。整體來看，使用索引顯然更划算。

有幾點需要坦誠說明，避免你期待它帶來奇蹟。索引偶爾需要重建：地圖反映的是掃描當時的程式碼，大幅修改後就要更新（不同工具的做法不同：有些會自動更新，有些則需要執行指令）。此外，像「token 減少 120 倍」這類驚人的說法，描述的是特定查詢的最佳情況，不代表每項任務都會有這種結果。實際節省幅度較為有限，但仍然明顯。如果你想深入了解如何避免整體上耗盡使用額度，可以參閱另一篇分析[〈如何避免用光 Claude Code 的使用額度〉](https://ailoot.ai/blog/zh-hant-tw/claude-code-token-limits-saving/)。

## 今天可以從哪裡開始？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重點摘要">

重點摘要

從免費又快速的做法開始。執行`/doctor`清理不必要的項目，再將 CLAUDE.md 縮減到 200 行。這些步驟能減少 Claude 帶進每項任務的內容，並開始節省 token 和使用額度。

</div>

去掉所有不必要的內容，今天的計畫很簡單：

1. 執行`/doctor`，並清理它提出的項目：CLAUDE.md 中的重複內容和未使用的工具。
2. 將 CLAUDE.md 縮減到 200 行，並把參考資料移到 skills。

接著依照需求選擇：如果你經常重構，就加入 Serena 進行精準編輯；如果需要語意搜尋，就設定 claude-context。程式碼記憶和精簡的上下文，今天就足以解決主要痛點。

<div class="section" role="doc-bibliography" aria-label="來源">

### 來源

- [Serena，GitHub](https://github.com/oraios/serena)
- [zilliztech/claude-context，GitHub](https://github.com/zilliztech/claude-context)
- [Claude Code：上下文視窗、/compact、/clear、/context（官方文件）](https://code.claude.com/docs/en/context-window)
- [Claude Code：連接 MCP 與工具搜尋（官方文件）](https://code.claude.com/docs/en/mcp)
- [Anthropic：為 AI 代理有效管理上下文](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)

</div>



如果你需要透過 Ailoot 使用 AI 模型，請參閱 [Ailoot](https://ailoot.ai/)。

## 常見問題：Claude Code 為什麼會重讀整個專案，以及如何解決

### 何時該選符號導覽，而不是依語意搜尋程式碼？

尋找定義、呼叫位置或精確重構，適合 Serena 類符號導覽。知道需要的行為卻不知符號名稱時，可用 claude-context 類語意搜尋，但需要另外設定資料庫與 embeddings。

### 修改程式後，還能直接相信程式地圖嗎？

先確認索引已更新。地圖反映的是掃描時的程式，各工具更新方式不同。用地圖定位相關程式後，修改前仍應查看目前檔案。


## Ailoot · 公司及其專案組合

Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。

公司及其專案組合：數百萬客戶，每月銷售額達數十億。

Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。