先考古再动手：用 AI 接手陌生代码库的第一周协议

2026 年 10 月 22 日，V2EX 上出现了一个帖子：《前端想学后端，但是看完这段代码就已经力竭了》。一百多条回复里，一种声音反复出现：看不懂就交给 AI 写。这话听起来洒脱，但没人回答一个更扎心的问题——如果连代码都看不懂，你交给 AI 的改动，凭什么相信它是安全的？

Vibe coding 把"写代码"的速度推到了前所未有的高度，但它同时制造了一个新问题：代码越写越快，"读懂别人的代码"反而成了稀缺能力。你可能会接手一个 AI 生成的旧项目、给一个开源项目做二开，或者从前任手里接过一个仓库。不管哪种情况，第一周的方法，决定后面三个月的返工量。

这篇指南给的就是这套方法：用 AI 当考古工具，用五天时间把一个陌生代码库吃透。它的核心信条只有一句——先考古，再动手。

阅读前说明：本文的边界。这是一份"入职陌生代码库"的方法论，讲的是第一周该按什么顺序做什么、交付什么。它的交付物很具体：架构草图、一条主链路的时序图、风险清单、一份项目上下文文件。它不讲"怎么读懂一段具体代码"的阅读技巧（那是另一篇指南 reading-ai-generated-code-guide 的地盘），也不讲"老代码怎么渐进式重构"（那是 legacy-code-gradual-refactor-agent 的地盘）。本文是改之前的前置工作：重构是手术，本文是术前检查。

一、为什么"这个项目是干什么的"是最差的开场问题

绝大多数人打开一个陌生仓库后的第一个动作，是把代码库扔给 AI 然后问："这个项目是干什么的？给我讲讲架构。"AI 会立刻给你一段流畅的回答，条理清晰、术语准确——然后你开始基于这段回答做一切后续判断。这就是灾难的起点。

问题不在于 AI 笨，而在于它在没有仓库上下文证据链的情况下，只能靠推测回答。而它的推测有三种固定套路，我称之为"开场三幻觉"：

幻觉一：按目录名脑补架构

看到 services/ 就说"这是微服务架构"，看到 controllers/ 就说"这是 MVC"，看到 utils/ 里有个 queue.ts 就断言"项目用了消息队列"。目录名只是作者随手起的名字，一个叫 services/ 的文件夹里可能装着三个互不相干的工具函数，而真正的业务逻辑藏在 lib/ 里。AI 从训练数据里学到的是"目录名与架构的统计相关性"，不是这个仓库的事实。

幻觉二：把示例当主逻辑

很多仓库带 examples/、demo/、playground/ 目录，或者 README 里贴着一大段"快速上手"代码。AI 最喜欢引用这些地方，因为它们注释多、命名规范、读起来最顺。但示例代码往往是作者精心简化的玩具版本，和生产路径的真实逻辑可能差了三层中间件、两次权限校验和一个 feature flag。按示例理解项目，等于按样板间理解一栋楼的承重结构。

幻觉三：给出无法验证的结论

这是最危险的一种。AI 会说"该项目采用事件驱动架构，通过 Redis Stream 实现服务间解耦"——听起来极其专业，但你顺着它给的方向去找，可能发现根本没有 Redis，所谓"事件"只是几个函数名里带 emit 的普通调用。流畅的结论不等于可验证的结论，而无法验证的结论比没有结论更糟，因为它会让你带着错误的地图走很远。

所以第一条铁律：永远不要问 AI"这个项目是干什么的"，要问它"这个项目有哪些证据能说明它是干什么的"。把开场问题从"要结论"换成"要地图"，整个考古工作就走上了正轨。

二、第一步：先要地图，不要结论

考古学的第一步永远是测绘，不是解读。面对代码库也一样：第一天要拿到的不是"理解"，而是一张带证据的地图——每个结论后面都跟着文件路径和行号，找不到证据的结论必须明确标出来。

带证据要求的提问模板

直接复制下面这个模板，把它作为你和 AI 的第一次对话。它有三个关键设计：第一，强制每条结论附证据（文件路径:行号）；第二，允许 AI 说"找不到"——这比编造重要得多；第三，要求区分"事实"和"推测"。

请你扮演一个代码考古学家，帮我测绘这个仓库。规则如下：

1. 你的每一条结论后面，必须附上证据，格式为「文件路径:行号」。
2. 找不到证据的结论，明确标注「推测：」开头，并说明你为什么这样推测。
3. 不要引用 examples/、demo/、docs/ 里的示例代码作为生产逻辑的证据。
4. 最后输出一张表，列：模块名 | 职责（一句话） | 证据 | 置信度（高/中/低）。

请依次回答：
a. 这个项目的入口在哪里？（package.json 的 scripts、main 入口、框架的路由注册文件）
b. 数据从哪里来、到哪里去？（数据库连接、外部 API 调用、环境变量里的服务地址）
c. 有哪几个顶层模块？每个模块的职责是什么？
d. 有哪些你「推测」存在但找不到证据的东西？（比如看似用了队列但没找到配置）

注意第 4 条：让 AI 主动列出"推测但无证据"的清单。这个清单的价值经常超过地图本身——它告诉你这个仓库里有哪些"看起来像、但可能是坑"的地方。

地图的验收标准

AI 交回地图后，别急着信。花 30 分钟做三件事：

• 抽查三条证据。随机挑三个"高置信度"结论，亲自打开对应文件看到那一行。如果三条里有一条对不上，这张地图的置信度就要整体降一档。
• 找入口，跑起来。按地图说的入口把项目跑起来（哪怕只是 npm run dev 看到首页）。跑不起来的地图，再漂亮也是纸上谈兵。
• 看依赖，不看描述。打开 package.json、requirements.txt、go.mod 这类依赖清单。依赖是不会撒谎的：装了 bullmq 就是真有用队列，装了 prisma 就是真连数据库。这比任何架构描述都可靠。

第一天结束时，你手里应该有一张纸（或一个文档）：入口在哪、模块有哪几个、数据流向哪、哪些是推测。这张纸不需要精美，它只需要每条都有证据。

三、第二步：追一条主链路

有了地图，第二步不是把每个模块都读一遍，而是只追一条链路：从用户入口到数据存储，把最核心的那条调用链吃透。泛读十个模块，不如吃透一条链路——因为链路给你的是"改哪里会碰到谁"的直觉，而泛读给你的是散装知识点。

选哪条链路

选这个产品用户最常用的那个功能。电商就是下单，内容平台就是发布，SaaS 工具就是登录。用这条链路的好处是：它是被测试得最多的路径，代码质量通常最高，而且你之后 80% 的改动都会落在这条链路上。

让 AI 帮你定位链路入口，提问方式要具体："用户点击'提交订单'按钮后，第一个被调用的后端函数是哪个？给出文件路径和行号。"不要问"订单流程是怎样的"——太宽泛的问题只会换来另一段无法验证的散文。

追链路的操作方法

从入口函数开始，用"逐层下钻"的方式跟下去，每一步都记录：

1. 当前函数在哪个文件、第几行，函数签名是什么；
2. 它调用了哪些下游函数（只记直接调用，不展开）；
3. 每个调用传递了什么关键参数，返回了什么；
4. 有没有分支（if/else、try/catch、feature flag），分支条件是什么。

跟到数据真正落地为止：写进了哪张表、调了哪个外部 API、发了哪条消息。跟完之后，把这条链路画成时序图。下面是一张示例——你画的应该长这样：

画图的工具不重要（纸笔、Excalidraw、Mermaid 都行），重要的是每个箭头都对应一次你亲眼见过的真实函数调用。画不出来的箭头，说明那段逻辑你还没真懂，回去继续跟。

这条链路要回答的三个问题

链路追完，你应该能脱稿回答：

• "如果我要改订单金额的计算逻辑，要动哪几个文件？"——答不上来，说明链路没吃透；
• "这条链路上最脆弱的一环在哪？"（比如库存扣减和订单写入不在一个事务里）；
• "哪个环节最可能藏着历史包袱？"（比如某个 if 分支的条件看起来毫无道理——记下来，这是第四步要查的）。

第二天结束时，你的交付物是：一张时序图 + 三个问题的答案。这张图以后会成为你做任何改动前的"作战地图"。

四、第三步：用改动验证理解

"我看懂了"是最不可靠的自我评估。真正的理解只有一种检验方式：改一下，看结果是否符合预期。第三步就是用一系列小实验，把"我以为"变成"我验证过"。

实验一：最小改动实验

找一个无害的地方做最小改动：改一句日志文案、改一个按钮文字、给某个函数加一行 console.log。然后跑起来，看你的改动是否出现在预期的位置。

这听起来很蠢，但它验证的是最基础的东西：你改的代码，真的是线上跑的那份代码吗？太多人栽在这种地方：改了半天发现改的是 src/ 而实际跑的是 dist/，或者改的是主分支而部署的是另一个分支。一个五分钟的实验，能省掉一下午的困惑。

实验二："故意破坏"验证法

这是考古阶段最高效的技巧：注释掉一个调用，看哪里报错。报错信息是最好的地图——堆栈会精确告诉你这个调用的上游是谁、下游是谁、缺了它谁会先崩。

具体做法：

• 挑链路上的一个中间函数，把它调用下游的那行注释掉；
• 跑起来，触发这条链路，看报错；
• 记录：报错信息是什么、堆栈经过了哪些文件、哪个环节先失败；
• 恢复代码，换下一个函数重复。

做三到五次，你对"谁依赖谁"的理解会比读三天代码更扎实。注意：所有实验都在单独的分支上做，做完即删，别让实验代码污染仓库。

实验三：把"我以为"固化成测试

每验证一个理解，立刻写成一个最小的测试或断言锁住它。比如你发现"订单金额 = 商品总价 × 折扣 + 运费"，就写一个断言把它钉住。这些测试不需要进 CI（除非你想），它们的价值是：下次你或 AI 改动相关代码时，测试会第一时间告诉你理解是否还成立。

这一步还有个附带好处：你写的这些测试，后来会成为你提交给这个项目的第一份有价值的贡献——没有哪个维护者会拒绝"补测试"的 PR。

五、第四步：查"为什么这样写"

链路追完、理解验证完，你一定会遇到一些"别扭"的代码：看起来多余的 if 分支、莫名其妙的魔法数字、被注释掉但没删除的代码、命名怪异的兼容函数。新手的第一反应是"这写得真烂"；老手的第一个反应是——这背后可能是一次线上事故。

git 是最好的考古现场

对每处别扭代码，走一遍这个流程：

1. git blame：看这行代码是谁、什么时候写的；
2. git log -p --follow <文件>：看这行代码的完整变更历史，注意提交信息里有没有"fix"、"hotfix"、"紧急"、"回滚"这类词；
3. 找关联的 PR / Issue：提交信息里通常有编号，顺着编号去看当时的讨论——很多"为什么"都写在 PR 的评论区里；
4. 对时间线：如果提交时间是凌晨三点，提交信息只有"fix"，那几乎可以肯定这是一次线上救火，而这段别扭代码就是救火的痕迹。

真实案例的模板长这样：某段代码里有个 if (userId.startsWith("legacy_")) 的分支，看起来完全多余。blame 发现它是两年前一次凌晨 hotfix 加的，关联 Issue 写着"老用户迁移后订单丢失"。删掉这个分支，等于亲手复活两年前那个事故。

风险清单：第四步的交付物

把查到的"别扭代码及其原因"整理成一张风险清单，格式如下：

位置	别扭之处	历史原因	能否动
order.ts:142	legacy_ 前缀分支	2024 年迁移事故的 hotfix	不能删，需保留兼容
pay.ts:88	重试 3 次后静默吞错	原因不明，无提交记录	待确认：先加日志观察
util.ts:30	注释掉的大段代码	作者自己注释，无事故背景	可删，删前先备份分支

注意第二行的"原因不明"——诚实地标出来。不知道就是不知道，标成"待确认"远比瞎猜一个原因安全。这张风险清单，是你未来三个月里最重要的护身符：每次改动前，先查这张表。

六、第五步：沉淀为项目上下文文件

前四步的所有产出——地图、时序图、验证过的理解、风险清单——如果只存在你的脑子里，那下次开新会话时 AI 还是会从零开始犯同样的错误。最后一步是把它们沉淀成一份项目上下文文件，让它成为你和 AI 协作的长期资产。

写在哪、写什么

文件名取决于你用的工具：Claude Code 是 CLAUDE.md，Cursor 是 .muserules，通用一点就叫 AGENTS.md。名字不重要，重要的是它放在仓库根目录，AI 每次开工都会先读它。

内容结构建议：

# 项目上下文（考古日期：2026-10-24）

## 这是什么项目
一句话：xxx。入口：xxx。

## 技术栈（只写验证过的）
- 后端：xxx（证据：package.json）
- 数据库：xxx（证据：.env.example 里的 DATABASE_URL）

## 核心链路
- 下单链路：前端 createOrder() → POST /orders → OrderService.create()
  → InventoryService.lockStock() → 写入 orders 表
- 时序图见 docs/arch/order-sequence.png

## 坑位清单（改之前必看）
- order.ts:142 的 legacy_ 分支是 2024 年迁移事故的 hotfix，不能删
- pay.ts:88 的静默吞错原因不明，改之前先加日志

## 约定
- 所有实验性改动走单独分支，做完即删
- 不要引用 examples/ 目录的代码作为生产逻辑依据

三条写作铁律

• 只写验证过的，不写猜的。凡是标了"推测"的结论，一律不进文件。上下文文件里的每句话都应该是你亲手验证过的——AI 会无条件信任这个文件，文件里的错误会被放大十倍。
• 写"不要做什么"，比写"要做什么"更重要。"不要删 legacy_ 分支"比"订单模块负责下单"有价值得多。坑位清单是这份文件里 ROI 最高的部分。
• 持续更新，而不是一次写完。每次你验证了一个新理解、踩了一个新坑，就追加进去。三个月后，这份文件会比任何官方文档都更接近这个项目的真相——因为它是用真实事故写成的。

这份文件有两个读者：一个是三个月后的你，一个是下一个接手这个仓库的人（很可能也是对着 AI 发愁的人）。你第一周的考古工作，最终沉淀成他们上手的第一份地图——这就是"考古"的完整闭环。

第一周交付清单

把五步压缩成一张时间表，贴在你工位上：

时间	任务	交付物	验收标准
第 1 天	测绘：带证据的架构地图	模块职责表（含证据与置信度）	随机抽查 3 条证据，全部能对上；项目能跑起来
第 2 天	追一条主链路	时序图 + 三个问题的答案	每个箭头对应真实函数调用；能说出改哪里会碰到谁
第 3 天	用改动验证理解	3-5 个破坏实验记录 + 锁定的测试	每个"我以为"都有实验或测试背书
第 4 天	查"为什么这样写"	风险清单	每处别扭代码都有历史原因或诚实的"待确认"
第 5 天	沉淀上下文文件	CLAUDE.md / AGENTS.md	只含验证过的结论；坑位清单完整

五天下来，你对这个代码库的理解会超过很多待了一年的"熟手"——因为熟手靠的是模糊的肌肉记忆，而你靠的是一套有证据链的方法。更重要的是，从第二周开始，你让 AI 做的每一次改动，都有地图、有链路、有风险清单、有上下文文件托底。AI 写代码很快，但"知道该让它改哪里、不该让它碰哪里"——这才是 vibe 时代真正的稀缺能力。

先考古，再动手。祝你的第一周，挖到的都是宝藏，不是地雷。