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

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

先區分三種「記憶」

1. 規則記憶

代表:CLAUDE.mdAGENTS.mdGEMINI.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.mdAGENTS.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.mdCLAUDE.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.mdAGENTS.md 更像專案規則文件。 code-review-graph 更像程式碼關係圖和審查輔助工具。 codebase-memory-mcp 更像跨工具共享的程式碼索引服務。 Codex Skills 更像可重用的工作流程說明書。

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

先說選型結論

小專案先用 AGENTS.mdClaude.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.mdAGENTS.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-graphcodebase-memory-mcp、CI 審查、權限邊界文檔。 內容站和自動化工作流建議:發布 Skill、翻譯 Skill、SEO 冷卻期規則、部署 Skill、少量站點目錄說明。

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

選型決策樹

先問:Agent 是否經常違反專案規則? 是,就寫 AGENTS.mdClaude.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.mdClaude.md。 如果你想讓 Agent 按固定流程辦事,選 Codex Skills。 如果你想讓 Agent 做變更影響分析,選 code-review-graph。 如果你想讓多個 Agent 共享程式碼結構,選 codebase-memory-mcp

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