
00 一个不算罕见的翻车现场
设想这样一幕。
周三下午,你给 AI Agent 提了个需求:「给订单增加一个『延迟发货赔付』状态」。12 分钟后,它交出一份漂亮的 diff:改了 5 个文件、3 个接口、2 张表,单测全绿,PR 描述写得比你自己写的还清楚。
你合了。
周五凌晨,财务对账任务炸了。
原因很朴素:订单状态枚举新增之后,离线数仓的 ETL 按老的枚举白名单过滤,新状态的单子全被丢掉了。而这条依赖,代码里没有任何痕迹,它活在两年前一次故障复盘的会议纪要里,活在数仓同学的脑子里。
AI 没有写错代码。它只是不知道这东西的存在。
这篇文章,就是想把这类问题彻底讲透。
01 真正的门槛,从来不是「让 AI 看懂代码」
之前我强调过一个判断:把 README 写厚一点、注释补全一点、接口文档写规范一点,解决的是「人和 AI 能不能读懂这段局部代码」,而不是「AI 能不能在一个复杂系统里做出正确的工程判断」。
这两件事的难度,差着一个数量级。
今天的大模型读代码、解释代码、补测试、做局部重构,能力已经相当强了。真正的麻烦在于:后端系统里最关键的那部分知识,压根不在代码里,或者虽然在代码里,却分散在不同仓库、不同配置、不同历史 PR、不同口头约定中。
- 这张表的某个字段看着没人用,其实下游离线任务每天凌晨要扫;
- 这个 MQ Topic 的 schema 不能随便改,因为还有三个历史服务在消费老格式;
- 这个模块代码很旧,但它是交易链路里的关键兜底逻辑,单测过了也不代表能上线;
- 这个接口只能新增字段、不能改语义,因为老版本客户端还在跑。
人类工程师靠什么补全这些?靠长期经验、靠群里问一句、靠「上次就是这么炸的」的肌肉记忆。这些东西有个统一的名字:组织记忆。
AI Agent 没有组织记忆。它只能读取你明确给它的东西。
所以「知识库怎么选」这个问题,表面上是工具选型,实际上是一个更底层的追问:
我们到底要把哪些系统知识显式化?显式化之后,又该以什么形态交给 AI 使用?
答案不唯一,取决于你要解决什么问题:
- 只是为了新人 onboarding → 一份自动生成的 Markdown Wiki 可能就够了;
- 为了跨服务影响分析和方案设计 → 你需要服务图谱、依赖关系、上下游调用链;
- 为了让 AI 安全地改代码 → 你还需要明确的约束、红线、任务路由和验证标准。
不同目标对应不同的知识形态,不能混在一起讨论。最危险的做法,是幻想用一个「大而全知识库」解决所有问题。




