接手陌生代码库,先读后改:让终端AI编程Agent只读列结构、跟主链路、标出不确定处,人逐项核实后再一次只改一处。
要点速览
- 接手陌生代码先读后改,接手当天不让AI动代码
- 只读阶段让Agent列目录、入口、依赖和配置
- 挑一条核心请求从入口跟到落库,人抽查三到五跳
- AI的解释当假设,用日志、断点、测试逐项核实
- 改动每次一处,看diff、跑测试、提交留回退点
接手一个陌生代码库,比较稳的做法是先读后改:让终端 AI 编程 Agent 在只读权限下帮你列出结构、跟出一条主链路、标出不确定的地方,人逐项核实之后,再一次只改一处。AI 在这个过程里负责阅读、整理和提示,某段逻辑到底是什么意思、能不能动、改完能不能合并,结论由工程师自己下。下面按四步展开,每一步都写清楚让 AI 做什么、人要核对什么。
为什么不建议一上来就让 AI 改代码
老项目难读,往往不是因为代码写得多复杂,而是因为里面藏着大量没有写进文档的约定:某个字段在历史上改过含义,某个函数被三处调用但只有一处还在用,某段看似多余的判断其实是为了绕开线上出过的问题。这些信息不在代码表面,AI 读到的也只是代码表面。
如果直接让 Agent 去改,它给出的修改往往在局部看起来合理,却可能碰坏某条隐性依赖。更麻烦的是,你自己还没看懂项目,就没有能力审查它给出的 diff,只能凭感觉放行。出了问题再回头查,花的时间通常比先读懂要多。
还有一层顾虑是代码本身属于公司资产。把整个仓库交给工具之前,应该先弄清楚代码会被发到哪里、调用有没有记录。这一点放在后文单独说。
所以顺序是:先只读理解,再画出主链路,然后验证理解,收尾时才动手改。
步骤一:划定只读范围,先看目录、入口、依赖和配置
这一步的目标是得到一张粗略的“项目地图”,不需要理解任何业务细节。给 Agent 的指令要明确两点:只读文件,不写入任何文件,不执行任何命令。如果工具支持权限设置,直接把写入和命令执行关掉,比靠指令约束更可靠。初次使用终端 Agent 的读者,可以参考AI编程Agent怎么用?初次在终端改代码先走哪四步里关于权限的部分。
可以让 Agent 分别整理以下几项:
- 目录结构:每个顶层目录大致放什么,哪些是业务代码、哪些是脚本、哪些是生成产物或第三方代码。
- 入口:程序从哪里启动,服务端的路由或接口定义在哪,定时任务和消息消费者在哪里注册。
- 依赖:依赖清单里有哪些主要框架和库,版本是否明显老旧,有没有私有包或本地路径引用。
- 配置:配置文件分几套环境,哪些值来自环境变量,数据库、缓存、外部服务的连接信息放在哪里(只记位置,不要把密钥内容输出到对话里)。
拿到结果后,人花十几分钟对照目录随手翻一翻,确认入口文件确实存在、配置文件确实在说的位置。这份地图不必完美,它的作用是让后面几步有个落脚点。建议把它存成一个 Markdown 文件放在自己的笔记里,后续每验证一处就更新一处。
步骤二:挑一条核心请求,从入口跟到落库
看懂别人的代码,不要试图一次读完整个项目,而是挑一条主链路跟到底。选哪条?优先选业务上最常发生、出问题影响面大的那条请求,比如电商项目里的下单、内部系统里的提交审批。
让 Agent 从这条请求的入口开始,一层层往下跟,产出一份调用链说明,要求写清每一跳的文件路径和函数名,以及这一跳做了什么:参数校验、权限判断、业务计算、调用外部服务、读写数据库或缓存。可以要求它用缩进文本或简单的时序描述“画”出来,比如“接口层 → 服务层 → 仓储层 → 某张表”,并在分叉处注明走哪条分支的条件。
人在这一步的工作是抽查。不需要每一跳都核对,但至少挑三到五跳,打开对应文件,确认函数确实存在、调用关系确实如此。重点看三类地方:
- 分支和条件判断,AI 容易只描述默认分支,漏掉特殊情况。
- 通过配置、反射、依赖注入或事件机制间接调用的地方,静态阅读容易跟丢。
- 事务和异常处理的边界,决定了出错时数据会停在什么状态。
如果抽查发现说明和代码对不上,不要只修正那一处,而是让 Agent 重新梳理那一段,并在说明里标注“已人工核对”或“待核对”。一条链路跟通之后,再读其他模块会快很多,因为大部分项目的分层方式是相通的。
步骤三:验证理解,把 AI 的解释当成待核实的假设
到这里你手上有一张地图和一条主链路说明,但它们仍然只是基于静态阅读的推断。这一步要把推断变成确认过的事实。
先让 Agent 主动列出它不确定的地方和缺失的文档:哪些函数的用途它只能猜测,哪些配置项看不出含义,哪些地方疑似废弃代码,哪些外部接口没有找到说明。这份清单往往比调用链说明本身更有价值,它直接告诉你哪里需要人去问、去试。
然后用运行时的证据逐项核实:
- 日志:在测试环境发起一次真实请求,看日志打印的顺序是否和调用链说明一致。
- 断点:在关键分支处打断点,确认实际走的是哪条路径、参数长什么样。
- 已有测试:找到覆盖这条链路的测试用例,读一读它断言了什么,跑一遍看是否通过。测试往往记录了原作者心里认为“正确”的行为。
- 问人:还能联系上前任维护者或业务方的,把清单里实在核实不了的几条拿去问。
核实的结果回写进项目地图,分成“已验证”和“未验证”两栏。原则只有一条:没有经过日志、断点、测试或人确认的解释,一律不当事实用。AI 的说明读起来通常很顺,这恰恰是需要警惕的地方。
步骤四:小范围改动,每次一处,留好 diff 和回退点
理解确认之后才进入修改。这时可以放开 Agent 的写入权限,但要控制节奏:
- 先建独立分支,不在主干上直接改。
- 每次只给 Agent 一个明确、范围小的任务,比如修一处边界判断、补一个缺失的空值处理。
- 改完逐行看 diff,确认它只动了你预期的文件和行,没有顺手“优化”别的地方。
- 跑相关测试,没有测试的先补一条再改。
- 每完成一处就提交一次,提交本身就是回退点。
Agent 需要执行的命令,尤其是涉及删除、安装依赖、改动数据库或推送远端的,应设置为人工确认后再执行。具体哪些地方需要自查,可以对照AI编程Agent安全吗?代码、命令、回退、模型出口四处自查。
架构层面的判断,比如要不要重构某个模块、要不要替换某个依赖,不交给 AI 拍板。它可以列出选项和各自的影响,决定和合并上线由工程师确认。
涉及公司代码时,工具和模型出口怎么安排
上面四步对工具的要求其实很朴素:能在终端里读仓库、能按指令输出结构化说明、权限可以收紧、命令执行可以要求确认。润迅的迅码 XunCode 就是这样一个终端 AI 编程 Agent,支持 macOS、Linux 和 Windows,个人可以免费使用,企业可以私有化部署。在这篇文章的场景里,它主要做的是读目录、跟调用链、列出不确定点,以及在你确认后做小范围修改。
个人项目随手用问题不大,但接手的是公司代码时,需要多想一步:代码片段会被发往哪个模型、谁在用、用了多少、有没有记录。企业场景下可以让 Agent 通过 MaxModel 接入模型。MaxModel 是润迅的模型统一管理平台,用一个 Key 接入所需的大模型,支持多模型路由,调用过程有审计记录,团队管理者能看清代码流向了哪里。具体的接入地址、Key 分发和日志怎么配,可以参考AI编程Agent接入公司大模型怎么配?四项配置逐个讲清。
需要说明的是,工具解决的是“读得快一些、整理得清楚一些”,不会替你理解业务。读懂一个项目的结论,仍然要靠人在日志、断点和测试里一条条确认。
行动建议:下次接手项目,从一条请求开始
- 接手当天不改代码,先用只读权限让 Agent 列出目录、入口、依赖和配置,存成一份项目地图。
- 挑一条业务上常发生的请求,让 Agent 从入口跟到落库,人抽查三到五跳。
- 让 Agent 列出不确定点和缺失文档,用日志、断点、测试逐项核实,分栏记录已验证和未验证。
- 确认理解后开分支,每次只改一处,看 diff、跑测试、提交留回退点。
- 如果代码属于公司,先和团队确认模型出口和调用记录的安排,再把仓库交给工具。
想在自己的终端里按这四步试一遍,可以先看迅码 XunCode的介绍,个人免费版足够完成只读梳理和小范围修改;团队需要私有化或统一模型接入,可拨打润迅业务热线 400-854-5566 咨询。
常见问题
接手别人的老项目,第一天应该做什么?
先不改代码。用只读方式梳理目录结构、程序入口、依赖清单和配置文件位置,整理成一份项目地图,再挑一条核心业务请求从入口跟到数据落库。读懂主链路之后,再考虑修改。
用AI看代码,它的解释能直接相信吗?
不建议直接相信。AI基于静态阅读给出的说明可能漏掉分支、跟丢间接调用。应让它列出不确定之处,再用日志、断点、已有测试或询问前任维护者逐项核实,未核实的解释不当事实用。
让AI编程Agent读公司代码会不会泄露?
关键看代码被发往哪个模型、调用有没有记录。企业场景下可以选择支持私有化部署的Agent,并通过统一的模型管理平台接入模型,用统一的Key管理并保留调用审计,接入前先和团队确认模型出口。
AI编程Agent改代码时怎么避免改坏?
开独立分支,每次只给一个范围小的任务,逐行检查diff是否只动了预期位置,跑相关测试,完成一处提交一次作为回退点。删除、安装依赖、推送等命令设置为人工确认后执行。
没有文档的项目怎么快速看懂代码逻辑?
不要通读全部代码,先选一条业务上常发生的请求,从入口跟到数据库,弄清每一层做了什么。同时找已有测试用例,测试的断言往往记录了原作者认为正确的行为,比注释更可靠。