陌生仓库的高效探索方法

进入陌生代码库时，先建立可验证的心智模型，再下达修改任务，是避免盲改、返工和越界的前提。本节给出从入口到链路、从静态结构到验证入口的探索顺序，以及如何让代理带着问题清单做只读探索并产出可供决策的结论。

一、仓库探索的五个层次

层次	重点看什么	应得出的结论
目录与依赖入口	顶层目录职责划分、依赖清单与构建配置位置	项目由哪些模块构成、技术栈与构建方式
启动与入口流程	程序如何启动、主流程如何串起来	一次请求或一次操作的主链路起点与流向
核心模块职责	关键目录/类/函数分别负责什么、彼此依赖方向	改动目标落在哪个模块、影响哪些相邻模块
调用关系与数据流	关键函数被谁调用、数据在模块间如何传递与转换	修改一处会沿调用链波及哪些位置
测试与验证入口	测试目录、运行命令、配置与环境前提	如何在改动前建立可重复的验证基线

二、如何下达只读探索任务

1. 限定探索姿态：明确本轮只阅读与汇总、不修改文件，配合保守的只读起步姿态，先看清再谈动手。
2. 给出问题清单：列出本次必须回答的具体问题，如"认证逻辑在哪一层""超时参数在哪里定义""哪些测试覆盖该模块"。
3. 要求结构化输出：让结论包含模块分工、关键调用链、目标位置、风险关联与可用验证命令，而非零散片段。
4. 定位而非贴全文：要求给出文件与符号位置并做摘要，便于人工定点复核，而不是大段粘贴源码。
5. 先基线再探索：开始前用 git status 确认工作区干净，避免把他人未提交改动混入判断。

三、探索阶段常见误区

误区	后果	正确做法
还没摸清就让全库大改	误判依赖关系、改动面失控	先只读探索、输出结论，确认后再定小任务
不找测试/构建入口就动手	无法自证改动有效，问题滞后暴露	探索阶段先定位可运行的验证手段并跑通基线
仅凭文件名猜测职责	结论与真实实现不符	结合调用关系、注释与测试交叉确认
一次探索覆盖所有模块	结论浅、重点散	围绕本轮目标做定向探索，其余按需深入
探索结论不沉淀就改代码	多轮后遗忘上下文、重复探索	把关键位置与约定写进后续任务或项目指令

四、从探索结论到首个改动

• 结论转任务清单：把"目标位置—影响范围—验证方式"转成一到两个小而独立的修改任务。
• 先易后难、先外围后核心：从低风险、易验证的点切入，熟悉改动与验证节奏后再碰核心链路。
• 明确改动边界：在任务中写清本次涉及的目录与不应触碰的模块。
• 结论存疑先核实：探索结论若与实际行为不符，先补查再修改，不靠猜测补齐证据。

五、FAQ

问题	处理建议
仓库很大如何避免探索耗时过长	按问题清单定向检索关键入口与符号，先画出主线，不必首轮通读全部文件。
探索结果太长要不要全看	重点复核目标位置、调用链结论与验证命令是否准确，其余摘要可按需深入。
没有现成测试怎么建立基线	先跑通构建与关键路径的手工复现步骤，记录现状行为，再开始改动。
代理探索结论与实际不符	把出入点作为新问题回贴，要求定位证据位置后再下结论。

六、动手练习

• 练习：选一个自己不熟悉的项目，按五层次列探索问题清单，让代理只输出"模块分工+关键链路+目标位置+验证命令"四段结论，再据此写出第一个最小改动任务。