冷启动遗留系统：用四层上下文让AI读懂旧代码

我接手过一个跑在生产环境里快十年的老系统，Java 加 JSP，还有一堆没人敢删的 shell 脚本和配置文件。第一次想让它"被 AI 看懂"的时候，我把几个核心类丢进去问"这个方法的业务含义是什么"，它给出的回答流畅、自信，然后完全是错的。那次之后我才意识到一件事：AI 读新代码很强，读旧代码几乎是半瞎的。原因不在模型，而在于旧项目长年累月堆积出来的信息断层——命名混乱、结构塌陷、业务规则只存在于某些人的脑子里。所以这篇东西想聊的，就是冷启动一个旧项目时，怎么用一套可复现的方法，把 AI 从"看得见字但看不懂事"变成"能回答、能定位、能改"的状态。适合谁看？适合接手遗留系统的开发、需要快速摸清历史包袱的维护者，也适合想把 AI 真正用进日常工作而不是当玩具的人。整个过程不需要什么特殊工具，一台能跑代码的机器、一个能读文件的 AI 助手，加上一点耐心就够了。

1. 先搞清楚：旧项目为什么会让 AI"看不懂"

1.1 旧项目的三类信息断层

新项目的代码和业务是同步长出来的，变量名基本能自解释，分层也还清晰。旧项目不是这样，它是被一次次需求、一次次救火、一次次人员流动磨出来的。磨到最后，代码里会出现三类非常典型的断层。

第一类是命名断层。你会在代码里看到doIt()、tmp2、dataList1、a1、processFlag这种东西，甚至有直接拿拼音首字母当变量名的。这类命名对人来说都费劲，对 AI 更费劲，因为模型理解代码高度依赖符号语义。当所有符号都失去语义，模型就只能靠调用位置去猜，猜错的概率非常高。

第二类是结构断层。典型特征是单个文件几千行，一个方法几百行，逻辑全塞在一起，没有 service 层、没有边界。AI 做代码分析靠的是"分块 + 关系"，文件一大，它要么被截断，要么只能看到局部，看不到全局。你在一个 8000 行的类里问它"这个改动会影响哪些地方"，它几乎无法回答，因为影响面散落在它没读到的部分。

第三类是上下文断层，也是最致命的一类。业务规则不在代码里。比如"这个字段为 0 的时候表示未审核，但历史数据里也有 -1 表示未审核"，这种信息只存在于某些人的记忆或者某份早就不知道去哪的需求文档里。AI 没有任何渠道知道这件事，它只能看到代码里那个if (status == 0)，然后给你一个看似合理的解释。

这三类断层叠加在一起，就是冷启动旧项目最难受的地方：你问的问题越接近业务本质，AI 的答案就越不可靠。

1.2 AI 读代码的真实能力边界

很多人对 AI 读代码的期待是"把仓库丢进去它全懂"，这个期待不现实。它的真实边界大概是这几条。

它能做得很好的：局部代码解释、单文件内的逻辑梳理、根据一段代码写测试、把一段老语法翻译成新语法、找出明显的空指针和资源泄漏。这些事情不依赖全局理解，只依赖它眼前的那段文本。

它做得一般的：跨文件调用链追踪、影响面分析、"这个功能在哪里实现的"这类检索型问题。做一般的原因不是它笨，而是它拿到的东西不完整——检索召回不准，或者上下文塞不下。

它做不好的：运行时的行为、依赖外部系统的副作用、以及所有不在代码里而在人脑里的隐性规则。

把这三档区分清楚，你的期望就对了。你要做的不是让 AI 变强，而是把它的输入补全——把那些它拿不到的东西，用人能写、机器能读的方式补进上下文里。这也是后面所有方法的出发点。

2. 冷启动前的准备：先给项目做一次"分诊"

2.1 判断这个项目值不值得投入

不是每个旧项目都值得你花几天时间去整理上下文。先做一次快速分诊，用三个问题判断。

第一个问题：它还在跑吗，还要改吗。如果一个系统只是挂着不动、未来半年没有任何需求，那你的目标应该是"看得懂就行"，不需要精细整理，把入口文件和关键配置交给 AI，能回答基本问题就收工。

第二个问题：核心业务逻辑集中还是分散。集中在一个模块里的，整理成本低，一天能搞定；散落在十几个模块互相引用里的，就得先做调用链切片，成本高一截。

第三个问题：有没有测试。有测试的项目，AI 可以通过测试理解预期行为，这是巨大的杠杆；没有测试的项目，你就得多花时间在"用文档补预期"上。

我一般会用一个很粗暴的标准：如果这个项目我预计要投入超过两周，那就值得花半天到一天专门整理上下文；如果只是看一眼，直接用 AI 边读边问更划算。别把整理上下文本身变成一个拖垮进度的大工程。

2.2 建立最小可读基线

整理之前，先确保项目处于"可运行、可构建"的状态。这一步看起来和 AI 无关，其实关系很大。

AI 判断代码对不对，最可靠的方式是对照运行结果、对照编译错误、对照测试输出。如果项目连编译都过不了，你给它的所有输出都没法验证，你就只能凭感觉信或者不信，这个循环非常低效。

具体做法很朴素：把依赖装上，把数据库或者数据文件准备好，让服务能在本地起来，跑一遍现有的测试（哪怕是几个）。跑不起来的旧项目很常见，那就退一步，至少让核心模块能单独编译通过。这个基线建立起来之后，你后面问 AI 的每个问题都有一个验证手段——让它在本地改一版，编译一次，看报不报错。

我踩过的坑是：跳过这一步，直接让 AI 读代码并给出修改建议，改完一编译一堆错误，然后我又得回去问它为什么，来回消耗的时间比搭环境还长。先把地基铺平，后面才快。

3. 核心方法：把旧项目"翻译"成 AI 能吃下的四层结构

这套方法是我自己磨出来的，核心思路是分层补全：每一层解决一类断层，从粗到细，做完一层就能回答一批问题，不需要一次做完。

3.1 第一层：目录地图与入口清单

这一层解决"结构断层"。目的是让 AI 知道这个项目大致长什么样，哪些目录是核心、哪些是历史遗留、哪些根本不重要。没有这层，AI 会把一个废弃的old_backup目录和核心业务目录同等对待，召回一堆垃圾。

做法是这样：先扫一遍顶层目录，人工判断每个目录的角色，然后写一份精简的地图。地图不用详细，一个目录一句话就够。关键是把"入口"标出来——程序的启动点、请求的入口、定时任务的入口、消息消费的入口。这些入口是后面所有调用链追踪的起点。

如果项目结构比较乱，可以用几条命令先拿到客观数据，避免凭印象判断。

# 统计各语言代码量和文件数 find . -type f -name "*.java" -not -path "*/target/*" | wc -l find . -type f -name "*.py" -not -path "*/venv/*" -exec wc -l {} + | sort -rn | head -20 # 找出最大的文件，通常是重灾区 find . -type f \( -name "*.java" -o -name "*.py" -o -name "*.js" \) -not -path "*/node_modules/*" \ -exec wc -l {} + | sort -rn | head -15 # 找出最近半年没人动的目录，大概率可以标记为低优先级 find . -maxdepth 2 -type d -mtime +180

拿到这些数据之后，你的目录地图就有了事实依据，而不是拍脑袋。

3.2 第二层：术语表，把业务黑话翻译成代码符号

这一层解决"命名断层"和部分"上下文断层"，是我认为投入产出比最高的一步。

几乎每个旧项目都有一套自己的黑话。可能是业务术语，比如"结算单""对账批次""冻结额度"；也可能是历史遗留的奇怪缩写，比如gmt其实是某个业务状态、qk是某种渠道。这些东西开发者心里有数，但 AI 完全没有。

你要做的是把它们整理成一张表，三列：业务说法、代码里的符号、一句话解释。这张表后面直接塞进 AI 的上下文，效果立竿见影——原本它看到qkFlag会瞎猜，现在它能准确说出这是渠道标识。

整理这张表有个技巧：不要对着代码硬想，而是拿着代码里的高频名词去问同事或者翻历史文档。哪些词出现频率高、哪些词让你困惑，优先整理它们。我一般会先跑一遍词频统计，把出现次数最多的一批标识符挑出来。

# 抓取驼峰和下划线标识符，粗略看高频词 grep -rhoE "[A-Za-z_][A-Za-z0-9_]{3,}" src/ \ | sort | uniq -c | sort -rn | head -60

这份表不需要一次做完，先写十个最关键的，够用了。

3.3 第三层：调用链切片，从入口往下切

这一层解决"结构断层"里最难的部分——跨文件理解。做法是：挑出你最关心的几个业务场景，从入口开始，把这条链路上涉及的文件和方法挑出来，做成一个"切片包"。

比如"用户下单"这个场景，链路可能是：Controller 的createOrder→ Service 的validate→reserveStock→createPayment→ 落库。你把这条链路上的每个方法所在的文件都列出来，标注它的角色（校验、扣减、支付、持久化），然后在这份切片里问 AI。

为什么这么做？因为 AI 处理大仓库的方式和你不一样，它不是真的一次读完，而是靠检索和分块。你主动把一条链路裁出来，等于替它做了最关键的召回工作，它的回答质量会直接上一个台阶。

切片包的形式可以很简单，一个 Markdown 文件，列清楚场景、入口、链路文件清单和每步职责。关键是链路要准确，最好你自己先跟着代码走一遍，或者用 IDE 的调用层级功能确认一遍。

3.4 第四层：约束与潜规则文档

这一层专门收留那些"代码里看不出来但必须知道"的东西。这是旧项目最有价值的资产，也是最容易被忽略的。

内容大概包括这几类：数据状态的特殊取值（比如 -1 代表什么）、不能改的字段、有顺序要求的操作、和生产环境绑定的配置、以及团队约定俗成的规矩（比如所有时间都用某个时区、金额都用整数分存储）。每一条都写成一句话，配上它在代码里的位置。

写这层文档的时候有个原则：只写"如果不写AI会猜错"的内容。不要把需求文档整段搬进来，那会把上下文撑爆，反而降低效果。

我这边的实际经验是，真正影响 AI 回答准确率的，往往是那么七八条潜规则，而不是几百页的需求。把这些关键点写清楚，收益远超预期。这层文档写完，你的上下文就基本够用了。

4. 实操全流程：从零到让 AI 准确回答业务问题

前面讲的是思路，这一节给一套可以直接照着做的流程。假设你刚接手一个项目，打算用两个小时把 AI 的上下文搭起来。

4.1 第一步：生成项目档案

先别急着问 AI，先自己收集事实。跑几条命令，拿到项目的客观画像：语言构成、代码规模、最大的文件、入口在哪、依赖了哪些外部服务。

# 语言构成 find . -type f -name "*.java" | wc -l find . -type f -name "*.xml" -not -path "*/target/*" | wc -l # 入口：找 main 方法和启动类 grep -rl "public static void main" --include="*.java" . grep -rl "@SpringBootApplication" --include="*.java" . # 外部依赖：看配置文件 grep -rhE "(jdbc|redis|mq|amqp)://" src/main/resources/ | sort -u

这些输出自己看一遍，你对项目的印象就具体多了，后面写档案也不会瞎写。

4.2 第二步：写上下文包

把前面四层的内容整合成几个文件，放在项目根目录下一个专门的文件夹里，比如.ai-context/。结构建议这样：

.ai-context/ 00-map.md # 目录地图与入口清单 01-glossary.md # 术语表 02-flows/ # 调用链切片，一个场景一个文件 order-create.md settle-batch.md 03-rules.md # 约束与潜规则

每个文件都尽量短，能一句话说清就不要写两句话。00-map.md的模板大概是这样：

# 项目地图 ## 入口 - Web 入口：src/main/java/.../OrderController.java - 定时任务：src/main/java/.../job/SettleJob.java（每天凌晨 2 点） - 消息消费：src/main/java/.../mq/StockConsumer.java ## 目录角色 - service/：核心业务逻辑，改需求主要动这里 - dao/：数据库访问，老代码里的 SQL 拼在这 - legacy/：废弃模块，不要参考，也不要改 - common/：工具类，通用但历史包袱多 ## 重点文件（大且乱，改动需谨慎） - OrderServiceImpl.java（3200 行） - SettleHelper.java（1800 行）

写完这几份文件，你的准备就完成了大半。

4.3 第三步：设计提问模板

上下文有了，提问方式也很关键。我吃过最大的亏就是问得太宽，比如"帮我分析这个项目"，AI 给一堆泛泛而谈。有效的问法有几个特征：绑定具体场景、要求引用文件、要求区分事实和推测。

几个我常用的模板：

请只基于 .ai-context/ 和指定文件回答，不要脑补。 问题：订单创建时，库存扣减和支付创建的顺序是什么？ 要求： 1. 引用具体文件和行号 2. 如果信息不足，明确说"上下文里没有"，不要猜 3. 区分"代码显示的事实"和"你的推断"

请阅读 02-flows/order-create.md 里列出的文件，回答： 如果我要在创建订单后增加一次风控校验，最小改动点在哪？ 给出改动清单，包括文件、方法、以及需要同步修改的地方。

模板的核心是那句"信息不足就说没有，不要猜"。旧项目里 AI 猜错的代价很大，因为它猜得特别连贯，你很容易被带偏。

4.4 第四步：用回读测试验证 AI 是否真的懂了

AI 说自己懂了不算数。我一般会做一次三轮验证，用三个问题测它。

第一轮，问一个你知道答案的事实型问题，比如某个状态值的含义。答对了说明术语表和规则文档起作用了。

第二轮，问一个你没整理过的链路，看它是老实说不知道，还是开始编。老实说不知道，说明边界控制得好；开始编，说明你的提问里缺约束，要补。

第三轮，让它做一个小改动，然后在本地编译验证。比如把某个日志级别改一下、给某个方法加个空值保护。改完能编译通过、逻辑合理，说明它对这个文件的理解是到位的。

三轮下来，你就知道你的上下文包里哪一层还薄，回去补哪一层就行。这个迭代过程通常两三轮就收敛了。

5. 工具与环境：一些实际选择上的考虑

5.1 几类 AI 辅助方式的对比

现在能用来读代码的 AI 工具形态差别挺大，选错了会浪费很多时间。我按自己的使用体验做个对比。

我的建议是组合使用：用能读仓库的工具做全局梳理和检索，用编辑器内置的做日常编码，两者不冲突。

5.2 大仓库怎么处理才不让索引崩掉

旧项目动辄几十万行，直接把整个仓库喂给工具，索引慢、召回也不准。有效的做法是先做过滤。

构建产物、依赖目录、自动生成的代码、历史备份目录，这些都要排除掉。大多数工具都支持配置文件指定忽略规则，把规则写清楚，索引量能降一大截，召回质量反而上升。

另外一个技巧是按模块分批索引。先索引你最关心的那一个模块，把上下文包也做小一点，回答质量会比"全仓库一把梭"好得多。等这个模块摸清了，再扩到下一个。冷启动最忌讳贪多，一次只啃一块，效率最高。

5.3 关于环境的一些零碎经验

字体、终端、编辑器这些看似无关，实际上对长时间读代码的体验影响很大。用等宽字体，选一个你眼睛不累的，配上合适的行高。终端里配好语法高亮，读 diff 的时候会舒服很多。这些都是小事，但你需要在这个项目上坐很久，小事累积起来就是大差别。

还有一点，把项目跑起来的步骤写成脚本，别每次都手动敲。冷启动阶段你会反复起停服务、跑测试、看日志，一个make run或者一个 shell 脚本能省下大量重复劳动。

6. 常见问题与排查技巧

6.1 常见问题速查表

整理一下我在冷启动过程中反复遇到的问题，以及对应的处理方式。

6.2 几条踩过坑才总结出来的经验

第一，不要让 AI 一次理解整个项目。这是最常见的错误，也是最容易导致挫败感的做法。正确的节奏是一个场景一个场景地啃，每啃完一个就沉淀一份切片文档，慢慢你手里就有了一整套可复用的上下文。

第二，把 AI 的回答当假设，不当结论。特别是涉及业务规则的部分，一定要用代码、数据或者同事的话去验证。旧项目里"看起来对但其实错"的解释最危险，因为你会照着一个错误的模型改代码。

第三，规则文档宁少勿多。我一开始很兴奋，把能想到的东西全写进去，结果上下文被稀释，关键信息反而被淹没了。后来精简到十几条最关键的，效果好很多。

第四，改动前一定要让 AI 列出影响面。旧项目里方法之间往往是隐式耦合，你改一个地方，另一个地方就崩。让 AI 先说清楚"这个改动会波及哪些文件"，即使它列得不全，也能帮你避开几个大坑。

第五，定期回读验证。上下文会随着项目演进过期，我大概每两周会把上下文包和代码对一遍，把失效的部分更新掉。这个习惯让我的上下文包一直能用，而不是用两周就废。

7. 进阶：让 AI 长期跟着这个项目走

7.1 把上下文包当成项目资产维护

上下文包一旦做起来，就不该是一次性的。把它纳入项目的常规维护，比如每次发布前顺手更新一遍目录地图，每改动一个核心链路就更新对应的切片。这件事花不了几分钟，但能让后面接手的人省很多事。

我现在的做法是把.ai-context/和代码一起进版本管理，改动它的时候也能看到历史。这样即使我离开这个项目，下一个人接手时能直接站在这套上下文上继续。这比写一份辞藻华丽但没人看的交接文档实在得多。

7.2 用 AI 做回归验证和知识补全

除了读代码，AI 在旧项目上还有两个高价值用法。

一个是回归验证。你可以让 AI 基于现有代码生成一批回归用例，尤其是针对那些边界条件复杂的逻辑。即使你不信任它生成的断言，把这些用例跑一遍、看看哪些失败，本身就能暴露一批历史遗留的隐藏问题。

另一个是知识补全。旧项目里经常有一些方法没人知道为什么这么写，注释也早没了。你可以让 AI 结合调用位置、上下文和历史提交信息，给出一个"最可能的解释"，然后拿去和同事确认。这种方式不保证准确，但能帮你快速形成一个可以验证的假设，比完全没头绪强。

我自己最近还在试的一件事是让 AI 帮我维护一份"变更风险清单"，把每次改动波及到的历史疑难代码记录进去，时间久了就形成一份针对这个项目的专属知识库。用了几个月，感觉方向是对的，后面如果有新进展再分享。