codebase-memory-mcp 使用教學:給 Claude Code、Codex 加程式碼庫記憶

整理 DeusData/codebase-memory-mcp 的一鍵安裝、Windows 安裝、UI、自動索引、更新卸載,以及適合 AI 程式 Agent 的程式碼庫記憶場景。

DeusData/codebase-memory-mcp 是一個程式碼智慧 MCP server。它會把程式碼庫索引成持久知識圖譜,讓 Claude Code、Codex、Gemini CLI、Aider、OpenCode 等 Agent 更快查詢專案結構。

專案地址:

https://github.com/DeusData/codebase-memory-mcp

文件站:

https://deusdata.github.io/codebase-memory-mcp/

一鍵安裝

macOS / Linux:

1
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

如果想同時安裝圖形介面:

1
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

Windows:

1
2
3
4
5
6
7
8
# 1. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. (Optional but recommended) Inspect the script
notepad install.ps1

# 3. Run it
.\install.ps1

手動安裝

macOS / Linux 解壓後安裝:

1
2
tar xzf codebase-memory-mcp-*.tar.gz
./install.sh

Windows:

1
2
Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
.\install.ps1

打開 UI

1
codebase-memory-mcp --ui=true --port=9749

自動索引和更新

開啟自動索引:

1
codebase-memory-mcp config set auto_index true

更新:

1
codebase-memory-mcp update

卸載:

1
codebase-memory-mcp uninstall

適合怎麼用

它適合程式碼庫比較大、Agent 經常反覆讀檔案的場景。例如:

  1. 老專案結構複雜,AI 總是找錯入口。
  2. 多語言倉庫裡需要快速查依賴關係。
  3. 想減少 Agent 把大量檔案塞進上下文。
  4. 希望用 MCP 給多個編碼工具共享同一份程式碼記憶。

安裝後建議先讓 Agent 做一個小任務:解釋專案結構、找到某個 API 的呼叫鏈、定位某個設定入口。確認它能正確查詢後,再用於真實改程式碼任務。

AI Agent 程式碼庫記憶工具的路線比較

AI Agent 寫程式時最常見的問題,不是模型完全不會寫,而是它不知道這個程式碼庫真正長什麼樣。

它可能不知道入口檔案在哪裡,不知道某個 helper 已經存在,不知道測試命令怎麼跑,也不知道團隊約定哪些目錄不能碰。於是每次開新會話都要重新解釋專案背景,或者讓 Agent 反覆 grep、反覆讀檔案、反覆把無關內容塞進上下文。

這就是「程式碼庫記憶工具」要解決的問題。

不過這類工具不是同一種東西。CLAUDE.md、AGENTS.md 是規則檔案;Cursor 做的是 IDE 內索引;Serena 更像給 Agent 加一組語義程式碼工具;codebase-memory-mcp 走的是持久知識圖譜;RepoPrompt 偏人工上下文打包;Sourcegraph 則更適合企業級多倉庫程式碼理解。

先給結論

工具/路線 最適合 主要價值 不適合
CLAUDE.md / AGENTS.md 幾乎所有專案 保存專案規則、命令、禁區、協作約束 自動理解複雜呼叫關係
Cursor codebase indexing Cursor 使用者、IDE 內開發 讓聊天和編輯能引用目前專案索引 跨工具共享、複雜 Agent 編排
Serena MCP 大型程式碼庫、語義導航、重構 symbol 級檢索、引用查找、語義編輯 只想寫簡單提示詞的小專案
codebase-memory-mcp 多工具共享程式碼索引 透過 MCP 暴露持久程式碼知識圖譜 不想維護額外服務的使用者
RepoPrompt / RepoPrompt CE 需要人工精確控制上下文 選擇檔案、CodeMap、diff,組裝可審查上下文 想完全自動索引的團隊
Sourcegraph / Cody 企業多倉庫、大規模程式碼理解 集中索引、搜尋、權限、跨倉庫上下文 個人小專案、輕量本地工作流

我的建議:

  • 小專案:先寫 AGENTS.md 或 CLAUDE.md。
  • 中型專案:規則檔案 + IDE 索引。
  • 大型單倉庫:規則檔案 + Serena 或 codebase-memory-mcp。
  • 多倉庫團隊:規則檔案 + MCP 索引工具 + Sourcegraph 這類平台。
  • 高風險改動:再加 RepoPrompt 這類人工上下文打包工具,先讓人審上下文,再讓 Agent 動手。

不要一開始就堆滿工具。程式碼庫記憶的目標不是「讓 Agent 知道一切」,而是讓它在目前任務裡少猜、少讀錯、少浪費上下文。

先區分三種「記憶」

1. 規則記憶

代表:CLAUDE.md、AGENTS.md、GEMINI.md、README 裡的 AI section。

它們記錄技術棧、常用命令、測試方式、目錄說明、禁止修改的檔案、程式風格、提交和驗證規則。這種記憶最便宜也最穩定,缺點是不會自動理解程式碼關係。

2. 檢索記憶

代表:Cursor codebase indexing、Sourcegraph、程式碼搜尋、向量索引、知識圖譜。

它們回答:函式在哪裡定義、誰呼叫了介面、哪些檔案可能相關、某個設定在哪裡出現、跨倉庫依賴在哪裡。適合中大型程式碼庫,但需要索引、刷新、權限和忽略規則。

3. 操作記憶

代表:Serena MCP、帶語義編輯能力的 Agent 工具、程式碼智能 MCP server。

它們不只是找到程式碼,還提供更接近 IDE 的工具,例如查 symbol、查引用、看 outline、替換函式體、重命名 symbol、做更小粒度的編輯。適合複雜重構和大倉庫導航,但安裝和配置更複雜。

CLAUDE.md / AGENTS.md:最基礎,也最應該先做

如果一個專案沒有任何程式碼庫記憶,第一步不該是上複雜索引,而是先補一份專案規則檔案。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Project Guide

## Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Rules

- Prefer existing helpers in `src/lib`.
- Do not edit database migrations unless explicitly requested.
- Do not delete files without listing paths and waiting for confirmation.
- For UI changes, check mobile and desktop layouts.

這類檔案適合保存「專案怎麼做事」:用 pnpm 還是 npm、測試命令、哪些目錄是生成物、哪些檔案不能改、改 API 後要跑什麼檢查、AI 最後怎麼回報。

它的優勢是簡單、可提交到 Git、團隊共享、跨工具可讀。缺點是它不會告訴 Agent 函式在哪裡被呼叫。它是地基,不是完整程式碼索引。

站內這篇已經講過多專案記憶怎麼分層:/zh-tw/2026/07/08/claude-code-multi-project-memory-team-workflow/。

Cursor codebase indexing:適合 IDE 內閉環

Cursor 的 codebase indexing 更適合已經在 Cursor 裡日常開發的人。它會為目前程式碼庫建立索引,讓聊天、編輯和 @Codebase 這類上下文引用更容易命中相關檔案。

適合 IDE 內開發、在編輯器裡直接問功能位置、根據目前專案補程式、不想維護 MCP server、團隊主要都用 Cursor 的場景。

邊界也要清楚:索引主要服務 Cursor 內部工作流,跨工具共享有限;大倉庫要注意索引範圍和 ignore;不能只依賴它表達專案規則,仍然需要 AGENTS.md;生產設定、密鑰和生成物目錄要排除。

如果你已遇到 Claude Code token 暴漲、MCP 返回過多、上下文越來越亂,請記住:索引不是越多越好,真正有價值的是和目前任務相關的上下文。相關排查可看:Claude Code token 消耗突然變高原因:教程、排障和 FAQ。

Serena MCP:適合大程式碼庫的語義導航和重構

Serena 更接近「給 AI Agent 用的 IDE 能力」。它透過 MCP 提供語義程式碼檢索、編輯、重構和除錯工具。

它適合大型 Python、Java、TypeScript、Go 等程式碼庫;Agent 經常找錯函式、讀錯檔案;需要查 symbol、引用、宣告和實作;需要更安全地做跨檔重構;也適合讓 Claude Code、Codex、OpenCode、Gemini CLI 等 MCP 客戶端共享同一套工具。

Serena 的優勢在於 symbol 級操作。普通 Agent 常靠全文搜尋和行號編輯,複雜專案裡容易誤傷。語義工具能讓它更像 IDE 一樣工作。

如果只是寫小腳本、改單頁應用、一兩個檔案的 bug,普通搜尋和編輯已經夠用。MCP 本身排障可以看:。

codebase-memory-mcp:適合多工具共享持久程式碼記憶

DeusData/codebase-memory-mcp 會把程式碼庫索引成持久知識圖譜,再透過 MCP 提供給支援 MCP 的 Agent。

它適合同時使用 Claude Code、Codex、Cursor、Aider、OpenCode 等多個工具;希望多個 Agent 共享同一個程式碼索引;專案較大,Agent 經常重複讀同一批檔案;想減少上下文裡塞大量原始碼;想要本地化、可重複的程式碼查詢能力。

優勢是「持久」和「跨工具」。缺點是要維護安裝更新、索引刷新、MCP 配置、權限範圍、忽略規則和客戶端相容性。

如果只是偶爾讓 AI 改兩行程式,沒必要上它。如果每天在多個 Agent 之間切換,它會更有價值。站內已有單獨教程:/zh-tw/2026/06/22/codebase-memory-mcp-code-intelligence-guide/。

RepoPrompt:適合人工精確控制上下文

RepoPrompt 和 RepoPrompt CE 的思路不是讓系統自動讀完整倉庫,而是幫使用者組裝一份可審查的上下文。

它適合想明確控制模型看到哪些檔案、複雜需求前需要人工選關鍵檔案、擔心自動索引帶入無關內容、想把檔案、CodeMap、目錄結構、Git diff 一起交給 AI 的場景。高風險重構、架構評審、程式碼審查都適合。

穩定流程是:人先選入口檔案、相關模組和 diff;RepoPrompt 生成上下文包;AI 做設計、審查或修改建議;真正寫程式前再縮小範圍。

Sourcegraph:適合企業多倉庫

Sourcegraph 更偏企業級程式碼理解平台,強調大型程式碼庫和多倉庫環境的索引、搜尋、權限和程式碼演進控制。

它適合多倉庫企業團隊、大型 monorepo、跨服務遷移、需要權限/審計/SSO/集中搜尋、Agent 需要理解不止目前本地倉庫、安全合規要求高的組織。

個人開發者通常不需要一上來用 Sourcegraph。它的價值在規模。

不同專案怎麼選

個人小專案

1
2
3
AGENTS.md 或 CLAUDE.md
+ Git
+ IDE 內建搜尋

先寫清命令、目錄和禁區,再讓 Agent 小步修改。重點不是記住所有檔案,而是別用錯命令、別誤刪檔案、別改無關目錄。誤刪防護可以看:。

中型業務專案

1
2
3
AGENTS.md / CLAUDE.md
+ Cursor codebase indexing
+ 必要時加 Serena MCP

規則檔案負責穩定約束,IDE 索引負責日常問答,Serena 負責更複雜的語義導航。

大型單倉庫

1
2
3
4
AGENTS.md / CLAUDE.md
+ Serena MCP
+ codebase-memory-mcp
+ 分目錄說明檔案

大型單倉庫最怕 Agent 把整個專案當成一坨文字。應該按模組拆:根目錄寫全局規則,子目錄寫局部規則,MCP 工具查 symbol 和依賴,重要任務先做只讀影響面分析,修改時只改小範圍。

如果還會用 Claude Code subagent,可以把「程式碼檢索」和「專項審查」拆成不同角色:。

多倉庫團隊

1
2
3
4
5
每倉庫 AGENTS.md / CLAUDE.md
+ 團隊通用記憶
+ Sourcegraph 或企業程式碼搜尋平台
+ MCP 工具層
+ 權限和審計規則

多倉庫團隊最重要的是統一規則和權限。這時程式碼庫記憶已經不是個人效率工具,而是工程治理的一部分。

選型時看這 7 個問題

  1. 程式碼庫有多大?
  2. Agent 主要問題是「不知道規則」,還是「找不到程式碼關係」?
  3. 你只用一個 IDE,還是同時用 Codex、Claude Code、Cursor、Aider?
  4. 是否需要團隊共享同一份規則和索引?
  5. 是否有密鑰、生產設定、客戶資料等敏感檔案?
  6. 是否經常做跨檔重構和遷移?
  7. 你能接受維護額外 MCP server 或企業平台嗎?

規則混亂就先寫 AGENTS.md / CLAUDE.md。找不到程式碼就考慮 Cursor 索引、Serena 或 codebase-memory-mcp。多倉庫治理就考慮 Sourcegraph。高風險任務上下文要可審查,就考慮 RepoPrompt。

常見錯誤

把記憶檔案寫成專案百科

CLAUDE.md 和 AGENTS.md 不應該塞所有歷史背景,只寫會影響操作的穩定規則。

索引範圍太大

不要把這些目錄交給 Agent 當主要上下文:

1
2
3
4
5
6
7
8
9
node_modules/
dist/
build/
public/
.next/
.cache/
coverage/
logs/
tmp/

索引工具要配合 .gitignore、.cursorignore、工具自己的 ignore 檔或 MCP 配置使用。

把搜尋結果當事實

程式碼檢索只能說明「找到了一些相關內容」,不代表結論一定正確。Agent 仍然需要讀入口檔案、查呼叫鏈、看測試和設定、跑最小驗證並回報不確定性。

忘了權限和隱私

接入前要確認是否上傳程式碼、索引存在何處、是否共享、是否包含 .env 和客戶資料、MCP server 是否限制工作目錄、日誌是否會列印敏感內容。

工具太多,規則太少

先把規則寫清楚,再加索引工具。

推薦落地路線

  1. 給專案加一份簡短 AGENTS.md 或 CLAUDE.md。
  2. 寫清技術棧、命令、目錄、禁區和驗證方式。
  3. 配好 .gitignore、.cursorignore 或索引排除規則。
  4. 日常 IDE 開發先用 Cursor / 內建索引。
  5. Agent 經常找錯程式碼時,再加 Serena 或 codebase-memory-mcp。
  6. 高風險改動前,用 RepoPrompt 這類工具人工打包上下文。
  7. 多倉庫團隊再考慮 Sourcegraph 或企業程式碼搜尋平台。

code-review-graph、Claude.md 與 Codex Skills 如何組合

很多人說 AI Agent 需要「程式碼庫記憶」。 但這個詞太寬了。 有人想讓 Agent 記住專案規則。 有人想讓 Agent 找到函式呼叫鏈。 有人想讓 Agent 不要每次都重新掃描整個倉庫。 也有人想讓 Agent 自動執行固定的審查流程。

這四個問題聽起來相似,實際需要的工具完全不同。 Claude.md 和 AGENTS.md 更像專案規則文件。 code-review-graph 更像程式碼關係圖和審查輔助工具。 codebase-memory-mcp 更像跨工具共享的程式碼索引服務。 Codex Skills 更像可重用的工作流程說明書。

選錯之後,問題不是功能少一點,而是維護成本變高。 這篇文章不重複單一工具教學,而是做選型。

先說選型結論

小專案先用 AGENTS.md 或 Claude.md。 中型專案加 Codex Skills,把重複流程固定下來。 程式碼審查任務優先看 code-review-graph。 多工具共享程式碼索引時,再考慮 codebase-memory-mcp。

不要一開始就把四種都裝上。 更好的順序是:規則文件先行,流程沉澱第二,結構索引第三,MCP 服務最後。 如果你已經讀過 AI Agent 程式碼庫記憶工具對比,這篇可以作為更窄的實作選型表。

四類工具解決四類問題

工具 主要解決的問題 最適合場景 最大風險
Claude.md / AGENTS.md 專案規則和長期約束 小團隊、單倉庫、固定規範 寫太長,污染上下文
Codex Skills 重複任務流程 發布、翻譯、部署、SEO、審查 把沒跑順的流程固化
code-review-graph 呼叫關係和變更影響 PR 審查、架構影響分析 圖譜過期或排除目錄不準
codebase-memory-mcp 跨工具共享程式碼索引 多 Agent、多 IDE、大倉庫 服務權限和索引維護成本

這張表的重點是「主要解決的問題」。 它們不是同一種工具的四個品牌,而是四層能力。 規則層告訴 Agent 怎麼做。 流程層告訴 Agent 重複做什麼。 結構層告訴 Agent 程式碼之間怎麼連。 服務層讓不同 Agent 透過統一接口查同一份索引。

先判斷你缺的是哪種記憶

選工具前先問四個問題:

  • Agent 是忘了專案規範嗎?
  • Agent 是找不到相關程式碼嗎?
  • Agent 是每次都重複同一套步驟嗎?
  • Agent 是多個工具之間上下文不同步嗎?

如果只是忘了規範,寫 AGENTS.md 就夠了。 如果只是重複同一套工作流程,寫 Skill 更直接。 如果經常漏掉呼叫鏈和影響範圍,用程式碼圖譜。 如果 Codex、Claude Code、Cursor 都要查同一份結構化索引,再接 MCP。

不要因為「記憶」這個詞,就把所有工具混在一起。

Claude.md 和 AGENTS.md:專案規則層

Claude.md 和 AGENTS.md 的價值在於短。 它們應該告訴 Agent 穩定規則,而不是保存專案百科。

適合寫進去的內容包括:

  • 專案啟動命令。
  • 測試命令。
  • 程式碼風格。
  • 禁止修改的目錄。
  • 發布前檢查。
  • 常見陷阱。
  • 安全邊界。
  • 語言和文案要求。

不適合寫進去的內容包括:

  • 完整業務背景。
  • 過期討論記錄。
  • 每個模組的詳細說明。
  • 長篇設計文件。
  • 一次性任務日誌。
  • 沒驗證過的個人偏好。

好的規則文件應該像路標。 它提醒 Agent 不要走錯路。 它不應該變成一本厚手冊。 如果你想專門優化規則文件,可以繼續遵循 Claude.md 不是越長越好的原則。

Codex Skills:工作流程記憶層

Skill 不是程式碼索引。 它記住的是「做事方式」。

例如這個站點的新文章流程:

  • 判斷是不是新建文章。
  • 找到下一個編號。
  • 只建立 index.zh-cn.md。
  • 設定 front matter。
  • 控制發布日期。
  • 檢查行數。
  • 不生成其他語言。

這些步驟不適合每次都寫在提示詞裡。 它們適合沉澱成 Skill。

Skills 適合的任務

  • 內容發布流程。
  • 多語言翻譯流程。
  • 部署流程。
  • SEO 冷卻期檢查。
  • 本地重寫流程。
  • 安全檢查清單。
  • 固定格式報告。
  • 程式碼審查步驟。

Skills 不適合的任務

  • 單次問題排查。
  • 仍在摸索的流程。
  • 需要大量臨場判斷的任務。
  • 沒有穩定驗收標準的任務。
  • 只為了讓回答更長的提示詞集合。

Skill 最好的形態是「少解釋,多約束」。 它應該減少 Agent 犯固定錯誤的概率。 如果你想從零寫,可以看 Codex Skills 怎麼寫自己的工作流。

code-review-graph:變更影響層

code-review-graph 的重點不是讓 Agent 記住聊天記錄。 它更關注程式碼結構。 它用圖譜思路幫你回答:

  • 這個函式被誰呼叫?
  • 這個路由影響哪些模組?
  • 這個 PR 改了哪些呼叫鏈?
  • 哪些測試可能需要補?
  • 哪些文件應該一起審查?

這類問題靠普通提示詞很難穩定回答。 因為 Agent 如果只讀 diff,容易漏掉間接影響。 如果讓它全倉庫搜尋,又容易浪費上下文。

圖譜工具的價值就在這裡。 它把程式碼結構提前算好。 Agent 需要時再查。

code-review-graph 適合誰

  • 經常做 PR 審查的人。
  • 倉庫模組之間呼叫複雜的人。
  • 想讓 Codex 或 Claude Code 審查變更影響的人。
  • 不想每次都讓 Agent 掃全倉庫的人。
  • 想把審查流程接入 GitHub Actions 的團隊。

code-review-graph 不適合誰

  • 只有幾個文件的小腳本。
  • 沒有 PR 或 diff 流程。
  • 只想保存聊天記憶。
  • 不願維護索引生成結果。
  • 無法區分生成文件和源碼目錄。

如果你要上手,可以看 code-review-graph 怎麼用。 如果要接 CI,可以看 code-review-graph 接入 GitHub Actions。

codebase-memory-mcp:共享索引層

codebase-memory-mcp 更適合多工具環境。 如果你只用一個 Agent,未必需要它。

但如果你同時用 Codex、Claude Code、Cursor、Gemini CLI,問題會出現。 每個工具都有自己的上下文。 每個工具都可能重新掃描程式碼。 每個工具對專案結構的理解可能不一致。

這時 MCP 形式的程式碼索引就有價值。 它可以把程式碼庫結構作為服務暴露給不同 Agent。 Agent 不需要每次重新建立理解。

codebase-memory-mcp 適合的場景

  • 大倉庫。
  • 多語言倉庫。
  • 多個 Agent 共享同一專案。
  • 需要本地優先的程式碼索引。
  • 需要透過 MCP 統一接入。
  • 需要減少重複掃描成本。

使用前要想清楚

它是一個服務。 服務就有運行狀態。 服務就有端口、權限、索引目錄和升級問題。

如果團隊沒有人維護,這類工具很容易變成「裝過但沒人敢動」。 所以它適合已經有穩定 Agent 使用習慣的團隊。 不適合還在試用階段的人。 安裝教程可以看 codebase-memory-mcp 使用教程。

按倉庫規模選擇

倉庫規模會明顯影響選型。 一個腳本倉庫和大型單體倉庫,不應該用同一套記憶方案。

10 個文件以內

這類專案不需要複雜記憶。 建議只保留:

  • README.md。
  • AGENTS.md。
  • 基礎測試命令。
  • Git diff 審查。

如果 Agent 還找不到文件,問題通常不是工具少,而是任務描述太寬。

10 到 200 個文件

這類專案開始需要輕量結構說明。 建議增加:

  • 模組目錄說明。
  • 常用命令清單。
  • 一個開發或發布 Skill。
  • 必要時加 code-review-graph。

這時規則文件仍然要短。 不要把每個模組都寫進 AGENTS.md。

200 到 2000 個文件

這類專案開始出現影響範圍問題。 建議增加:

  • 呼叫關係圖譜。
  • 變更影響審查。
  • CI 中的最窄測試策略。
  • 團隊共享規則。
  • 忽略生成目錄的索引配置。

code-review-graph 在這一層更有價值。 它幫助 Agent 少靠猜。

多語言大倉庫

這類專案需要共享索引和服務化能力。 建議增加:

  • codebase-memory-mcp。
  • 統一 MCP 配置。
  • 索引更新策略。
  • 權限白名單。
  • 服務監控。
  • 版本升級記錄。

這時工具本身已經是基礎設施。 不能只靠個人習慣維護。

按任務類型選擇

不同任務對記憶的要求也不同。

修 Bug

修 Bug 最需要復現步驟和相關文件。 優先級是:

  • 錯誤日誌。
  • 復現命令。
  • 最近改動。
  • 相關測試。
  • 呼叫關係。

如果 Bug 很局部,不必上 MCP。 如果 Bug 跨模組,再用圖譜。

寫新功能

新功能最需要邊界。 優先級是:

  • 需求範圍。
  • 不改動範圍。
  • 資料結構。
  • API 契約。
  • 測試入口。

規則文件能防止 Agent 亂改架構。 Skill 可以保存固定實作流程。

程式碼審查

程式碼審查最需要變更影響。 優先級是:

  • diff。
  • 呼叫方。
  • 被呼叫方。
  • 路由入口。
  • 測試覆蓋。
  • 安全邊界。

這裡 code-review-graph 比長提示詞更合適。

文件和發布

文件和發布最需要流程記憶。 優先級是:

  • front matter。
  • 文件命名。
  • 構建規則。
  • 多語言同步。
  • 連結檢查。
  • 發布檢查。

這類任務更適合 Skills。

資料更新策略

程式碼庫記憶如果不更新,很快就會誤導 Agent。 不同工具的更新方式不同。

規則文件靠人工維護。 Skills 隨流程變化更新。 code-review-graph 需要在程式碼變更後重建或增量更新。 codebase-memory-mcp 需要維護索引服務和資料目錄。

什麼時候必須更新

  • 新增模組。
  • 刪除目錄。
  • 路由結構變化。
  • 測試命令變化。
  • 構建工具變化。
  • 程式碼生成目錄變化。
  • 團隊權限規則變化。
  • CI 流程變化。
  • Agent 工具升級。
  • MCP 服務升級。

更新後的驗收

  • Agent 能說明入口文件。
  • Agent 能找到相關測試。
  • Agent 不會掃描生成目錄。
  • Agent 能解釋一次真實 diff。
  • Agent 能遵守禁止修改範圍。
  • Agent 能正確呼叫 Skill。
  • MCP 查詢返回的是最新文件。
  • 圖譜結果和實際程式碼一致。

失敗案例和修復

規則文件太長

表現是 Agent 每次都讀得慢,還會引用無關規則。 修復方法是刪。 保留穩定約束。 把流程移到 Skill。 把背景移到文檔。

Skill 寫得太泛

表現是每種任務都套同一個流程。 修復方法是拆。 一個 Skill 只服務一類工作。 例如發布、翻譯、部署、審查分別寫。

圖譜沒有排除生成目錄

表現是 Agent 關注構建產物,而不是源碼。 修復方法是更新 ignore 配置。 把 dist/、public/、node_modules/、緩存目錄排除。

MCP 權限過大

表現是 Agent 能訪問太多不相關資源。 修復方法是分級。 只讀工具先行。 寫入工具單獨審批。 生產工具默認關閉。

四種工具可以怎麼組合

個人小專案建議:AGENTS.md、少量專案文檔、Git diff、最窄測試命令。 中型 Web 專案建議:AGENTS.md、一個發布或測試 Skill、code-review-graph、PR 審查模板。 多 Agent 團隊專案建議:AGENTS.md、團隊級 Skills、code-review-graph、codebase-memory-mcp、CI 審查、權限邊界文檔。 內容站和自動化工作流建議:發布 Skill、翻譯 Skill、SEO 冷卻期規則、部署 Skill、少量站點目錄說明。

這類組合的關鍵不是工具多。 關鍵是每一層解決的問題不重疊。

選型決策樹

先問:Agent 是否經常違反專案規則? 是,就寫 AGENTS.md 或 Claude.md。

Agent 是否經常重複同一套步驟? 是,就寫 Skill。

Agent 是否經常漏掉呼叫鏈或影響範圍? 是,就用 code-review-graph。

是否有多個 Agent 需要共享程式碼索引? 是,再考慮 codebase-memory-mcp。

否,先不要加工具。 這個順序能避免把簡單問題複雜化。

和已有文章怎麼串起來

這篇文章適合作為選型入口。 單工具安裝繼續交給已有文章。

code-review-graph 的具體命令看 7/99。 GitHub Actions 接入看 7/137。 codebase-memory-mcp 安裝看 6/113。 規則文件思想看 4/118。 通用記憶路線看 7/42。

這樣讀者不會在一篇文章裡被所有命令淹沒。 他們先選方向,再進入具體教程。

最終選擇建議

如果你只想讓 Agent 不犯固定錯誤,選 AGENTS.md 或 Claude.md。 如果你想讓 Agent 按固定流程辦事,選 Codex Skills。 如果你想讓 Agent 做變更影響分析,選 code-review-graph。 如果你想讓多個 Agent 共享程式碼結構,選 codebase-memory-mcp。

真正成熟的程式碼庫記憶,不是把所有東西都記住。 而是把規則、流程、結構和服務放到合適的位置。