让 AI 先读懂再动手：CodeArts 代码库知识生成与跨仓理解实践

一、真正的瓶颈不是"找不到"，而是"读不懂"

很多人以为给 AI 配好索引、能 grep 到文件就万事大吉。但真接手一个陌生大仓时，卡点往往不是"某个 API 在哪个文件"，而是"这个模块负责什么、边界在哪、改这里会牵动谁"。

索引解决的是检索，知识解决的是理解。这是两件事。

尤其多仓场景（前端仓 + 若干服务仓 + 公共库），依赖关系散落在 import、配置文件和构建脚本里，靠人逐个翻成本极高，AI 也一样——上下文窗口根本装不下。

所以思路得换：不要让 AI 每次都"现场读代码"，而是先生成一份结构化的知识，之后让 AI（和人）持续消费这份知识。

二、两种知识，正交而不重复

代码库知识生成把产物拆成两个正交维度，这一点很关键：

1. 内容知识（按模块树组织）：每个模块提供什么能力、内部如何组织。回答"这里有什么"。
2. 规范知识（按横切主题组织）：构建、配置、日志、异常处理、测试等全仓约定。回答"在这里应该怎么写"。

为什么要分开？因为改一个功能，既要定位模块（内容知识），又要遵守全仓规范（规范知识）。混成一份文档，检索噪声会显著变大；拆开后各查各的，命中率更高，AI 引用时也更精准。

三、多仓：把隐性依赖变成显性资产

单仓知识化之后，多仓的痛点反而更突出：跨仓调用、共享库版本、业务流的完整链路。

跨仓分析的做法是：先对每个子仓生成知识文档与锚点，再扫描仓间关系，提取"谁依赖谁"的链接，并沉淀成业务流文档。

价值在于——过去跨仓改动靠"老师傅的记忆"和口头传承，现在变成一份可检索、可 review、可随代码演进的知识资产。新人接手时不必再从零考古。

四、落地流程（四步）

1. 界定范围：先明确要知识化的仓和目录。生成物目录（dist、构建产物、自动生成代码）必须排除——否则既污染知识，也会拖垮索引。这跟"索引文件数上限"是同一个根因，区别是这次要治本：在生成知识之前就用 ignore 清单把噪声挡在门外。
2. 生成单仓知识：产出模块/结构文档与锚点。
3. 提取跨仓依赖：汇总仓间链接，形成业务流文档。
4. 增量更新：代码变了，知识不能靠全量重刷。

五、增量更新才是能否长期使用的分水岭

一次性生成谁都能做，难的是"改完代码，文档不过期"。

增量的思路：记录变更文件 → 通过知识索引反查"哪些文档、哪些小节引用了这些文件" → 只重写受影响的部分，而非全文重生成。

这一步决定了知识库是"一次性玩具"还是"长期资产"。全量重刷的成本高到没人愿意坚持，最终文档必然腐烂。

六、几个边界

• 知识文档是地图，不是真相。关键路径仍要落到代码确认；地图与代码冲突时以代码为准。
• 不是所有仓都值得知识化。小仓、一次性脚本仓，直接读可能更快。
• 规范知识要"可执行"才有意义——最好能对应到 lint 规则、模板或 CI 检查，否则只是一段读起来很舒服的文字。

结语

从"索引到文件"到"知识到理解"，是从工具能力走向工程方法的一步。让 AI 先读懂再动手，省下的不只是搜索时间，更是那些"改了一处、以为没事、结果牵动三个仓"的隐性代价。