大代码库里如何管理上下文

在小项目里，可以把相关文件一次性塞给模型。但在真实的大代码库里，这种方式很快失效。问题不只是上下文窗口够不够大，而是模型到底有没有看到正确的上下文。

Mario 对这件事的判断很直接：Agent 的自主搜索召回率并不稳定。它会用 rg、find、grep 去找文件，也会顺着引用关系阅读代码，但在大代码库里，它很可能过早停止搜索，或者漏掉某个关键模块。最后它会基于不完整上下文写出一个看似合理、实际破坏边界的方案。

因此，大代码库要让 Agent 工作得好，首先要让代码库本身更 “agent-ready”。这意味着模块边界清晰、目录结构表达意图、文档能渐进披露、每个子系统的关键入口容易定位。理想情况下，某个任务只需要读一个模块或少数几个文件夹，而不是把全仓库都塞进上下文。

如果人已经了解代码库，最好的方式不是让 Agent 自己漫游，而是直接告诉它该看哪里。比如：“我要给 TUI 加鼠标支持，请先完整阅读 tui.ts，再告诉我改动方案。” 这比让 Agent 从仓库根目录盲搜更可靠。人类工程师对系统边界的记忆，本身就是一种高质量上下文索引。

如果人也不了解代码库，就不要马上让 Agent 实现。更好的做法是先让它探索：找相关文件、解释调用链、列出可能改动点、说明每个文件的职责。然后人根据这些结果继续追问，补充遗漏，直到自己对问题空间有基本理解。

Mario 在 Pi 里用“会话树”的方式处理这种探索。先开一个分析分支，让 Agent 大量读取代码、做探索、总结需要关注的文件和改动方向。等分析足够可靠，再把总结带到新的实现分支中。这样既保留了探索阶段的结论，又避免把大量临时上下文全部带进后续实现。

这和常见的 sub-agent 有点像，但更透明。很多 sub-agent 的问题是：它读了什么、漏了什么、为什么得出结论，主会话未必知道。它只返回一个最终摘要，人很难判断摘要是否建立在完整上下文上。Mario 更偏好亲自参与探索过程，因为这样可以随时追问、纠偏，并确认关键上下文已经被读到。

所以大代码库里的上下文管理，不是简单追求“更多 token”，而是追求“更准的上下文”。上下文不是模型的负担，而是人的责任。工程师越理解代码库，就越能给 Agent 精确导航；代码库越模块化，Agent 就越不容易迷路。

相关：AI Coding Agent 的两派：全自动黑箱 vs 人类主导、Agents、AI 编程时代的软件工程原则