ARTICLE · 1197094
没有文档的老项目,AI读得懂吗?我调研了5种思路
没有文档的老项目,AI读得懂吗?我调研了5种思路入职一家新公司，或者中途接手一个老项目，最痛苦的莫过于：没有文档。 或者有文档，但最后一次更新是一年前，里面的架构图和现在的代码早就对不上了。 想搞清楚这个系统到底怎么运转，无非啃代码，翻测试用例，逮着老员工问。问题是老员工很忙，也不一定知道，代码量大，测试用例还不见得靠谱。 这样的情况很常见。现在大模型时代，可以尝试用skill来解决这个问题。 带着这个问题，我在工作里做了一些尝试，也跟不少同行交流过他们团队的做法。汇总下来，关于"用AI读懂一个没文档的项目"，至少有5种完全不同的思路。 这篇文章把这5种思路摊开讲：每种怎么做，效果怎么样，适合什么场景。最后给新手一条上手路线。
这是目前的主流路线，也是大多数人的第一反应。 做法：把仓库地址扔给AI，克隆下来之后，用grep、glob做文本检索，用AST工具（tree-sitter、ast-grep这类）做语法级分析，再配合scip之类的索引工具理清符号跳转，对整个仓库做一遍全量静态分析。 读什么？成熟的方案会重点提取五类事实： 入口清单：controller接口、RPC服务、消息队列消费端、定时任务，也就是系统对外敞开的所有门。 调用链：从入口一路往下，谁调用谁。 配置：服务里的配置，数据库里的配置项。 数据模型：表结构、mapper XML。 技术栈：框架和中间件。 提取完，输出一份知识文档。 效果：快，半天就能对一个陌生仓库建立基本认识。局限也明显，代码是静态的，它告诉你系统"能做什么"，但说不清系统"实际在做什么"。有些逻辑写了但从来没被调用，有些路径才是真正的流量担当，光看代码分不出来。 思路一的局限，正好引出第二种做法：光看代码不够，把运行数据拉进来对照。 一个公司里关于系统的"活数据"其实很多：日志平台的调用记录，监控平台的流量和耗时，覆盖率平台上哪些代码真的被执行过，需求研发管理平台上这个模块改过多少次、谁改的。 把这些数据和代码分析结果摆在一起看，很多事情就清楚了。比如代码里有十个入口，监控数据告诉你真正扛流量的只有三个。比如某个方法你以为是核心链路，覆盖率数据显示它半年没被碰过。 效果：能回答"系统实际怎么跑"，这是纯静态分析给不了的。前提是你的团队有这些平台，数据够全，AI还得有权限访问。这一条在很多团队是硬门槛。 前两种都是"现场提取"：你问问题，它现场读代码、现场分析。 第三种思路反着来：知识不现场提取，提前建好。把调用关系、数据模型、已有文档统一建成图谱或者索引，查询的时候直接检索，秒级出结果，每个结论还能溯源到具体的文件和行号。后续系统变了，知识也跟着更新。 效果：响应快，答案稳定，团队所有人共用一份知识，不用每个人接手都从头读一遍。 代价是前期投入大。建图谱、建索引、做更新机制，每一项都是工程量。它适合"系统长期有人维护、长期有人问"的场景。一次性搞清楚就完事的项目，犯不上。 这个思路最有意思：干脆不读代码，把系统当黑盒。 用浏览器自动化把系统的界面全量遍历一遍，点每个按钮，进每个页面，观察状态之间怎么跳转，推断系统背后的状态机。走完一遍，得到一张功能地图，外加一份不确定点清单：哪些地方推断不出来、有歧义，如实记下来。 然后进入人工回填环节。人拿着这份清单回到代码里做白盒确认，把黑盒推断和白盒事实对上。 效果：特别适合有界面的业务系统，产出的功能地图接近用户视角，产品和运营也能看懂。缺点是无法全自动，人工回填那一步省不掉，页面多的系统遍历一遍也不轻松。 最后一种比较特殊：不读代码，读测试用例。 逻辑是这样的，测试用例记录的是"系统应该怎么表现"，一条条用例就是一份份行为说明书。用例写得好的项目，用例库就是现成的需求文档。 但它成立有个大前提：用例的管理情况。用例是否持续更新，是否和代码同步，命名分类是否规范，直接决定它能不能当知识源。 我见过用例维护得极好的团队，也见过用例库零星维护的团队，还有很多团队的用例只有标题没有操作步骤和预期结果等关键信息。维护得极好，用例是个宝。维护得差，用例就很鸡肋。 效果：成本低，读用例比读代码快得多，但质量方差极大。用之前先抽样看看用例库的成色。
5种思路讲完，说说各家的共同做法。这部分最值得抄。 输入规范。成熟的方案不会上来就全量读，会分层：先读目录和入口，再按模块深入。提取什么也有清单，比如前面那五类事实。 防幻觉约束。这是所有方案里纪律性最强的部分：结论必须带文件和行号；没找到不代表没有；推断类结论的置信度封顶0.6；提取不出来的信息强制标"待补充"，不许编造。有的方案还会引入不同视角互相对质，或者加一个仲裁角色复核结论。 多agent并行。仓库多、上下文太大的时候，把读取任务拆给多个子agent并行做，再汇总结果。 持久化和保鲜。读出来的知识要沉淀成文档或知识库，还要有更新机制。不然每次都是临时读一遍，下一个人接手，一切重来。
5种思路放在一起，如果不去组织，它们只是一份菜单。真正有用的是看清楚层次。 按"知识从哪来、什么时候提取"两个维度，我把它们分成三层。 第一层：代码精读（思路一） 定位是底座。 优点：零门槛，见效快，一个仓库地址就能开工。 缺点：只能告诉你代码里有什么，分不清死代码和真流量。 适用场景：任何情况下的第一步，特别是时间紧、只想快速建立基本认识的时候。 第二层：代码外的事实校准（思路二、四、五） 定位是纠偏。代码读明白了，但代码不等于现实。这三种思路分别从运行数据、用户界面、测试用例三个角度，拿代码外的事实来校准和补充。 优点：能回答系统实际怎么运转。 缺点：都依赖外部条件，运行数据要权限，黑盒遍历要人工回填，测试用例要用例库质量过关。 适用场景：对理解深度有要求，或者要基于理解去做改动、做决策的情况。 第三层：知识预建（思路三） 定位是基础设施。 优点：查询快，可溯源，可复用，知识变成团队资产。 缺点：建设成本高，还要持续保鲜。 适用场景：系统长期处于多人接力维护的状态，或者同一套系统会被反复提问。 一句话选型：快速摸底选第一层，要做改动加第二层，长期多人用建第三层。 三层之间不互斥。比较常见的走法是：先用第一层跑通，把第二层里条件成熟的部分补上，等团队里问的人多了，再把沉淀下来的知识升级成第三层。
如果你手头正好有一个没文档的项目，想让AI帮你搞定，我建议按这个顺序来。 第一步，先写提取清单，再动手。 别急着把仓库扔给AI。先想清楚你要什么。入口清单、调用链、配置、数据模型、技术栈，这五类事实是性价比最高的起步清单。清单越明确，输出越靠谱。 第二步，用静态精读跑通一个最小版本。 目标定小一点，比如先产出一份这个仓库的入门文档。跑通的价值在于建立信心，也在于暴露问题。你会很快发现哪些地方AI读不准，哪些信息代码里根本没有。 这时候你会继续产生诉求，再完善skill。 第三步，把防幻觉纪律加上。 最小版本跑通之后，尝试增加约束：结论带文件和行号，推断要标注，读不出来就写"待补充"。这一步决定产出的是能用的资料，不止是看着像那么回事。 第四步，有条件再上交叉验证。 如果你能访问日志、监控这些平台，把第二层加上。哪怕只接一路监控数据，理解的准确度都会明显上一档。没条件就先跳过，时机成熟时再说。 第五步，多人复用时再考虑沉淀。 如果你发现团队里不止你一个人需要这份知识，再去建知识库、做更新机制。一个人用一次的文档，认真做持久化没有必要。 还有两个最常见的错误。 一个是一上来就建知识图谱。代码都没读通就想搞基础设施，结果图谱建了一半，问题还是没解决。 另一个是跳过人工确认。黑盒推断也好，AI提取也好，标了"待补充"的地方一定要人工回填。指望全自动，最后坑的是自己。
为了让读者能借鉴思路，后续我也会提供几个skill，初步思路是从github上找一些开源项目来实践。如果你遇到的项目情况特殊，到时候再具体交流。 你们团队接过没文档的老项目吗？最后是怎么搞清楚的？评论区聊聊。
正文
