它到底是什么

/add-dir 是 Claude Code 的会话内 slash 命令,用于在当前会话中动态追加额外工作目录,使 Claude 能够读取和操作这些目录中的文件。它与 CLI 启动标志 --add-dir 和 settings.json 中的 additionalDirectories 键共同构成 Claude Code 的多目录访问体系。

三种触达路径的核心区别:

怎么触发 / 怎么使用

1. 会话中添加单个目录

/add-dir /absolute/path/to/project

也可以用相对于当前工作目录的相对路径:

/add-dir ../shared-lib

如需添加多个目录,须多次执行,每次一条:

/add-dir ../frontend
/add-dir ../shared-types

注意:多次执行存在 append 失效 bug,详见下方"常见坑"第 1 条。

2. 启动时通过 CLI 标志指定(可一次传入多个)

claude --add-dir ../apps ../lib ../shared

3. 通过 settings.json 预配置(持久化,推荐团队统一使用)

见下方"保存 / 配置 / 集成"节。

保存 / 配置 / 集成

settings.local.json 自动写入

执行 /add-dir 后,Claude Code 会将路径写入项目级 .claude/settings.local.json:

{
  "permissions": {
    "additionalDirectories": ["/absolute/path/to/dir"]
  }
}

settings.local.json 通常不提交到 Git,适合本地私有配置。

手动预配置(可提交到 Git 的 settings.json)

直接编辑 .claude/settings.json:

{
  "permissions": {
    "additionalDirectories": [
      "../frontend",
      "../shared-lib",
      "/absolute/path/to/external"
    ]
  }
}

加载额外目录的 CLAUDE.md(需 opt-in,v2.1.20+)

从 v2.1.20 起,可选择让 Claude Code 同时加载额外目录中的 CLAUDE.md / CLAUDE.local.md:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude

不设置此变量时,额外目录只扩展文件访问权,不贡献 CLAUDE.md 记忆。

运行约束 / 限制

跟同类目录命令对比

/add-dir 与 /cd 都涉及"让会话访问别的目录",但语义完全不同——一个是额外挂载,一个是整体搬家:

简单记:想让 Claude 同时看到两个目录的代码用 /add-dir;想把整个会话连同 CLAUDE.md、项目存储搬到另一目录用 /cd。

经典使用场景

• Monorepo 跨包开发:在某个 package 中启动会话,用 /add-dir 挂载另一个 package,让 Claude 同时看到两侧代码。
• 前后端联调:后端 repo 中启动,用 --add-dir 挂载前端 repo,Claude 可理解接口契约的双端实现。
• 引用外部 shared types / proto 定义:访问独立维护的类型库或 schema 仓库,无需将其复制进当前 repo。
• 迁移参考:重构时引用旧 repo 作为对照,与新 repo 同时保持在上下文可见。

常见坑

1. /add-dir 会替换而非追加 additionalDirectories:在同一会话中多次执行 /add-dir 时,每次调用会覆盖整个 additionalDirectories 数组,只保留最后一条路径(GitHub issue #14097,报告于 v2.0.70)。绕过方式:在会话结束后手动编辑 .claude/settings.local.json,将所有路径一次性填入数组;或改用 --add-dir 启动标志一次性传入多个目录。

2. @ 文件提及的自动补全不覆盖额外目录:输入 @filename 时,下拉建议不会显示通过 /add-dir 添加的目录中的文件(GitHub issue #7412,版本 1.0.110,状态 open)。绕过方式:手动输入完整路径。

3. CLAUDE.md 加载在 settings.json + env var 组合下失效:当 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 与 settings.json 里的 additionalDirectories 同时使用时,额外目录的 CLAUDE.md 可能不被加载;改用 --add-dir 命令行参数传入时可正常加载(GitHub issue #22583)。

4. 目录已是工作目录时会给出明确提示(v2.1.193+):对一个已经是当前工作目录(或已挂载)的路径再执行 /add-dir,从 v2.1.193 起会返回更清晰的提示,而非默默无操作——便于辨认"为什么这次 /add-dir 没有新增目录"。来源:Claude Code changelog v2.1.193 "Improved /add-dir message when the directory is already a working directory"。

来源

• Commands — Claude Code Docs
• CLI reference — Claude Code Docs
• [DOCS] --add-dir can load CLAUDE.md from additional directories (new in 2.1.20, undocumented) · Issue #21138 · anthropics/claude-code
• [BUG] /add-dir replaces additionalDirectories instead of appending · Issue #14097 · anthropics/claude-code
• [BUG] @ mentions don't work with additional directories include via add-dir command · Issue #7412 · anthropics/claude-code
• CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD not loading CLAUDE.md if additionalDirectories is specified in settings.json · Issue #22583 · anthropics/claude-code
• Claude Code /add-dir: The Monorepo Command You Miss — Vincent's Blog