让代理高效摸清陌生代码库

面对陌生代码库，最容易犯的错误是"没看懂就动手"。高效协作的第一步是让代理先做只读调研、建立心智模型，输出模块地图与待确认问题，再进入修改。本节给出探索顺序、提问清单和常见误区。

一、先建立心智模型，再谈修改

心智模型至少回答五个问题：程序从哪里启动、目录如何分工、核心数据结构在哪定义、关键功能的调用路径是什么、测试与配置分别在哪里。模型不清时直接改代码，容易出现改了实现漏了调用方、改动与既有约定冲突等问题。可先按 Shift+Tab 切换到计划模式，让代理只读调研、给出方案而不修改代码，确认理解一致后再进入实现。

二、推荐探索顺序（先宽后窄）

顺序	看什么	目标产出
1 入口与说明	项目说明、启动入口、主流程文件	程序如何启动、主流程走向
2 目录结构	高层目录职责、源码/测试/配置/文档分布	模块地图初稿
3 依赖与配置	依赖清单、环境与构建配置、关键环境变量用途	运行前提与外部依赖
4 核心模块与调用链	目标功能从入口到实现经过的文件与函数	调用关系与关键抽象
5 测试组织	测试目录、覆盖重点、运行方式	可用于回归验证的测试基线

三、引导探索的提问清单

• "功能 X 的入口在哪个文件？从入口到核心实现依次经过哪些函数？"
• "核心数据结构/类型定义在哪里？被哪些模块读写？"
• "某配置项从哪里读取、如何影响行为？"
• "现有测试覆盖了哪些路径？哪些关键行为还没有测试？"
• "列出与本次改动相关的文件清单和依赖关系，先不要修改代码。"

这些问题以只读检索为主，让代理定位文件、符号与调用关系，避免把整份源码塞进对话造成上下文浪费。

四、探索阶段的产出物

• 模块地图：目录/文件职责、关键抽象、入口与主要调用路径的简要说明。
• 影响范围清单：与目标改动相关的文件、调用方和测试位置。
• 待确认问题：需求不明、约定冲突或多种实现取舍之处，先与人对齐。
• 验证基线：当前测试与构建是否通过、关键行为样例是什么。

五、常见误区

误区	后果	正确做法
未理解就直接改	破坏隐含约定、反复返工	先只读调研并确认计划
要求通读全库	上下文臃肿、重点丢失	按目标功能定向检索调用链
只看单个实现文件	漏掉调用方与依赖	同时梳理定义处与所有使用处
边探索边修改	调研结论被未经验证的改动污染	调研与修改分阶段进行

六、用好只读探索子代理（Explore）

大型仓库中，让只读子代理先跑调研，能避免主会话被大量源码挤占上下文。内置探索类子代理的特点是只读、禁用写操作、按需调整调研深入程度，且调研结果以精炼结论回传、不把原始内容灌入主上下文；计划类子代理只做只读研究并产出方案，通用型子代理才具备完整工具能力。使用要点：

• 任务描述限定"只调研、不改文件"，明确要求输出模块地图、关键文件路径、调用链与待确认问题四类结论。
• 按需选择调研深入档位：快速定位用浅档，跨模块调用链用更深入的档位；避免对小型项目过度展开。
• 把探索结论作为后续实现的输入文档，主会话据此指挥小步修改，而不是让探索代理直接动笔。
• 探索结论存疑时回到源码核对关键路径；子代理摘要用于建立方向，关键改动仍以实际文件与测试为准。

七、探索阶段 FAQ

问题	处理建议
仓库很大，代理一开始就读取很多文件导致上下文紧张	先只问入口、目录职责与目标功能调用链；按"入口 → 核心实现 → 测试"逐层定向检索，不要求通读全库；必要时用只读子代理分担检索。
代理给出的模块地图与实际不符	让它指出每个结论对应的文件与行级依据；对存疑路径用只读检索复核后再修改，防止基于错误认知改代码。
找不到功能入口/关键配置	从启动说明、依赖声明、配置读取点与测试用例四侧交叉定位；测试用例往往最接近真实调用入口。
多人/多目录项目里只看到当前目录	若工作区包含多个相关目录，用 /add-dir 纳入额外工作目录后再探索；注意额外目录的项目记忆默认不会自动加载（详见第 9、11 章）。
探索完直接进入修改导致改漏调用方	先产出"定义处 + 全部使用处 + 相关测试"清单，确认无遗漏后再动手；修改与调研分阶段。

八、动手练习

• 练习 1：选一个不熟悉的开源项目，只用只读方式产出一份不超过一页的模块地图（入口、目录职责、核心数据流、测试位置、3 个待确认问题），不写任何修改。
• 练习 2：针对一个目标函数，列出其定义文件、所有调用点、读写的核心数据结构与对应测试；对照真实代码检查清单是否完整，复盘漏掉了哪一类位置。