分解一座冰山:后端系统「AI 知识库体系」建设实践(长文干货)
01
在上一篇讨论《后端系统 AI Friendly 设计》时,文章开篇就强调过一个判断:后端系统要想真正进入 AI Friendly 状态,不能只停留在“代码写得清楚一点”、“README 多补一点”、“接口注释完整一点”这种层面。这些当然重要,但它们解决的更多是“人和 AI 能不能读懂局部代码”的问题,而不是“AI 能不能在一个复杂系统里做出正确的工程判断”。
真正的问题是:当 AI Agent 接到一个需求时,它到底知不知道这个系统的边界在哪里?知不知道哪些接口不能破坏兼容?知不知道这张表的某个字段虽然看起来没人用,但其实是下游离线任务每天凌晨要扫的?知不知道某个 MQ Topic 的 schema 不能随便改,因为三个历史服务还在消费老格式?知不知道某个模块虽然代码很旧,但它是交易链路里的关键兜底逻辑,动了之后不是单测过了就能上线?
这就是后端系统 AI Friendly 化真正麻烦的地方。
AI 不是完全看不懂代码,恰恰相反,今天的大模型读代码、解释代码、补测试、做局部修改,能力已经相当强了。问题在于,后端系统里的很多关键知识并不直接存在于代码中,或者虽然存在于代码中,但分散在不同仓库、不同配置、不同历史 PR、不同口头约定里。
人类工程师靠长期经验、团队沟通和线上事故记忆来补全这些上下文;AI Agent 没有这些“组织记忆”,它只能读取你明确给它的东西。
所以,“知识库怎么选”这个问题,表面上是工具选型,实际上是一个更底层的问题:我们到底要把哪些系统知识显式化,显式化之后又应该以什么形态交给 AI 使用?
如果只是为了新人 onboarding,一份自动生成的 Markdown Wiki 可能就够了。如果是为了跨服务影响分析、尤其是跨服务的技术方案设计,那就需要服务图谱、依赖关系、上下游调用链。
如果是为了让 AI 安全修改代码,那就还需要有明确的约束、红线、任务路由和验证标准。不同问题对应不同知识形态,不能混在一起讨论,更不能用一个“大而全知识库”幻想解决所有问题。
这也是本文想讨论的核心:后端系统 AI Friendly 化落地时,知识库怎么设计,如何有效利用这座知识的大山,挖出冰山藏在水下的 90% 部分,让 AI 从 coworker 真正走向 agentic operator。
02
2.1 为什么技术方案设计如此重要
在实践中反复面对的问题:无论是 CoWorker 形式的 AI Coding,还是 7x24小时AI 全自动规划的 Agentic Operator Coding ,在完整的研发流程中,技术方案设计是最关键的一环。方案质量直接决定了后续编码执行和交付的正确性。
这个判断可能看起来很传统。技术方案设计在没有 AI 的年代就很重要,这有什么新鲜的?新鲜之处在于:AI 时代放大了方案质量的杠杆效应,而且放大的倍数远超直觉。
一. AI 的执行速度放大了错误的传播速度:
一个人类工程师方向走偏,可能半天才写了几百行代码,拉个 PR 被同事 review 时就能被拉回来。损失可控。但一个 AI Agent 在错误方案的指引下,10 分钟可以完成一个涉及 5 个文件、3 个接口、2 张数据库表的完整变更。等你发现方向错了,回滚成本已经是人工编码的好几倍。更麻烦的是,这种错误往往不是语法错误,也不是单测一定能抓住的错误,而是“业务理解错了”“边界改错了”“兼容性破坏了”“下游影响漏了”。
二. AI 的默认行为是“忠实执行”,不是“质疑方案”:
给一个 senior 工程师一份有问题的需求,他会说“这里有矛盾”“这个方案会引入循环依赖”“你少考虑了并发场景”“这个接口以前不能这么改”。这种质疑能力是经验积累的结果。AI 当前不是完全没有质疑能力,它会在形式上指出一些明显的逻辑冲突,但对于那些需要系统全局理解才能发现的问题,比如“这个设计会导致下游服务超时”“这个字段看起来可删但其实影响离线对账”“这个状态机不能绕过人工审核”,它往往直接执行,而不是主动停下来质疑。
三. AI Coding 的核心价值是让 AI 处理执行细节。
但这个价值有一个隐含前提:执行方向必须正确。如果你把大量节省下来的编码时间,又花在 debug、回滚、返工、解释线上异常上,净效率提升可能趋近于零。很多团队反馈“用了 AI 好像也没快多少”,细究原因,往往不是 AI 编码能力差,可能在技术方案设计环节就没做好。AI 很高效地写了很多“局部正确但整体错误”的代码,最后人还是要花时间收拾残局。
2.2 技术方案设计强依赖知识库
所以,AI Coding 时代的技术方案设计,不只是“写一份方案文档”,而是要先让 AI 拥有足够准确的系统上下文,这个上下文就是知识库—— 完善的知识库建设。
知识库至少要能回答这些问题:
当前系统架构长什么样?模块怎么分?职责边界在哪里?这个需求涉及哪些上下游系统?接口契约是什么?改了会影响谁?数据库 schema 是什么?哪些字段有业务约束?哪些表之间有隐含依赖?有没有类似历史变更可以参考?上次改类似功能时踩了什么坑?什么是红线?哪些操作在任何情况下都不允许?
人类工程师靠经验、沟通和历史记忆来获取这些信息。AI 呢?它需要一个结构化的、精确的、可按需加载的知识来源。
此外,“业务元语”对应的已有技术链路、技术方案是什么,也是能够极大提升技术方案设计效率、准确性的输。我们管这一层叫做“业务层”,主要做业务与架构之间的转换、映射;
我们要做的不只是“让 AI 能看懂代码”,更需要“让 AI 在设计方案和执行变更时拥有正确、完整、可验证的系统上下文”。
这样就有两个问题显而易见:1. 知识库应该包含哪些内容?2. 知识库如何承载和加载?
2.3 知识库贯穿 AI Coding 全流程
在讨论「知识库 to 技术方案」之前,需要先把一个问题讲清楚:知识库并不是只在 AI 写代码之前用一下,也不是一个放在旁边、需要时搜索几段内容的 RAG 文档库。对于 AI Coding 来说,知识库应该贯穿从需求理解、现状分析、方案设计、编码执行、验证测试到 Review 交付的整个流程。
如果把 7x24小时的 AI/Agentic Coding 拆开来看,它其实不是“AI 自动写代码”这么简单。它至少包含几个连续动作:先理解需求,再识别业务概念,再找到这些业务概念对应的系统、模块、接口、表和消息;然后分析改动范围,判断影响哪些上下游;再形成技术方案,确定怎么改、改哪里、不改哪里;最后才进入编码、测试、Review 和交付。任何一个环节缺上下文,后面的执行都会变形。
在需求理解阶段:知识库帮助 AI 理解“业务元语”。比如需求里说“退款体验优化”“权益冻结”“履约异常补偿”“订单逆向链路”,这些词对业务同学来说是自然语言,但对 AI 来说,如果没有业务知识和业务到系统的映射,它只能按字面猜。它可能知道 refund 是退款,却不知道这个团队里的退款到底涉及订单状态、支付单状态、履约状态、财务对账、客服工单还是风控策略。业务层知识的价值,就是把这些业务词翻译成系统可以识别的技术对象和链路。
在现状分析和影响分析阶段:知识库帮助 AI 回到真实系统。一个需求到底改一个服务,还是改多个服务?是改接口,还是改状态机?是改同步链路,还是改异步消息?是否影响下游消费方?是否会破坏老版本客户端兼容?这些问题不能只靠 AI 看当前仓库回答。它需要架构层知识,需要服务依赖关系,需要上下游调用图谱,需要历史实践,也需要知道这个系统过去为什么这样设计。没有这些知识,AI 很容易做出“单仓库内看起来合理,但放到全链路里不合理”的方案。
在技术方案设计阶段:知识库的价值会被进一步放大。因为方案设计不是简单地列几个代码文件,而是要确定改动边界、数据流、状态流、兼容策略、异常处理、灰度方式和验证范围。这个阶段最怕的是 AI 给出一个形式完整但上下文错误的方案:文档看起来很像技术方案,里面也有接口、表结构、流程图和测试计划,但关键系统漏了,核心约束没提,下游影响没分析,历史兼容没考虑。这样的方案越完整,反而越危险,因为它会给后续编码执行制造一种“方向已经确定”的错觉。
在编码执行阶段:知识库不再只是帮助 AI “理解系统”,更是需要开始约束 AI “如何行动”。哪些目录可以改,哪些模块不能跨层调用,哪些字段不能删,哪些接口只能新增不能改语义,哪些状态流转必须保持幂等,哪些中间件使用方式必须遵守团队规范,这些都需要提前显式化。否则 AI 很容易写出功能上能跑、工程上却不符合系统规则的代码。
在验证测试阶段:知识库还要回答“怎么证明这次修改是安全的”。不同类型的改动,对应的验证方式不一样。新增 API 需要关注接口契约和兼容性;修改数据库需要关注迁移、回滚和历史数据;修改 MQ 消息需要关注生产者、消费者和重复消费;修改状态机需要关注主流程、逆向流程和异常分支。如果知识库里没有这些验证规则,AI 往往只会跑最容易跑的单测,然后给出一个“测试通过”的结论,但这个结论未必覆盖真正的风险。
所以,知识库在 AI Coding 里的角色,不应该被理解成“给 AI 搜索答案的资料库”,而应该理解成一套贯穿全流程的系统上下文。它既提供事实,也提供映射;既提供约束,也提供验证标准;既帮助 AI 理解业务和系统,也帮助 AI 在执行时不要越界。
更重要的是,知识库不是一次性输入,而应该形成闭环。每一次技术方案评审中发现的遗漏,每一次 Code Review 中指出的风险,每一次线上问题暴露出的隐性依赖,每一次历史兼容带来的特殊处理,都应该反向沉淀回知识库。否则知识库会很快变成一份“看起来完整、实际上过期”的文档,而 AI 最怕的不是没有上下文,而是拿到了错误的上下文。
因此,从 AI Coding 的角度看,知识库的作用贯穿全流程,但其中最关键的放大点,仍然是技术方案设计。因为需求理解、现状分析、影响分析、编码执行和验证测试,最终都会收敛到一个问题上:这次到底应该怎么改。技术方案一旦错了,后面所有高效执行都会变成高效返工。
那么知识库具体应该如何建设呢 ?具体目标是什么呢?
03
3.1 建设目标
知识库(knowledge base)在整个AI Coding 全链路中的建设目标,主要是基于其核心价值、影响范围来思考的,如果从典型的互联网架构思维来衡量的话,我认为主要有以下几个方面的指标可以用来衡量:
内容全面性:在做技术方案设计、AI Coding 的时候,知识库的内容是否足够全面。尤其面对后端有几十个微服务的前提下,知识库是否能反馈系统全貌,对于技术方案设计有非常大的作用。比如本来已经存在了一个微服务可以根据经纬度获取用户POI,如果知识库里漏掉了这一点,可能AI 就会重新设计开发一个同样的API;
内容准确性:知识库的内容准确性,在AI 时代已经被大幅提高了—— 大量的知识库都是依赖AI 生成,比人类自己的梳理提效了很多,准确性也提高了很多。但是仍然有一些痛点就是“技术元语定义重复”,比如“订单”—— 比如对于外卖系统来讲,用户创建的外卖单叫做订单,骑手接单的“配送单”也可以叫订单,二者本质上是两个不同实体。在提及订单的时候,到底是指哪一个订单呢?类似的歧义场景如何处理,也是很多时候落地要额外关注的。此外,在代码有变更后,知识库内容是否及时联动更新了,也是一个很重要的事情。
内容召回效率和质量:这个召回主要是指在技术方案调研、技术方案设计阶段,经常会涉及到跨多个代码仓库的知识召回等,这个时候召回准确率也和query 优化、召回引擎有很大关系。比如大模型的上下文窗口size 虽然有几百KB 甚至MB 级别,但实际上很多时候有效注意力往往集中在前几十个KB。
所以,知识库建设的目标需要紧密围绕上面几个方向展开。
3.2 知识库的分层设计
经过调研走访,我们发现很多团队在知识库建设层面、知识库做技术方案设计层面都有一些共性的挑战:
产品需求 to 技术链路转换瓶颈:产品的PRD 需求文档往往是以“用户界面”为切入点进行描述的,但是用户界面到后端API 还是需要一个转换过程—— 某一个界面请求了哪几个后端的关键API,分别用于渲染界面中的哪部分内容,这部分知识的缺失是阻碍“产品PRD文档 to 技术方案设计” 非常大的一个拦路虎;
跨越多层多系统时的系统事实与约束:在大型互联网项目中,往往一个用户请求要穿透多层后端微服务、对应每个微服务中也处理不同的逻辑。具体到本次需求,需要在哪一层的哪一个微服务中开发 —— 这就依赖大量的链路知识检索、架构约束、系统约束等知识。
知识检索增强RAG:大模型会话窗口 context length 是有限的,不可能把所有上下游系统的所有知识都放到一个context window 或者 session 中,也需要“按需加载”或者“只加载最相关的上下文” —— 大家经常用的 RAG 就是解决这一个问题的主要思路。在知识库的建设过程中,这个能力是基本能力之一。
单一系统内的知识全面性、抽象程度:在经历了上面几层业务转化、链路转化等过程之后,在实际的coding 阶段更依赖单一微服务系统内的知识库的质量。比如一个高质量的知识库,能够按照业界经典的DDD 或者三色建模法等经典方法论,把系统代码进行抽象,这除了解决优雅性问题以外,也能够把系统代码架构和约束、设计理念等大幅度可见,对AI coding 是非常有帮助的。
针对这些大家遇到的现状和问题,我们在设计和实践过程中,把知识库进行了分层,倾向于拆成如下四层:业务层、架构层、系统层、基建层。
其中蓝色背景框部分,是性价比比较高的模块,适合越早投入见效越快的模块。其中蓝色背景框部分,是性价比比较高的模块,适合越早投入见效越快的模块。
3.2.1 业务层:让 AI 知道“为什么改”和“业务落在哪里”
业务层是最容易被技术团队低估的一层。很多人讨论 AI Coding,会直接从代码仓库、接口文档、数据库表开始,但真实的研发过程不是从代码开始的,而是从业务问题开始的。
业务层至少包含三类知识:业务知识、业务与架构映射、历史实践。
业务知识:解决的是“这个系统到底在服务什么业务”的问题。比如订单、支付、履约、权益、库存、风控、对账,这些业务概念分别是什么意思,有哪些核心规则,哪些状态变化是正常的,哪些操作是高风险的。如果 AI 只看代码,它也许能读懂
order_status有几个枚举值,但它未必知道“已支付未履约”在业务上意味着什么,也未必知道某个状态为什么不能直接跳转。业务与架构映射:解决的是“业务概念最终落在哪些系统、模块、接口、表和消息上”的问题。这一块非常关键,也是很多知识库最容易缺失的地方。一个需求说“优化退款体验”,听起来是业务需求,但落到系统上,可能涉及订单服务、支付服务、履约服务、客服系统、财务对账、消息通知、风控策略都有和退款相关的能力支持,退款操作的业务流程对应到技术系统,首先请求的API 是什么?对应的同步API 是什么?异步API 是什么?AI 如果不知道这些映射关系,就很容易把一个跨系统需求误判成单服务局部修改。
历史实践:解决的是“过去为什么这么做”的问题。比如对于一个平台化系统,每次做新的定制能力接入的时候,开发的代码基本都是类似的分层、类似的模块,用历史实践的方式沉淀技术方案,给AI 作为参考,针对同类问题就可以很高效的产出技术方案、降低技术方案的影响风险等。比如还有很多后端系统里都有一些看起来不优雅的设计:一个多余的字段、一段兼容老逻辑的代码、一个特殊的兜底判断、一个不能删除的 MQ 消费分支。新人容易觉得它脏,AI 更容易觉得它可以被重构掉。但这些东西背后可能是历史事故、灰度兼容、老版本客户端、下游依赖、合规要求或者业务妥协。
这也是为什么我觉得业务层里的“业务与架构映射”和“历史实践”值得重点标出来。它们往往不在代码里,不在自动生成文档里,也不在接口定义里,但它们直接影响技术方案设计是否正确。
3.2.2 架构层:让 AI 知道“系统之间怎么协作”
架构层解决的是系统之间的分工、调用、依赖和治理问题。它包括 架构 / 分层 / 链路事实、架构约束、服务治理。
架构 / 分层 / 链路事实,回答的是“系统怎么组织”的问题。比如一个业务链路从网关进入后,会经过哪些服务;每个服务负责什么;哪些是核心链路,哪些是旁路链路;哪些模块属于领域层,哪些属于应用层,哪些只是适配层;哪些接口是同步调用,哪些是异步消息;哪些数据是强一致,哪些数据允许最终一致。
架构知识/事实:对技术方案设计非常重要。因为 AI 如果只看当前仓库,很容易出现“局部最优”的方案:在当前服务里改起来很顺,但放到整体链路里就不合理。比如某个逻辑应该在订单服务里做,AI 却改到了网关层;某个校验应该靠领域对象保证,AI 却散落在多个 Controller 里;某个异步链路应该通过 MQ 解耦,AI 却新增了一个同步 RPC 调用。这些问题不是代码能力问题,而是架构上下文不足。
架构约束:回答的是“系统设计上不允许怎么做”的问题。比如核心链路不能新增强依赖,交易链路不能引入不稳定外部服务,某些接口只能由聚合服务调用,某些服务不能反向依赖上游,某些数据只能通过领域事件同步,不能跨库直查。架构约束和代码规范不一样,它约束的是系统之间的关系和依赖方向。
服务治理:更偏运行时和组织治理。比如服务等级、超时配置、重试策略、熔断降级、限流规则、接口负责人、依赖 owner、SLA、灰度策略、监控告警。这些信息不一定直接影响代码怎么写,但会影响方案能不能上线、风险是否可控、出了问题能不能快速定位。
从选型角度看,需要有一个架构层来理解系统之间的关系,比如通过服务图谱、上下游依赖、接口调用、项目元数据,帮助 AI 和工程师回答“改这个服务会影响谁”“有没有现成能力可以复用”“这个接口被哪些上游调用”。这类知识不是普通 CodeWiki 最擅长的,因为它跨越了单个仓库,需要从微服务生态里看关系。
所以,架构层的核心价值不是解释代码,而是帮助 AI 做影响分析和服务寻址。它决定了技术方案设计的前半段是否靠谱:需求到底应该改哪些系统,影响哪些上下游,边界应该切在哪里。
3.2.3 系统层:让 AI 知道“这个服务内部怎么改才安全”
系统层是单个服务内部最核心的 AI Friendly 知识层。它包括 系统事实、系统约束、验证 / 测试。
系统事实:解决的是“这个服务内部有什么”的问题。比如模块划分、核心领域对象、主要 API、数据库表、缓存 Key、MQ Topic、定时任务、核心流程、状态机、配置项。这些信息是 AI 理解单个仓库的基础。没有系统事实,AI 就只能在代码里临时搜索,看到哪改哪,很难形成完整判断。
系统约束:解决的是“这个服务内部什么不能随便改”的问题。比如 public API 字段不能删除,数据库字段只能新增不能改语义,某个状态机流转必须经过特定校验,某个历史兼容逻辑不能删除,某个模块禁止大规模重构,某些目录只能通过适配层访问,某些写操作必须保证幂等。系统约束是 AI Coding 中最关键、也最容易缺失的知识。
历史实践:在单个系统内,历史做某一类型的需求,主要使用什么方案,这对AI 做技术方案设计有非常大的参考意义。在事实层面,和“业务层”的历史实践是一样的意义,只是辐射的scope 不同;
验证 / 测试:解决的是“怎么证明改对了”的问题。很多 AI 修改代码的问题,不是完全不能跑,而是验证方式太弱。新增接口要不要契约测试?修改数据库要不要迁移验证?改状态机要不要跑核心流程用例?改 MQ schema 要不要验证生产者和消费者兼容?改缓存逻辑要不要验证穿透、击穿和失效策略?这些都需要明确。否则 AI 很可能只跑了几个单测,就以为任务完成了。
这一层里,CodeWiki 和 service-knowledge-generate 都有价值,但侧重点不同。
CodeWiki 更适合生成和维护系统事实。它能低成本把项目概览、模块说明、API、数据模型、核心流程自动整理出来,帮助人和 AI 快速理解系统。
service-knowledge-generate 更适合把系统约束和验证规则结构化。它不只是告诉 AI “这个系统是什么”,还要告诉 AI “面对某类任务必须读哪些上下文、哪些地方不能动、做完以后必须怎么验证”。所以它不是 CodeWiki 的简单替代,而是更偏 AI 执行阶段的约束型知识库。
这也是为什么图里把“系统事实”和“系统约束”放在一起重点标出来。单个服务内部的 AI Friendly 化,最关键的不是把所有代码都解释一遍,而是把“事实 + 约束 + 验证”这三件事组织好。AI 只有知道系统事实,才能理解怎么改;只有知道系统约束,才能知道不能怎么改;只有知道验证方式,才能证明改动是安全的。
3.2.4 基建层:让 AI 知道“底座规则是什么”
基建层是很多文章里容易被一笔带过的部分,但在后端系统里,它其实非常重要。它包括 中间件知识、代码规范约束、工程规范等。
中间件知识:对于常见的 Redis、Kafka 等中间件基础使用知识,当前很多大模型都已经进行了内化,所以这些开源或者行业标准级别的中间件知识不太需要放到知识库中。这里知识库中的中间件知识指的是团队如何使用数据库、Redis、Kafka、RocketMQ、ES、配置中心、注册中心、任务调度、对象存储、日志监控等基础设施。这里不只是“Redis 是什么”“Kafka 怎么用”这种通用知识,而是本团队、本系统里的使用约定。比如 Redis Key 怎么命名,缓存过期时间怎么设,是否允许缓存空值,MQ Topic 命名规则是什么,消息是否要求幂等,数据库分库分表规则是什么,大字段能不能进主表,慢查询阈值是多少。
代码规范约束:解决的是“代码应该按什么方式组织”的问题。比如分层结构、命名规范、异常处理方式、日志规范、DTO / DO / Entity 的边界、依赖注入方式、事务边界、单测目录、Mock 方式。这些知识看起来比较底层,但它直接影响 AI 生成代码是否符合团队风格。如果没有这层约束,AI 很容易写出“功能能跑,但不像这个团队写的代码”。
工程规范:内容更广,包括依赖管理、发布流程、配置变更、灰度要求、安全扫描、监控埋点、报警规则、回滚策略等。这些东西可能不在业务代码里,却决定了代码能不能安全上线。对于这部分建设,不同规模的互联网公司或者软件公司可以有自己的适配标准。大型互联网公司对于稳定性、标准化要求高并能够适度接受迭代效率的降低,则规范类要求会更强更多;而中小型互联网公司对于业务迭代效率要求更高,反而在稳定性、标准化要求可能会更低,则工程规范类要求可能相对偏少。选择适合自己企业、业务复杂度的建设标准即可。
基建层的价值在于,它给 AI 提供工程底座。AI 不是只要写出业务逻辑就算完成任务,它写出的代码还要符合团队工程习惯,符合中间件使用方式,符合发布和运维要求。尤其是在大型互联网系统里,很多线上问题并不是业务逻辑错了,而是超时、重试、缓存、消息幂等、数据库性能、日志监控这些底座规则没处理好。
04
4.1 Ontology 本体论
在我们做知识库方案调研的时候,首先去了解了一下业界比较前沿或者在AI 领域比较领先的企业方案。
Palantir 推崇了 Ontology (本体论)的方法论,如下图。
更多内容可见 Palantir 官网对于 ontology 的一些论述设计: https://www.palantir.com/docs/foundry/ontology/overview
注:此配图来自 Palantir 官网
Ontology(本体)的概念并不新,几十年前就有了,也不是软件工程独有,主要是用来定义领域知识的体系化描述的。在软件工程/AI 领域指对特定领域概念、属性及关系的形式化、显式且可共享的规范说明,…