用 AI 读懂和修改已有项目代码

结论先说：面对陌生项目，先让 AI 只读不改，依次回答“项目是做什么的、怎么跑起来、目录怎么分工、某个功能从哪里进到哪里出”；理解之后再让它 小步修改，每一步都用运行结果、测试和 git diff 验证。AI 读代码很快，但它的解释也可能是猜的，关键结论要回到代码里确认。

阶段	目标	AI 是否改文件
1. 准备	隔离环境，能随时回退	否
2. 建立项目地图	知道整体结构和运行方式	否
3. 追踪一个功能	理解具体代码路径	否
4. 定位问题	找到要改的位置	否
5. 小步修改	完成改动	是
6. 验证	确认改对、没改坏别的	运行命令

1. 准备

工具

能读取整个项目、搜索文件、运行命令的编程代理最适合这个任务，例如 Claude Code、Codex；在 Cursor 或装有 GitHub Copilot 的编辑器中，用其对话或代理模式也可以完成。安装与账号准备见 AI 编程工具入门。

开始前的检查清单

准备项	为什么
项目在 Git 仓库中，工作区干净（git status 无未提交修改）	随时能回退 AI 的修改
新建一个分支：git switch -c ai-explore	不影响主分支
确认没有明文密钥文件会被读取	例如 .env，必要时先移出或在工具设置中排除
确认公司是否允许把代码交给第三方 AI 服务	部分单位对源代码外发有规定
先自己尝试按 README 运行一次	知道项目原本能否跑起来

关于权限

编程代理会请求读取文件和运行命令的权限。理解阶段只需要读取和搜索，遇到安装依赖、修改配置、删除文件、访问网络的命令，先看清再允许。

2. 第一步：建立项目地图

在项目根目录启动工具，第一个问题：

我刚接手这个项目，请只阅读、不要修改任何文件。帮我回答：
1. 这个项目是做什么的？面向谁？
2. 用了什么语言、框架和主要依赖？
3. 怎么在本地安装依赖、运行和测试？请给出具体命令，并注明命令来自哪个文件；
4. 顶层目录各自负责什么？用表格列出；
5. 程序的入口文件在哪里？
如果某项无法从代码中确定，请直接说明，不要猜。

拿到回答后：

• 核对运行命令：亲自按它给的命令运行一次。跑不起来时，把完整报错贴回去让它分析；
• 核对来源：它说“来自 package.json”的命令，打开文件看一眼是否真的存在；
• 保存地图：让它把结果写成一份笔记（例如 docs/项目地图.md），或你自己保存下来，后续对话可以直接引用。

很多工具支持项目级说明文件，把运行命令、目录约定、代码风格写进去，之后每次对话都会自动读取，相关用法见各工具介绍页。

3. 第二步：追踪一个具体功能

整体结构只能帮你“知道在哪”，真正理解要靠追踪一条完整的路径。选一个你关心的功能，例如“用户点击导出按钮后生成 CSV 文件”：

请追踪“点击导出按钮生成 CSV”这个功能的完整代码路径：
1. 从界面上的按钮开始，到文件生成结束，按调用顺序列出经过的文件和函数；
2. 每一步写明：文件路径、函数名、行号、这一步做了什么；
3. 数据在哪一步被读取、转换和写出；
4. 有哪些分支或错误处理会让流程中途结束。
只阅读，不要修改。

核验方法：按它给出的文件和行号，在编辑器中逐个打开，确认函数确实存在、调用关系确实如此。AI 有时会把名字相近的函数混为一谈，或描述一个“应该存在”但实际没有的调用。

看不懂某段代码时，单独问：

请逐行解释 src/export/csv.ts 第 40–75 行在做什么，
特别说明其中的正则表达式和异步处理，用新手能懂的话。

4. 第三步：定位问题

假设用户反馈“导出的 CSV 用 Excel 打开中文乱码”。先让 AI 分析，不急着改：

用户反馈：导出的 CSV 用 Excel 打开时中文显示乱码，用文本编辑器打开正常。
请根据上面追踪到的代码路径分析可能原因：
1. 列出 2–3 个最可能的原因，按可能性排序；
2. 每个原因对应哪段代码，引用文件路径和行号；
3. 我可以用什么方法验证是哪个原因（例如运行什么命令、看什么输出）。
暂时不要修改代码。

按它建议的验证方法亲自确认原因，再进入修改。跳过验证直接改，最容易出现“改了一处，问题没解决，还引入新问题”。

5. 第四步：小步修改

已确认原因是导出文件缺少 UTF-8 BOM。请修改，要求：
1. 先说明打算改哪些文件、每处改什么，等我确认；
2. 只做解决这个问题所需的最小改动，不要顺手重构或调整格式；
3. 如果项目有测试，为这个问题补充一个测试用例；
4. 改完后运行相关测试并告诉我结果。

几条值得坚持的规则：

规则	原因
先说计划再动手	及早发现方向错误
要求“最小改动”	AI 倾向于顺手修改无关代码，增加审查难度
一次只解决一个问题	出错时容易定位
改完立即提交	下一步改坏了可以回到这里

6. 第五步：验证修改

看改动

git status      # 哪些文件被改了
git diff        # 具体改了什么

逐段阅读 git diff，对每一处改动问自己：这处改动和要解决的问题有关吗？看不懂的地方直接问 AI “这一行改动的作用是什么”。

跑起来

验证方式	做法
复现原问题	用修改前出问题的同一个操作再试一次
运行测试	运行项目已有的全部测试，不只是新加的
检查相关功能	导出其他格式、导出空数据等相邻场景
让 AI 复查	新开一个对话，让它审查这次 diff 是否有遗漏或副作用

复查提示词：

请审查当前分支相对于 main 的改动（git diff main），
只指出可能的错误、遗漏的边界情况和与项目现有风格不一致的地方，不要修改代码。

验证通过后提交，写清楚改了什么、为什么改。

7. 常见错误

错误	表现	改进
一上来就让 AI 改	改动范围失控，看不懂改了什么	先只读理解，再修改
相信 AI 对代码的描述	照着不存在的函数去找	按文件路径和行号亲自核对
不复现就修	问题没解决，或掩盖了真正原因	先确认原因再改
测试失败时让 AI“让测试通过”	它可能直接改测试或跳过测试	明确要求“修复代码，不要修改已有测试”
对话太长后 AI 前后矛盾	忘记早先的约定	新开对话，引用项目地图笔记
命令行工具连接超时	网页能开，终端里请求失败	见 浏览器能访问，为什么应用程序连接失败 和 AI 工具报错或无法访问怎么排查

相关阅读

• AI 编程工具入门：开始使用前需要准备什么
• 用 AI 做一个网页：从需求描述到上线
• Codex 入门教程：安装、登录与第一个任务
• Cursor 入门教程：安装、登录与第一个任务
• AI 导航：AI 编程与建站工具