Claude Code 多項目、多目錄怎麼用：--add-dir、/add-dir 與 /cd 的區別，以及加進來的目錄哪些配置不生效

本文根據 Claude Code 官方文檔《Configure permissions》《CLI reference》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

• 項目拆成了多個文件夾（前端、後端、公共庫、文檔），想讓 Claude Code 同時讀寫的人；
• 加了目錄卻發現「它沒讀到那邊的 CLAUDE.md」「那邊的 Skill 沒生效」的人；
• 分不清 --add-dir、/add-dir 和 /cd 的人。

結論先說

1. 預設只能訪問啟動目錄。 官方說，Claude 預設可以訪問你啟動它的目錄裏的文件，這個目錄就是會話的主工作目錄。
2. 擴展訪問有三種方式： 啟動時用 --add-dir <路徑>；會話中用 /add-dir；想長期生效，在設定文件裏寫 permissions.additionalDirectories。
3. 附加目錄享受和主目錄同樣的權限規則。 讀文件不再逐個詢問，寫文件是否需要確認取決於當前權限模式。
4. 加目錄只是給文件訪問權，不是把它變成第二個項目。 官方明確說：大部分 .claude/ 配置不會從附加目錄被發現，只有少數例外。
5. 要把整個會話換到另一個項目，用 /cd，不是 /add-dir。 前者換主目錄並應用新目錄的配置，後者只是多開一扇門。

圖：本站根據 Claude Code 官方文檔：Permissions 整理的示意圖

一、三種加目錄的方式

假設你的項目是這樣放的：

text
work/
├── web/        # 前端
├── api/        # 後端
└── shared/     # 公共類型

方式一：啟動時加。 在 web 裏啟動，同時把另外兩個帶上。官方 CLI 參考裏的寫法是後面可以跟多個路徑：

bash
cd work/web
claude --add-dir ../api ../shared

官方說明 --add-dir 會校驗每個路徑必須是已存在的目錄。

方式二：會話裏加。 已經在對話中了，才發現還要讀另一個目錄，直接輸入：

text
/add-dir ../api

方式三：寫進設定，長期生效。 官方 CLI 參考說，想讓這些目錄跨會話保留，設定 permissions.additionalDirectories。示例（寫在 .claude/settings.json 裏，目錄名按你的實際情況改）：

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

注意官方的一個安全細節：項目裏 .claude/settings.json 的 additionalDirectories 是「授予能力」的配置，只有你接受了該文件夾的工作區信任對話框之後才會生效。所以剛克隆下來的陌生倉庫裏寫的目錄，不會在你沒確認的情況下被使用。

二、加進來的目錄，哪些配置生效

這是最容易踩的坑。官方的原話意思是：附加目錄讓 Claude 能讀寫文件，但不會讓它成為完整的配置根目錄。表格整理如下（來自官方 Permissions 頁面）：

兩個要點：

• Skill 能帶過來。 官方還給了命名規則：當附加目錄裏的 Skill 與已有的重名時，命令前面會加上該目錄的文件夾名，比如 --add-dir ../cli 的 verify 技能變成 /cli:verify（官方標註需要 v2.1.309 或更高）。
• 只寫在 permissions.additionalDirectories 裏的目錄，只給文件訪問，上面表格裏的例外都不適用。 官方特別說明，例外只針對用 --add-dir 標誌或 /add-dir 命令加的目錄。

所以如果你想讓後端目錄裏的 CLAUDE.md 也生效，有兩種做法：一是啟動前設定上面那個環境變量；二是把真正需要共享的規矩放進你當前項目的 CLAUDE.md。CLAUDE.md 本身怎麼寫，見 /guides/claude-md-agents-md。

三、/add-dir 和 /cd 到底差在哪

官方對 /cd 的描述：把會話移到另一個主工作目錄，保留對話，加載新目錄的 CLAUDE.md；如果你沒在那裏工作過，會提示你信任該工作區。移動之後，新目錄的這些東西立刻生效：

• 項目設定，包括權限規則和 Hooks；
• .mcp.json 裏的 MCP 伺服器（要經過同樣的審批）；
• 它的設定裏啟用的插件、Skill 和子智能體；
• 它的 env 值。

同時，舊目錄的項目級和本地級 MCP 伺服器會斷開。你用 --add-dir 或 /add-dir 加的目錄會保留。

一句話選擇：還在同一個任務裏，只是需要讀另一個目錄 → /add-dir；這個任務已經轉到另一個項目了 → /cd。 如果只是想一次改兩個倉庫，又要各自隔離，可以看 /guides/claude-code-worktree。

四、實戰提示詞

跨前後端改一個接口：

text
我在 web 目錄啟動，已經加了 ../api。請先讀 api 裏 /orders 接口的定義和 web 裏調用它的代碼，列出兩邊不一致的字段；
先不要改，給我一份改動清單（哪個文件、改什麼），我確認後再改。

讓它只讀不改附加目錄：

text
../shared 裏的類型定義只讀，不要修改它。需要新字段的話，把建議寫在回覆裏，我自己去改。

官方還提供了更硬的辦法：把 permissions.blockWritesOutsideWorkingDirectories 設為 true，讓 Write、Edit、NotebookEdit 工具拒絕向工作目錄之外寫入（官方標註需要 v2.1.314 或更高）。注意官方明確說它不限制 shell 命令、MCP 工具和 Hook 運行的程序，限制命令寫入要用沙箱，見 /guides/claude-code-sandbox-security。

圖：本站根據官方文檔整理的示意圖

五、常見問題

Q：能加網絡共享路徑嗎？

官方說大部分網絡路徑（例如 \\server\share）加不了，因為查找它可能聯絡它指向的主機。Windows 上的辦法是先把共享映射成盤符，再在啟動時傳盤符，比如映射到 Z: 就運行 claude --add-dir Z:\（PowerShell 裏）。其他 Windows 常見問題見 /guides/claude-code-windows-pitfalls-paths-git-bash-powershell。

Q：以前的會話還找得到嗎？

官方 CLI 參考說，--resume 的會話選擇器和名稱搜尋會包含添加過該目錄的會話。會話怎麼續接見 /guides/claude-code-resume-history。

Q：加了很多目錄，額度會更快用完嗎？

官方沒有對這一點給出數字。道理上，讀進來的文件越多，上下文佔用越多，所以提示詞裏最好寫明具體讀哪個目錄、哪幾個文件，而不是讓它全盤掃描。

Q：能用 --bare 模式嗎？

官方說 --bare 會跳過 Hook、Skill、插件、MCP、CLAUDE.md 等自動發現，但用 --add-dir 傳入的目錄裏的 Skill 仍會加載。

訂閱和額度

跨目錄讀寫會讓上下文變大，長期這樣用的話要留意額度。訂閱選擇見 /chongzhi/claude-code，價格和額度以官方頁面當前顯示為準。

相關教學

• /guides/claude-code-worktree：用 worktree 並行處理多個分支
• /guides/claude-code-settings-json：settings.json 怎麼寫
• /guides/claude-code-permission-modes：權限模式決定附加目錄能否直接寫

參考資料

• Claude Code 文檔：Configure permissions — https://code.claude.com/docs/en/permissions
• Claude Code 文檔：CLI reference — https://code.claude.com/docs/en/cli-reference