Claude Code /add-dir 命令详解：多仓库协作的命门与避坑指南

Q: 第一步：从主项目启动

这段代码在做什么：进入主项目目录，启动 Claude Code 的交互式 REPL。这里有个细节要注意——你启动的那个目录会成为"根目录"，后续所有相对路径都基于它。这点后面踩坑环节会展开讲。

Q: 第三步：发起跨仓库任务

这才是 /add-dir 真正发力的地方。以前你要分三步做的事，现在一句话搞定： 我需要在主应用里新增一个"年度订阅"产品，价格 $99/年。请同时完成：1) 在 payment-core 里添加对应的 Stripe Price ID 配置；2) 在 i18n-content 里为 12 种语言添加 "annual_subscription" 这个 key 的翻译；3) 在 saas-web 的定价页面加上这个新档位的 UI。每改一个文件前告诉我你要改什么。 Claude 会真的把这三件事串起来做，而且会在 payment-core 改完之后，主动 import 进 saas-web 的代码里。这种跨仓库的一致性，是单目录模式根本做不到的。

Q: 第四步：用 --add-dir 启动参数预加载

如果你的项目永远是这三个目录一起用，每次手动敲 /add-dir 很烦。可以在启动时直接传： 这段代码在做什么：启动时就预加载好所有目录，省去进入 REPL 后再手动添加。这里有个细节要注意——--add-dir 启动参数接受绝对路径或相对路径，但 /add-dir 斜杠命令在 REPL 内部对相对路径的解析基准是你启动时的那个目录，不是你 cd 过去的目录。这个差异坑过我，下面细说。

Q: 大多数教程不告诉你的细节：.claudeignore 比你想象的重要

这是我交的最贵的学费。/add-dir 加进来的目录，默认会被 Claude 全量扫描。如果你的 payment-core 里有 node_modules、.next、dist，Claude 会傻乎乎地把这些都读一遍，瞬间把上下文窗口撑爆。 解决办法：在每个被 /add-dir 的目录根部，单独放一个 .claudeignore 文件： 这段代码在做什么：告诉 Claude 哪些路径根本不用看。这里有个细节要注意——.claudeignore 不会自动继承 .gitignore。我一开始以为 Claude 会复用 .gitignore，结果发现它该读还是读，token 烧得飞快。

Q: 坑一：相对路径的"基准目录陷阱"

时间：今年 3 月的某个周五晚上。 卡了多久：两个半小时。 我在 ~/projects/saas-web 启动了 Claude Code，加了 payment-core。然后我在终端的另一个 tab 里 cd ~/work/temp 干了点别的事。回到 Claude 的 REPL，敲： 我以为它会去 ~/work/temp/shared-utils 找，结果它去 ~/projects/saas-web/shared-utils 找了，告诉我目录不存在。 怎么发现的：我把路径打印出来让 Claude 自己确认 pwd，它返回的居然是 ~/projects/saas-web，跟我终端当前的 pwd 完全不一样。 怎么解决的：REPL 内部维护着自己的"当前工作目录"，跟你外部终端的 cd 没关系。要么用绝对路径，要么记住——/add-dir 的相对路径基准永远是你最初启动 Claude 时的那个目录。我现在的习惯是，多仓库项目一律用绝对路径，宁可多敲几个字符也不要赌。

Q: 坑二：跨目录的 Git 操作会"串台"

时间：四月初，一个出海项目要交付。 卡了多久：一小时，外加一次 force push 的心脏骤停。 我让 Claude 在 payment-core 里改一个 bug，改完顺手让它 commit。我说："帮我提交这个改动，commit message 写 'fix: stripe webhook signature verification'"。 它真的执行了 git commit，但是——它是在主目录 saas-web 里执行的。把 saas-web 里我还没改完的脏代码一起提交了。 怎么发现的：我习惯性地 git log 检查，发现 commit hash 出现在主仓库而不是 payment-core。当时心跳直接拉到 130。 怎么解决的：以后所有跨目录的 Git 操作，必须明确指定目录。给 Claude 的 prompt 要写成： 请在 ~/projects/payment-core 这个目录下执行 git commit，commit message 是 "fix: stripe webhook signature verification"。执行前先 cd 到该目录，并用 pwd 确认你在正确的位置。 啰嗦？啰嗦。但比 force push 强一万倍。

ivye
免费干货
13小时前
16热度
0评论

有一次，我在改一个出海 SaaS 的 Stripe 回调逻辑。主仓库在 ~/projects/saas-web，但支付的核心校验逻辑藏在另一个共享库 ~/libs/payment-core 里。我让 Claude 改一个 webhook 签名验证的 bug，它信誓旦旦地告诉我："文件已修改"。我去看——根本没动。

那一刻我才意识到，Claude Code 默认只能看到你启动它的那个目录。它不是骗你，它是真的"看不见"另一个仓库。

这就是 /add-dir 存在的意义。但官方文档把它写得跟"加个文件夹"一样轻描淡写，实际上它是 Claude Code 做多仓库、Monorepo、共享库协作的命门。今天聊聊这个被严重低估的命令，以及我踩过的两个让人血压飙升的坑。

为什么大多数人用不好 `/add-dir`

先说一个反常识的判断：90% 用 Claude Code 的人，都在单目录里硬撑。

不信你看身边的同事——主项目用 claude 启动，遇到要改共享库怎么办？退出，cd 到另一个目录，再 claude 一次。然后两边的上下文完全断裂，Claude 不知道你主项目里的类型定义，也不知道共享库里的接口签名。改出来的代码经常是"看起来对，跑起来崩"。

我自己也是这么干了大半年。直到做一个跨境电商的多语言落地页项目，主仓库是 Next.js 前端，国际化文案抽到了一个独立的 i18n-content 仓库（方便运营单独提 PR），支付逻辑又在 payment-core 里。三个仓库，三个 Claude Code 窗口，每次让它改个东西都得手动复制粘贴上下文。

后来我发现了 /add-dir，整个工作流直接重构。

说人话就是：/add-dir 让一个 Claude Code 会话能"同时看见"多个独立的 Git 仓库或目录，共享一个上下文窗口。这意味着它能理解跨仓库的依赖关系，能在改一个地方时主动提醒你另一个地方需要同步。

但前提是——你得会用。

从启动到多仓库协作的完整流程

我用一个真实的出海项目场景来演示。假设你的目录结构长这样：

~/projects/
├── saas-web/          # Next.js 主应用
├── payment-core/      # Stripe 封装库
└── i18n-content/      # 多语言文案仓库

第一步：从主项目启动

cd ~/projects/saas-web
claude

这段代码在做什么：进入主项目目录，启动 Claude Code 的交互式 REPL。这里有个细节要注意——你启动的那个目录会成为"根目录"，后续所有相对路径都基于它。这点后面踩坑环节会展开讲。

第二步：动态添加额外目录

进入 REPL 之后，敲：

/add-dir ../payment-core
/add-dir ../i18n-content

这两行命令把支付库和文案库都纳入了 Claude 的可见范围。现在它能读、能写、能创建这三个目录里的任何文件。

验证一下是否生效：

列出当前所有可访问的工作目录，并告诉我每个目录的主要用途（根据 README 或 package.json 推断）

Claude 会扫描所有已添加的目录，返回类似这样的结果：

1. ~/projects/saas-web (主目录) - Next.js 14 应用，出海 SaaS 前端
2. ~/projects/payment-core - Stripe 支付封装，支持多币种
3. ~/projects/i18n-content - 多语言 JSON 文案，支持 12 种语言

如果它没列全，说明 /add-dir 没生效，最常见的原因是路径写错——继续往下看坑。

第三步：发起跨仓库任务

这才是 /add-dir 真正发力的地方。以前你要分三步做的事，现在一句话搞定：

我需要在主应用里新增一个"年度订阅"产品，价格 $99/年。请同时完成：1) 在 payment-core 里添加对应的 Stripe Price ID 配置；2) 在 i18n-content 里为 12 种语言添加 "annual_subscription" 这个 key 的翻译；3) 在 saas-web 的定价页面加上这个新档位的 UI。每改一个文件前告诉我你要改什么。

Claude 会真的把这三件事串起来做，而且会在 payment-core 改完之后，主动 import 进 saas-web 的代码里。这种跨仓库的一致性，是单目录模式根本做不到的。

第四步：用 `--add-dir` 启动参数预加载

如果你的项目永远是这三个目录一起用，每次手动敲 /add-dir 很烦。可以在启动时直接传：

claude --add-dir ~/projects/payment-core --add-dir ~/projects/i18n-content

这段代码在做什么：启动时就预加载好所有目录，省去进入 REPL 后再手动添加。这里有个细节要注意——--add-dir 启动参数接受绝对路径或相对路径，但 /add-dir 斜杠命令在 REPL 内部对相对路径的解析基准是你启动时的那个目录，不是你 cd 过去的目录。这个差异坑过我，下面细说。

大多数教程不告诉你的细节：`.claudeignore` 比你想象的重要

这是我交的最贵的学费。/add-dir 加进来的目录，默认会被 Claude 全量扫描。如果你的 payment-core 里有 node_modules、.next、dist，Claude 会傻乎乎地把这些都读一遍，瞬间把上下文窗口撑爆。

解决办法：在每个被 /add-dir 的目录根部，单独放一个 .claudeignore 文件：

node_modules/
.next/
dist/
*.log
.env*
coverage/

这段代码在做什么：告诉 Claude 哪些路径根本不用看。这里有个细节要注意——.claudeignore 不会自动继承 .gitignore。我一开始以为 Claude 会复用 .gitignore，结果发现它该读还是读，token 烧得飞快。

两个真实的坑，让我血压飙升

坑一：相对路径的"基准目录陷阱"

时间：今年 3 月的某个周五晚上。卡了多久：两个半小时。

我在 ~/projects/saas-web 启动了 Claude Code，加了 payment-core。然后我在终端的另一个 tab 里 cd ~/work/temp 干了点别的事。回到 Claude 的 REPL，敲：

/add-dir ./shared-utils

我以为它会去 ~/work/temp/shared-utils 找，结果它去 ~/projects/saas-web/shared-utils 找了，告诉我目录不存在。

怎么发现的：我把路径打印出来让 Claude 自己确认 pwd，它返回的居然是 ~/projects/saas-web，跟我终端当前的 pwd 完全不一样。

怎么解决的：REPL 内部维护着自己的"当前工作目录"，跟你外部终端的 cd 没关系。要么用绝对路径，要么记住——/add-dir 的相对路径基准永远是你最初启动 Claude 时的那个目录。我现在的习惯是，多仓库项目一律用绝对路径，宁可多敲几个字符也不要赌。

坑二：跨目录的 Git 操作会"串台"

时间：四月初，一个出海项目要交付。卡了多久：一小时，外加一次 force push 的心脏骤停。

我让 Claude 在 payment-core 里改一个 bug，改完顺手让它 commit。我说："帮我提交这个改动，commit message 写 'fix: stripe webhook signature verification'"。

它真的执行了 git commit，但是——它是在主目录 saas-web 里执行的。把 saas-web 里我还没改完的脏代码一起提交了。

怎么发现的：我习惯性地 git log 检查，发现 commit hash 出现在主仓库而不是 payment-core。当时心跳直接拉到 130。

怎么解决的：以后所有跨目录的 Git 操作，必须明确指定目录。给 Claude 的 prompt 要写成：

请在 ~/projects/payment-core 这个目录下执行 git commit，commit message 是 "fix: stripe webhook signature verification"。执行前先 cd 到该目录，并用 pwd 确认你在正确的位置。

啰嗦？啰嗦。但比 force push 强一万倍。

一句话记住 `/add-dir`

/add-dir 不是给 Claude 加个文件夹，是给你的脑子省一次上下文切换。 工具的价值不在于功能多，而在于它有没有让你少做一次"把信息从 A 搬到 B"的搬运工。

最后一个值得认真想的问题： 你在用 Claude Code 做多仓库项目时，是把所有相关仓库都 /add-dir 进来一把梭，还是按任务粒度只加当前需要的那一两个？这两种策略对上下文窗口的消耗、对 Claude 输出质量的影响，你实测过吗？欢迎在评论区聊聊你的取舍标准。

FAQ

Claude Code 的 /add-dir 命令支持添加远程仓库吗？

不支持。/add-dir 只能添加本地文件系统中的目录，不支持直接添加远程 Git 仓库。你需要先将远程仓库克隆到本地，再用 /add-dir 添加。

/add-dir 添加的目录数量有限制吗？

没有硬性数量限制，但受限于 Claude Code 的上下文窗口（截至 2025 年，标准上下文约 100K token）。添加过多目录可能导致 token 耗尽，影响输出质量。建议按需添加，并用 .claudeignore 排除无关文件。

/add-dir 和 --add-dir 启动参数有什么区别？

/add-dir 是 REPL 内部的斜杠命令，用于在会话中动态添加目录；--add-dir 是启动参数，在启动 Claude Code 时预加载目录。两者效果相同，但 --add-dir 适合固定工作流，/add-dir 适合临时需求。