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