大型单仓库（monorepo）包含多个包/工作区、共享依赖与公共组件。代理在这种规模下的核心矛盾是：仓库很大，但每个任务只关心其中一小块。本章讲如何用记忆分层、只读探索与改动隔离，把大型仓库拆成可安全处理的局部问题。
一、先认识规模带来的四个代理挑战
| 挑战 | 后果 | 应对方向 |
|---|
| 公共代码被多包复用 | 局部改动可能波及大量下游 | 先画受影响面，再决定改动位置 |
| 规则与约定分散 | 根目录规则过粗、子包各有约定 | 按目录/类型分层作用域规则 |
| 上下文易被无关文件占满 | 信号密度下降、重复探索 | 只读子代理调研、按需加载记忆 |
| 并行开发易撞公共文件 | 冲突增多、集成成本上升 | 工作副本隔离 + 明确变更边界 |
二、记忆与规则的分层布局
- 仓库根 CLAUDE.md 只放全局事实：整体用途、技术栈、公共命令、跨包约定与禁止事项；不堆砌单个包的细节。
- 各包/子目录放置各自 CLAUDE.md：描述该包职责、内部结构与构建方式；这类文件按需加载，只在代理接触到对应目录时进入上下文，从而控制启动体积。
- 把按文件类型或路径生效的规则放到作用域规则目录（
.claude/rules/ 一类），让规则跟随相关文件出现，而非全部常驻主上下文。
- 对与当前任务无关的上级/邻近包，使用排除设置或不加载其记忆的方式，避免无关约定误导判断；共享规范通过明确引用而非全量注入。
三、先探索建模，再动代码
- 用只读的 Explore/Plan 类子代理按目标范围调研：列出相关包、公共依赖、调用链与测试位置，返回精简影响清单，而非把大段源码塞进主会话。
- 在计划模式下产出改动方案：确认改公共包还是改调用方、需要联动哪些下游包、回归范围多大。
- 建立最小验收基线：确认可用的构建、测试与静态检查命令；先让现有检查跑通，再开始修改。
四、改动隔离、提交粒度与集成
- 不同子任务用独立工作副本/并行会话推进，避免多人代理同时修改同一公共文件；职责边界按包或按主题切清。
- 提交保持小而内聚：单个包修复一个提交；公共契约、依赖与工具链的变更单独提交并写明影响面。
- 公共包变更先评估下游兼容：新增能力优于删除/改签名；破坏性改动同步更新所有调用点与说明。
- 集成阶段统一跑全仓相关测试与构建，确认并行副本合并后无交叉回归；冲突回到对应会话解决，不在合并现场即兴修补。
五、大型仓库常见反模式
- 让代理在主会话通读整仓、整文件粘贴：既浪费上下文也容易遗漏调用点。
- 把所有约定堆在一个根记忆文件里：规则互相覆盖、体积膨胀、遵循度下降。
- 修改共享组件却不排查下游：造成隐式耦合导致的跨包回归。
- 并行改动无工作副本隔离：同一文件被重复覆盖，合并困难。
本节小结与下一节预告
本节给出 monorepo 的记忆分层、探索顺序与隔离策略。下一节转向多服务协作：跨服务契约兼容、并行实现与发布协调。