Claude Code 處理大倉庫：怎麼讓它只看需要的目錄（子目錄 CLAUDE.md、claudeMdExcludes、deny 規則）

本文根據 Claude Code 官方《Set up Claude Code in a monorepo or large codebase》和《How Claude remembers your project》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

• 倉庫有幾十萬行代碼，或是 monorepo（一個倉庫裏很多個包）的開發者；
• 發現 Claude Code 老是讀和當前任務無關的文件，上下文很快被佔滿的人；
• 想讓團隊成員共用一套「只看相關部分」的配置的人。

結論先說

1. 官方的判斷是：Claude Code 能處理任意規模的倉庫，但為小項目調好的預設設定，在大倉庫裏會讓無關的指令和文件讀取塞滿上下文窗口，費 token 也拖累效果。
2. 第一步最簡單：在哪個目錄啟動。從子目錄啟動，只加載該目錄及各級上層的 CLAUDE.md；從根目錄啟動，只加載根目錄的，子目錄的按需加載。
3. 需要時再疊加：子目錄 CLAUDE.md、claudeMdExcludes、Read 的 deny 規則、代碼智能插件、worktree.sparsePaths、additionalDirectories。官方說這些設定彼此獨立、可以疊加。
4. 每一項都要分清是個人的還是提交到倉庫的：官方在每個小節都寫明瞭該放哪個文件。

圖：本站根據 Claude Code 官方《Set up Claude Code in a monorepo or large codebase》 整理的示意圖

一、先決定在哪個目錄啟動

啟動位置決定了三件事：不額外授權就能讀寫哪些文件、啟動時加載哪些 CLAUDE.md、適用哪份項目設定。官方給的對照是：

• 倉庫根目錄：能訪問所有文件；啟動時只加載根目錄的 CLAUDE.md，子目錄的按需加載。適合任務橫跨多個包。
• 某個子目錄：只能訪問該子樹，需要更多訪問權限要另行授予；加載該目錄和各級上層目錄的 CLAUDE.md。適合工作集中在一個包。

一個容易踩的點：.claude/settings.json 不會像 CLAUDE.md 那樣從父目錄繼承。你在 packages/api/ 啟動，就讀 packages/api/.claude/settings.json；每個子目錄的設定文件要寫得自成一體。具體哪個目錄的設定被讀取，官方指向《settings》頁的「where Claude Code looks for each file」一節。

二、給不同目錄各放一份 CLAUDE.md

根目錄一個文件寫全倉庫通用規則，每個包再放自己的。官方的示例很短：

根目錄 CLAUDE.md：

markdown
Run package scripts from the package directory, not the monorepo root.
Prefix commit subjects with the package name, for example `api: add rate limiting`.
Never edit files under packages/*/generated/. Run `npm run codegen` in the package instead.

packages/api/CLAUDE.md：

markdown
Copy `.env.example` to `.env` before running anything. Tests and the dev server fail without it.
Write database queries with the Knex query builder. Never put raw SQL strings in route handlers.
Never edit a migration after it has merged. Add a new migration instead.

在 packages/api/ 啟動，會同時加載這兩份，而 packages/web/ 裏的規則不會進入上下文。想確認加載了哪些，運行 /context all，看 Memory files 下的列表。每份寫什麼內容，參見 /guides/claude-code-claude-md-templates-frontend-backend-data。

官方還建議：把 CLAUDE.md 的改動當作普通文檔改動在 PR 裏評審；新一代模型發佈後回頭刪掉那些只為繞開舊模型缺陷而寫的規則；也可以加一個 Stop hook，在會話結束時讀取對話記錄並提出更新建議。

和 .claude/rules/ 裏帶 paths 的規則怎麼選：想讓各目錄的負責人自己維護、規則隨代碼走，用子目錄 CLAUDE.md；想所有規則集中在倉庫根的 .claude/ 裏，或同一條規則要用在很多分散的路徑，用 paths 規則。

三、用 claudeMdExcludes 跳過別人的 CLAUDE.md

從根目錄啟動時，其他團隊的包裏的 CLAUDE.md 也可能在會話中被按需加載。claudeMdExcludes 可以讓指定文件永遠不加載。官方建議個人使用時寫進 .claude/settings.local.json：

json
{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

規則是 glob，匹配的是絕對路徑，所以相對風格的模式要以 / 開頭。官方列的其他寫法："/packages//CLAUDE.md" 排除所有包的 CLAUDE.md 但保留根目錄的；"*/packages/legacy-/*" 排除名字以 legacy- 開頭的包（連帶規則文件）；也可以寫絕對路徑排除某一個文件。

兩點限制：它是靜態清單，不是按任務切換的開關，今天做 api、明天做 web，官方建議直接換目錄啟動而不是改排除項；另外，組織統一部署的託管 CLAUDE.md 不能被排除。

四、擋住生成物和第三方代碼

官方說明：Claude 的內容搜尋預設遵守 .gitignore，所以 node_modules/、dist/、build/ 這類已被忽略的路徑本來就不會出現在搜尋結果裏。需要額外處理的是已提交進倉庫的生成代碼或第三方 SDK，可以在 permissions.deny 裏加 Read 規則：

json
{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

官方特意把目錄寫成 /**/ 結尾而不是 /*，這樣規則只管目錄裏的內容，Claude 仍可以 ls dist 或 cd build。放在 .claude/settings.json 提交到倉庫，全團隊生效；放在 .claude/settings.local.json 只管你自己。

要注意邊界：官方說明 deny 規則覆蓋內置文件工具，以及 Bash 中 cat、head、grep、find 這類被識別的文件命令；對內置 Grep 和 Glob 工具是盡力排除。但 Bash 裏對包含被拒文件的目錄做 grep -r，輸出裏仍可能出現它們；自己打開文件的子進程也不在覆蓋範圍內。所以它是減少干擾的手段，不是安全邊界。想硬性防護可參考 /guides/claude-code-permission-modes。

五、少讀文件：代碼智能插件

在大倉庫裏查「這個函數定義在哪、誰在調用」，可能要讀很多文件、跑很多次 grep。官方的代碼智能插件讓 Claude 連接語言伺服器，直接跳轉定義、查引用。官方示例是在 claude 提示符裏安裝 TypeScript 插件：

text
/plugin install typescript-lsp@claude-plugins-official

官方列出兩種常見安裝失敗：提示 Marketplace "claude-plugins-official" not found，先用 /plugin marketplace add anthropics/claude-plugins-official 添加市場再重試；提示 Plugin "<name>" not found in marketplace "claude-plugins-official"，用 /plugin marketplace update claude-plugins-official 刷新目錄再重試。插件還要求你的機器上裝有該語言對應的語言伺服器程序，且從官方市場安裝需要能訪問 GitHub。插件的一般用法見 /guides/claude-code-plugins-marketplace。

六、worktree 只檢出需要的目錄

--worktree 會在新的 git worktree 裏開會話，預設檢出整個倉庫。大倉庫裏可以用 worktree.sparsePaths，藉助 git sparse-checkout 只寫入列出的目錄和根目錄下的文件：

json
{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

路徑相對倉庫根目錄；根目錄下的文件（如 package.json、鎖文件）總會被檢出，但根目錄下的目錄不會，所以想在 worktree 裏用到根目錄的 .claude/settings.json 或 .claude/rules/，要把 .claude 寫進去。symlinkDirectories 讓每個 worktree 的 node_modules/ 連結回主倉庫那份，避免重複佔用磁盤。官方還提醒：這些設定是在 worktree 創建前從你啟動的目錄讀取的，創建後會話的工作目錄是 worktree 根，所以 worktree 裏需要的權限規則、hook，要放在倉庫根目錄的 .claude/settings.json。worktree 的基礎用法見 /guides/claude-code-worktree。

七、從子目錄啟動又要改兄弟包

圖：本站根據 Claude Code 官方《Set up Claude Code in a monorepo or large codebase》 整理的示意圖

在 packages/api/ 啟動時，預設只能讀寫這個目錄。要改共享類型這類跨包的任務，有兩種授權方式：

json
{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

或啟動時臨時加：claude --add-dir ../shared。相對路徑從啟動目錄算起。官方列了一張差別表：用 additionalDirectories 設定添加的目錄，永遠不加載它的 CLAUDE.md、規則和技能；用 --add-dir 或 /add-dir 添加的目錄，技能會加載，CLAUDE.md 和規則需要再設環境變量 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 才加載。

八、一次改動跨多個包時

官方的兩條建議：把共享類型的修改和它的所有調用點放在同一個會話裏讓 Claude 一起完成，決策才能前後一致；改之前先進入計劃模式（見 /guides/claude-code-plan-mode），Claude 會把計劃寫進文件，長會話被壓縮上下文之後，Claude Code 會重新注入這份計劃文件。上下文壓縮的機制見 /guides/claude-code-context-compact。

常見問題

Q：Claude 還是老讀到我不想讓它讀的目錄？

先看是否已在 .gitignore 中；已提交的目錄用 Read deny 規則；注意 deny 對 Bash 裏的 grep -r 不是完全有效。

Q：設定寫了卻沒生效？

多半是放錯層級。項目的 settings.json 不繼承父目錄；worktree 裏讀的是 worktree 根目錄的那份。

Q：每次啟動都很慢、額度掉得快？

上下文裏無關內容越多，消耗越大。先按本文收窄範圍，再考慮額度問題，需要更高額度可以看 Claude Code 訂閱方案。

參考資料

• Claude Code 官方：Set up Claude Code in a monorepo or large codebase — https://code.claude.com/docs/en/large-codebases
• Claude Code 官方：How Claude remembers your project — https://code.claude.com/docs/en/memory