寫於 2026 年 8 月 13 日（補 8 月 12 日的排程），9 月才上線（部落格的發佈額度 8 月 10 日就用完了，這批稿子要等到九月才發得出去）。文中對 Aider 與 Claude Code 的描述，以 8 月 13 日查到的官方文件與 main 分支原始碼為準，你讀到時兩邊都可能已經改版。

要不要先給 AI 一份專案地圖，這個問題有一個很硬的前提：你的主要語言得在那 39 種裡面。Aider 的語言支援表列了 150 種語言，其中打勾有 repo map 的只有 39 種，其餘 111 種只吃得到 linter。

這篇我只有一半算實戰經驗。Aider 我一次都沒跑過，下面所有關於它的行為都來自官方文件與 GitHub main 分支的原始碼靜態閱讀，該標「未實測」的地方我會標。有第一手經驗的是另外半邊，我每天在用的 Claude Code。所以這篇的視角是一個習慣了「讓它自己去找」的人，回頭看「先把地圖畫好」這條路線到底在解什麼。

兩邊都在解同一題：模型要怎麼知道這個 repo 有什麼

Aider 的做法是每次都附一份地圖過去。官方文件的說法很直接：

“Aider sends a repo map to the LLM along with each change request from the user. The repo map contains a list of the files in the repo, along with the key symbols which are defined in each file.”

這份地圖用 tree-sitter 解析原始碼，從 AST 抓出函式、類別、變數、型別這些定義，同時抓出它們在別處被引用的位置。產出長這樣（官方範例）：

1
2
3
4
5
6
7
aider/coders/base_coder.py:
⋮...
│class Coder:
│    abs_fnames = None
⋮...
│    def run(self, with_message=None):
⋮...

保留的行前面有 │，被省略的區段用 ⋮... 標出來。模型看到的是一副有洞的骨架，重點是那些洞是明示的。

Claude Code 這邊，官方 blog 講得也很白：

“Claude Code navigates a codebase the way a software engineer would: it traverses the file system, reads files, uses grep to find exactly what it needs, and follows references across the codebase.”

“It operates locally on the developer’s machine and doesn’t require a codebase index to be built, maintained, or uploaded to a server.”

拿捷運來比會很清楚。一種是出門前先印一張路線圖折進口袋，圖上只有主要站名，小站省略。另一種是到了當地才問路。每次都得問，但問到的永遠是今天的狀況。

那份地圖到底佔多少空間

這裡有一個值得停下來看的落差。官方文件寫 --map-tokens “defaults to 1k tokens”，但原始碼不是這樣算的。args.py 的 CLI 預設是 None，main.py 接到 None 之後會去問模型：

1
2
3
4
5
6
7
8
def get_repo_map_tokens(self):
    map_tokens = 1024
    max_inp_tokens = self.info.get("max_input_tokens")
    if max_inp_tokens:
        map_tokens = max_inp_tokens / 8
        map_tokens = min(map_tokens, 4096)
        map_tokens = max(map_tokens, 1024)
    return map_tokens

所以真正的預設是 context window 的八分之一，夾在 1024 到 4096 之間。一個 200k context 的模型算出來是 25000，被上限砍成 4096，換算下來地圖大約佔 context 的 2%。文件那句「預設 1k」在今天只描述了下限。

這條推論鏈是串三個檔案讀出來的（args.py → main.py → models.py），我沒實跑印出來驗證，你要用這個數字的話請自己確認一次。

聊天視窗裡還沒加入任何檔案時，預算會乘上 --map-multiplier-no-files（CLI 預設 2 倍），同時被 context window − 4096 夾住。模型手上沒有具體檔案可看的時候，地圖就給大一點，這個設計滿合理的。

至於挑選哪些符號進地圖，文件只寫 “a graph ranking algorithm”，從頭到尾沒出現 PageRank 這個字。要說它是 PageRank 得引原始碼：repomap.py 匯入 networkx、建一張 MultiDiGraph，跑的是 personalized PageRank。塞進 token 預算的方式是二分搜尋，官方容許 15% 誤差。

判準一：你的專案主體是什麼語言

這條最好判，也最容易被忽略。有 repo map 的 39 種語言裡，Java、Python、Go、Rust、TypeScript、C#、Kotlin、Swift 都在。缺席的是 html、css、scss、sql、vue、svelte、perl、powershell、markdown。

所以如果你的 repo 主體是前端模板加 SQL，Aider 的地圖對這些檔案給不出符號，頂多列出檔名。反過來說，符號密度高的靜態語言專案才是它的主場。

補一個考據。表格上 bash 沒打勾，但 2026 年 5 月 15 日的一個 commit 已經加了 bash-tags.scm，實際支援了。那張表是用 cog 自動產生的快照，這次沒重新產。所以照文件說是 39，照原始碼說是 40。我兩個數字都放給你。它揭露的事情比數字本身重要：語言支援不是模型能力問題，是有沒有人替那個語言手寫一份 tags.scm 查詢檔的工程問題。

同一頁還有一個坑。表格的 Linter 欄每一列都打勾，那不是逐語言檢查的結果，get_supported_languages_md() 裡直接寫死 linter_support = "✓"。要引用那張表，只有 Repo map 那一欄是真的驗過檔案存在。

判準二：你用的模型有多強

這條是我讀完整份文件覺得最反直覺的一段。Aider 對它不認識的模型，預設是把 repo map 關掉的。官方 FAQ 講得毫不客氣：

“This is because weaker models get easily overwhelmed and confused by the content of the repo map. They sometimes mistakenly try to edit the code in the repo map. The repo map is usually disabled for a good reason.”

弱模型會去編輯地圖裡的程式碼。想一下這個失敗模式有多合理：地圖看起來就是程式碼，有 class、有函式簽名、有欄位宣告，模型分不清哪個是索引、哪個是本體。

機制上是白名單制。models.py 的 dataclass 預設 use_repo_map: bool = False，model-settings.yml 裡 357 個模型條目中有 338 個明文寫 use_repo_map: true，沒有一個寫 false。名單上有的才開，不認識的一律關。

同一個張力在「地圖給大一點會不會更好」這題上也出現了。base_coder.py 裡有一句官方自己的警告："Warning: map-tokens > {N} is not recommended. Too much irrelevant code can confuse LLMs." N 是該模型建議值的兩倍。無關的程式碼會讓模型混淆，這是官方說的。

事先建地圖這條路線最根本的難處就在這裡。你得在涵蓋率跟雜訊之間挑一個點，而且得在還不知道使用者要問什麼之前就挑好。

判準三：repo 有多大

Aider 的官方 FAQ 承認大 repo 不是它的強項：

“Aider will work in any size repo, but is not optimized for quick performance and response time in very large repos.”

原始碼裡有一條硬失敗路徑，大到讓圖處理爆掉的時候，它會把地圖整個關掉：

1
2
3
4
except RecursionError:
    self.io.tool_error("Disabling repo map, git repo too large?")
    self.max_map_tokens = 0
    return

緩解手段是 --subtree-only 只看子目錄、或寫 .aiderignore 排掉不相關的部分。首次全 repo 掃描會慢，但官方強調 “only happens once”，之後吃 mtime 快取逐檔失效，--map-refresh 有 auto／always／files／manual 四個值可調。快取放在 repo 根目錄的 .aider.tags.cache.v3（或 v4）裡，實作是 diskcache 上的 SQLite。

現場搜尋這邊也有天花板，只是長得不一樣。Glob 單次回傳上限 100 個檔案，按修改時間排序，超過會給模型一個截斷旗標讓它自己縮小 pattern。Grep 建在 ripgrep 上，預設輸出模式是 files_with_matches，只回檔名不回內容——先知道哪些檔案有，再決定讀哪個。這其實是一份即時生成的迷你地圖，只是它按需生成、用完就丟。

順帶說一件容易被忽略的事：Claude Code 也有符號級能力，跳定義、找引用、看型別錯誤都有，走的是 LSP 工具，需要裝 code intelligence plugin。差別不在有沒有這個能力，在交付時機。Aider 把符號表事先算好塞進 prompt，LSP 是用到才問 language server，結果不常駐 context。

兩種失敗模式，你得選一種

講到這裡可以把兩邊的代價擺齊了。

Anthropic 在 context engineering 那篇文章裡的說法是，glob 跟 grep 這類基本工具讓 agent 即時取檔，”effectively bypassing the issues of stale indexing and complex syntax trees”。這句話幾乎是點著語法樹在講。但有兩件事要注意。它沒有點名任何工具，而且它旁邊那段對「索引會過期」的批評，講的對象是 RAG 與 embedding pipeline。Aider 的地圖是 mtime 增量更新的符號表，不是向量，過期問題比 embedding pipeline 輕得多。把那段批評直接搬過來罵 repo map，是偷換對象。

Anthropic 自己也承認了另一邊的代價。Agent SDK 那篇寫得很清楚：

“Semantic search is usually faster than agentic search, but less accurate, more difficult to maintain, and less transparent.”

現場找比較慢，官方認的。而且每次都要重新付一次搜尋成本。

真正的差別在失敗的形狀。地圖法的失敗是「地圖上沒有的東西模型就不知道」，但地圖用 ⋮... 明示了省略，模型看得出這裡有東西被拿掉了。現場搜尋的失敗是「模型沒想到要搜的東西就不知道」，而且沒有任何符號告訴它漏了什麼。前者是知道自己有盲區，後者是不知道自己有盲區。

三個條件全中才給地圖

我的答案不騎牆。靜態語言為主、模型夠強、repo 還沒大到讓它爆掉，三個條件同時成立的時候，事先給地圖是划算的。2% 的 context 換一份全域排序過的符號總覽，這價格很便宜。

三個條件缺任何一個，現場找更穩。語言不在清單裡，地圖是空的；模型不夠強，地圖會被拿去改；repo 太大，地圖會自己關掉。

Aider 的現況只看機器可讀的欄位，不引用二手說法。Aider-AI/aider 未封存、授權仍是 Apache-2.0、48,145 顆星，最後一次 push 到 main 是 2026 年 5 月 22 日。PyPI 上 aider-chat 最新版本 0.86.2，發佈於 2026 年 2 月 12 日。發版節奏明顯放緩了，數字給你，活著還是要收攤你自己判斷，我不替它下結論。

還有一個彩蛋值得記著。Aider 的 FAQ 提到它一次只能處理一個 repo，變通做法是 aider --show-repo-map > map.md，在每個 repo 裡各匯出一份地圖，然後在 repo-A 裡用 /read 讀進 repo-B 的地圖。地圖被匯出成一份可以傳遞的文件，這是「事先建地圖」這條路線的極致形態。你的 CLAUDE.md 如果寫過「這個專案的目錄長怎樣、核心類別在哪」，那你其實已經在手動做同一件事了，只是排序演算法是你自己的腦袋。

來源：Aider Repo map 文件、Aider 語言支援表、Aider FAQ、Aider tree-sitter 技術文（2023-10-22）、How Claude Code works、Tools reference、Claude Code in large codebases、Building agents with the Claude Agent SDK、Effective context engineering