很多人用 AI 编程工具改旧项目，一上来就说“帮我实现这个功能”。结果 AI 看了几个文件就开始改，表面进度很快，后面却容易出现三类问题：改错入口、漏掉旧逻辑、测试通过不了。
真正稳定的做法，是先把“代码阅读”变成一个固定流程。无论你用 Cursor、Claude Code 还是 Codex，都先让它回答：这个项目怎么运行、核心模块在哪里、数据从哪里来、改动会影响哪些旧功能。读懂之后再改，返工会少很多。
如果你正在系统学习这类工作流，可以先看 AI编程工具专题 和 老达AI实践专题，再把本文当作“改旧项目之前的阅读清单”。
第一步：先让 AI 画出项目地图
代码阅读的第一句话，不要问“这个项目讲讲看”，而是让 AI 输出结构化项目地图。比如：
请先只阅读项目结构，不修改文件。输出项目地图：主要目录职责、启动入口、配置文件、数据存储、测试目录、构建命令和可能的业务核心模块。对不确定的地方标注“待确认”。
这个提示的重点是“只阅读，不修改”。旧项目里经常有历史目录、废弃脚本、临时文件和生产配置。AI 如果没有先分层，很容易把示例文件当成真实入口，或者把旧版本逻辑当成当前流程。
项目地图至少要包含五类信息：运行入口、页面或接口入口、业务服务层、数据层、测试和部署脚本。对 WordPress、Node、Python、前端项目来说，这几类信息通常决定后续改动会碰到哪里。
第二步：沿着真实入口读一条链路
项目结构看完之后，不要马上全仓库总结。更有效的是选一条真实链路读到底。例如“用户提交表单后发生什么”“文章发布时经过哪些字段”“订单状态怎么从待支付变成已完成”。
可以这样让 AI 工作：
请沿着“用户提交表单”这条链路阅读代码：从路由、控制器、服务函数、数据库写入、异步任务到前端反馈逐步列出文件路径和关键函数。只输出链路，不提出改动。
这一步会让 Cursor、Claude Code、Codex 从“看文件”转向“看调用关系”。旧项目的风险通常不在单个函数里，而在隐性的调用顺序、默认值、状态流转和副作用里。
如果 AI 输出的链路里有“可能”“猜测”“应该是”，要让它继续查证。没有证据的总结只能作为线索，不能当作修改依据。
第三步：让 AI 找出修改边界
读懂链路之后，再让 AI 回答一个更具体的问题：如果要改这个需求，最小改动范围是什么？这一步可以参考我之前写的 AI编程需求文档怎么写，把目标、范围和验收条件先压实。
一个好的修改边界，应该包括：
- 必须修改的文件；
- 可能需要查看但不一定修改的文件；
- 不能随意改的公共模块；
- 需要补充或运行的测试；
- 上线后需要观察的指标或页面。
这比“给我一个实现方案”更实用。实现方案容易写得漂亮，修改边界才真正能控制风险。
第四步：让 AI 复述旧逻辑，而不是只写新逻辑
很多 AI 编程翻车，问题不在新代码，而在它没有理解旧逻辑为什么存在。比如一个看起来多余的判断，可能是为了解决老数据；一个重复字段，可能是兼容旧接口；一个奇怪的重试，可能是外部 API 不稳定。
动手前可以追加一条指令：
请复述当前旧逻辑的业务目的，列出你认为不能破坏的行为。如果有看起来可疑但不确定能否删除的代码，请只列为风险点，不要直接删除。
这一步适合改权限、支付、内容发布、自动化任务、数据库迁移这类高风险功能。尤其是多人维护过的项目，旧逻辑里经常藏着经验债。
第五步：把阅读结果变成验收清单
代码阅读不是为了产出一段总结，而是为了让后面的修改更可验收。修改前就应该得到一份小清单：改完要跑什么命令、打开哪些页面、检查哪些边界数据、是否需要人工确认。
这部分可以和 AI编程上线检查清单 连起来用。读代码时发现的关键链路，最后都要变成验收项。比如：
- 改表单提交，就检查必填项、重复提交、失败提示和数据落库；
- 改文章发布，就检查标题、摘要、SEO meta、特色图、标签和内链；
- 改登录权限，就检查普通用户、管理员、过期会话和无权限提示；
- 改性能问题，就检查改动前后的指标，而不是只看主观变快。
如果项目已有上下文管理问题，可以参考 AI编程上下文管理怎么做，把“必须读哪些文件、不该读哪些历史文件”写进项目规则里。
一套可直接复用的代码阅读提示词
下面这段可以直接丢给 AI 编程工具，适合改旧项目之前使用：
请先阅读项目，不要修改文件。按以下结构输出：1. 项目运行方式；2. 主要目录和职责；3. 与本需求相关的入口文件和调用链路；4. 关键数据结构和配置；5. 可能影响的旧功能；6. 建议的最小修改范围；7. 需要运行的测试和人工验收清单。所有不确定结论都标注为待确认，并说明需要继续查看哪个文件。
如果项目比较大，可以让 AI 分两轮做：第一轮只画地图，第二轮只读需求相关链路。不要一次要求它“读完整个项目并完成修改”，这类提示看起来省事，实际最容易丢上下文。
老达点评
AI 编程工具越强，越容易让人忽略“先理解再修改”这件事。真正拉开差距的不是谁能多生成几百行代码，而是谁能把旧项目的入口、依赖、风险和验收条件先讲清楚。
我的建议很简单：每次让 AI 改旧项目之前，先付出 10 分钟做代码阅读。读出来的项目地图、链路和验收清单，后面还能沉淀到项目规则里。这样 Cursor、Claude Code、Codex 才不只是代码生成器，而是可以长期协作的维护助手。
