多工作目录与 /add-dir 的使用边界

单仓库任务在当前工作目录内即可完成；当需要参考共享配置、相邻服务或组件库时，会涉及多个工作目录。本节讲清添加目录的方式、记忆文件的加载差异与跨目录操作的安全边界。

一、添加额外目录的两种入口

• 会话内使用 /add-dir 把额外目录纳入本次会话可访问范围。
• 启动时使用 --add-dir <路径> 指定额外目录，例如引入相邻的共享配置目录。

添加目录首先解决的是访问与读取范围；是否把这些目录的记忆文件也载入上下文，需要单独说明。

二、记忆文件默认不随额外目录加载

• 默认情况下，--add-dir 只开放目录访问，并不自动读取该目录下的 CLAUDE.md 等记忆文件，避免无关规范混入当前会话。
• 若希望额外目录的记忆一并加载，可设置环境变量 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1；开启后会加载该目录的 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md 与 CLAUDE.local.md（本地文件是否纳入还受设置来源选项影响）。
• 是否开启取决于协作关系：只读参考的第三方/相邻目录通常不加载其规则；共享团队规范的目录才需要载入。

三、典型适用场景

场景	建议做法
参考相邻服务的接口实现	只读添加目录做对照检索，改动仍限定在主仓库
跨仓库共享规范/组件库	必要时开启额外目录记忆加载，统一约定来源
大型 monorepo 局部工作	以子目录为工作起点，利用子目录规则按需加载；用排除设置忽略无关上级记忆
对比多个候选实现	独立会话/独立工作副本分别探索，避免改动互相污染

四、跨目录操作的安全边界

1. 先明确"主工作目录"与"参考目录"：默认写入、测试与提交应落在主目录，参考目录以只读为主。
2. 动手前让代理列出将读取/修改的路径清单，确认每个文件归属正确仓库，防止误改相邻项目。
3. 涉及共享目录的写操作（如公共组件修改）应单独评估、单独提交，并通知依赖方，不与本仓库改动混在一起。
4. 跨目录改动需要并行推进时，使用独立工作副本或独立会话隔离（见下一节），避免同一文件被多处同时修改。

五、跨目录任务的标准操作顺序

1. 定主从：先声明主工作目录（写入、测试、提交的落点）与参考目录（只读对照），避免写入归属不清。
2. 按需加目录：会话中用 /add-dir、启动时用 --add-dir <路径> 加入所需目录；先只开放访问，不急着加载对方规则。
3. 判断是否加载规则：共享团队规范目录才开启额外目录记忆加载；只读参考的相邻/第三方目录保持不加载，防止无关约定混入。
4. 先列路径清单：让代理列出将读取与可能修改的全部路径并标注所属仓库，人工确认无误后再写。
5. 写操作隔离：共享组件等跨库写入单独评估、单独提交；需要并行改动时用独立工作副本/独立会话，最后统一集成。

六、FAQ

问题	处理建议
加了目录但代理不读该目录的规范文件	默认不随访问加载记忆文件属预期行为；确需遵循其规则时再开启额外目录记忆加载环境变量，并确认来源可信。
误改到相邻仓库的文件怎么办	立即停止写入，用版本控制核对差异，回退误改；后续先以只读模式加目录、列出路径清单并把写入限定在主仓库。
monorepo 里上级记忆与子目录规则冲突	从具体子目录启动工作，利用子目录规则按需加载；用排除/忽略设置避免无关上级规范覆盖当前约定，冲突时以团队基线为准。
多个参考目录让上下文变臃肿	只加当前任务必需目录，检索交给只读子代理返回结论；任务结束后释放不再需要的目录。

七、动手练习

• 练习：在一个主仓库旁加入一个相邻只读参考目录，先不加载其规则完成一次对照检索与小修改；随后再对比"加载/不加载规则"两种情形下代理建议的差异，记录何时应当开启记忆加载。