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 安全地改代码 → 你还需要明确的约束、红线、任务路由和验证标准。
不同目标对应不同的知识形态，不能混在一起讨论。最危险的做法，是幻想用一个「大而全知识库」解决所有问题。
02 为什么技术方案设计是决胜环节
在 AI 出现之前，技术方案设计就很重要。这话听起来像正确的废话。
新鲜的地方在于：AI 时代放大了方案质量的杠杆效应，而且放大倍数远超直觉。
具体是三个放大器。
放大器一：错误的传播速度，等于执行速度
人类工程师方向走偏，半天写几百行，拉个 PR 被同事 review 一顿就拉回来了，损失可控。
AI Agent 在错误方案的指引下，10 分钟就能完成一个涉及 5 个文件、3 个接口、2 张数据库表的完整变更。等你发现方向错了，回滚成本已经是人工编码的好几倍。
更麻烦的是错误的类型。这类错误往往不是语法错误，也不是单测一定能抓住的错误，而是：
- 业务理解错了
- 边界改错了
- 兼容性破坏了
- 下游影响漏了
这四种，单测全绿。
放大器二：AI 的默认行为是「忠实执行」，不是「质疑方案」
给一个 senior 工程师一份有问题的需求，他会停下来说：「这里有矛盾」、「这个方案会引入循环依赖」、「你少考虑了并发场景」、「这个接口以前不能这么改」。这种质疑能力，是经验积累的结果。
AI 不是完全没有质疑能力，它能指出形式上明显的逻辑冲突。但对于那些需要系统全局理解才能发现的问题：「这个设计会导致下游服务超时」、「这个字段看起来可删但其实影响离线对账」、「这个状态机不能绕过人工审核」，它往往直接开干，而不是主动停下来。
放大器三：AI Coding 的价值，有一个隐含前提
AI Coding 的核心价值是让 AI 处理执行细节。但这个价值成立有个前提：执行方向必须正确。
如果你把大量节省下来的编码时间，又花在 debug、回滚、返工、解释线上异常上，净效率提升可能趋近于零。
很多团队反馈「用了 AI 好像也没快多少」。细究原因，往往不是 AI 编码能力差，而是在技术方案设计环节就没做好，AI 非常高效地写了一大堆「局部正确但整体错误」的代码，最后还是人来收拾残局。
一句话总结：
方案对了，AI 是加速器；方案错了，AI 是放大器。
03 知识库不是「给 AI 查资料的地方」
这里要先纠正一个很常见的误解。
很多人理解的知识库，是放在旁边、需要时 RAG 搜几段塞进 context 的文档库。这个理解太窄了。
把 7×24 小时的 Agentic Coding 拆开看，它其实不是「AI 自动写代码」这么简单，而是至少六个连续动作。任何一个环节缺上下文，后面的执行都会变形。
| 阶段 | 知识库提供什么 | 缺了会怎样 |
| 需求理解 | 业务元语 | 按字面猜业务词 |
| 现状分析 | 系统链路 | 只看单仓库，全链路不合理 |
| 方案设计 | 改动范围 | 形式完整、上下文错误 |
| 编码执行 | 安全边界 | 能跑，但不符合系统规则 |
| 验证测试 | 验证规则 | 只跑最容易跑的单测 |
| Review 交付 | 经验沉淀 | 同一个坑踩第二次 |
展开说几个关键的。
需求理解阶段，知识库负责「翻译」。需求里写「退款体验优化」、「权益冻结」、「履约异常补偿」、「订单逆向链路」，这些词对业务同学是自然语言，对 AI 是黑话。它知道 refund 是退款，但不知道你们团队的退款到底牵扯订单状态、支付单状态、履约状态、财务对账、客服工单，还是风控策略。业务层知识的价值，就是把业务词翻译成系统可识别的技术对象和链路。
方案设计阶段最怕一种东西：形式完整但上下文错误的方案。文档看起来非常像技术方案：有接口、有表结构、有流程图、有测试计划，但关键系统漏了，核心约束没提，下游影响没分析，历史兼容没考虑。
这样的方案越完整，反而越危险，因为它会给后续编码执行制造一种「方向已经确定」的错觉。
编码执行阶段，知识库的角色从「解释」变成「约束」。哪些目录可以改，哪些模块不能跨层调用，哪些字段不能删，哪些接口只能新增不能改语义，哪些状态流转必须保持幂等，哪些中间件用法必须遵守团队规范，这些都需要提前显式化。
验证阶段，知识库要回答「怎么证明这次修改是安全的」。不同类型的改动对应不同验证方式：新增 API 关注接口契约和兼容性；改数据库关注迁移、回滚和历史数据；改 MQ 消息关注生产者、消费者和重复消费；改状态机关注主流程、逆向流程和异常分支。没有这些规则，AI 会跑几个最容易跑的单测，然后给出一个「测试通过」的结论，而这个结论未必覆盖真正的风险。
最后一条，也是最容易被忽略的：知识库必须形成闭环。
每一次方案评审发现的遗漏、每一次 Code Review 指出的风险、每一次线上问题暴露的隐性依赖、每一次历史兼容带来的特殊处理，都应该反向沉淀回知识库。否则它会迅速变成一份「看起来完整、实际上过期」的文档。
而这正是最危险的地方：
AI 最怕的不是没有上下文，而是拿到了错误的上下文。
所以，知识库的作用贯穿全流程，但最关键的放大点仍然是技术方案设计。因为需求理解、现状分析、影响分析、编码执行和验证测试，最终都收敛到同一个问题上：这次到底应该怎么改。
技术方案一旦错了，后面所有的高效执行，都会变成高效返工。
04 四层分层：业务层 / 架构层 / 系统层 / 基建层
调研走访了不少团队后，我们发现大家卡住的地方高度相似：
- PRD 到技术链路的转换断层：产品文档以「用户界面」为切入点，但界面到后端 API 之间缺一层映射——某个页面请求了哪几个关键 API，分别渲染哪部分内容？这部分知识的缺失，是「PRD to 技术方案」最大的拦路虎。
- 跨多层系统的事实与约束缺失：一个用户请求穿透好几层微服务，每层处理不同逻辑。这次需求到底该在哪一层的哪个服务里改？
- 上下文长度是硬约束：不可能把所有上下游知识都塞进一个 window，必须「按需加载」、「只加载最相关的上下文」。
- 单服务内部的抽象质量：真到 coding 阶段，拼的是单个微服务知识库的质量，能不能按 DDD 或三色建模这类方法论把系统代码抽象出来，把架构、约束、设计理念大幅可见。
针对这些问题，我们把知识库拆成四层。
这里之所以用「中台」这个词，不是为了蹭概念，而是因为它准确描述了这套东西的形态：同一份知识，被多个需求、多个 Agent、多个研发阶段反复调用；沉淀一次，复用无数次。 它和当年的业务中台解决的是同一类问题，只不过服务对象从「前台业务」换成了「AI Agent」。
四层可以先记住一句话：
业务层管「为什么改」，架构层管「改哪些系统」，系统层管「服务内部怎么改才安全」，基建层管「底座规则是什么」。
4.1 业务层：让 AI 知道「业务落在哪里」
这是最容易被技术团队低估的一层。
很多人讨论 AI Coding，张口就是代码仓库、接口文档、数据库表，但真实的研发过程不是从代码开始的，是从业务问题开始的。
业务层至少包含三类知识。
① 业务知识：订单、支付、履约、权益、库存、风控、对账分别是什么意思，有哪些核心规则，哪些状态变化正常，哪些操作高风险。
AI 只看代码，能读懂 order_status 有几个枚举值，但未必知道「已支付未履约」在业务上意味着什么，更不知道某个状态为什么不能直接跳转。
② 业务与架构映射：这是最关键、也最容易缺失的一块。
「优化退款体验」听起来是纯业务需求，落到系统上可能涉及订单服务、支付服务、履约服务、客服系统、财务对账、消息通知、风控策略，每一个都有和退款相关的能力支持。退款流程对应到技术系统，首先请求哪个 API？同步链路是什么？异步链路是什么？
AI 不知道这层映射，就很容易把一个跨系统需求误判成单服务局部修改。
③ 历史实践：回答「过去为什么这么做」。
这里要特别说一下。几乎每个后端系统里都躺着一些看起来不优雅的设计：一个多余的字段、一段兼容老逻辑的代码、一个特殊的兜底判断、一个不能删除的 MQ 消费分支。
新人容易觉得它脏，AI 更容易觉得它可以被重构掉。
但这些东西背后，可能是历史事故、灰度兼容、老版本客户端、下游依赖、合规要求或者业务妥协。
另一个价值是复用：对于平台化系统，每次接入新的定制能力，代码基本都是类似的分层、类似的模块。用历史实践的方式沉淀技术方案给 AI 作参考，同类问题就能高效产出方案、降低方案风险。
「业务与架构映射」和「历史实践」这两块值得重点圈出来：它们往往不在代码里，不在自动生成文档里，也不在接口定义里，但它们直接决定技术方案设计是否正确。
4.2 架构层：让 AI 知道「系统之间怎么协作」
架构层解决的是系统之间的分工、调用、依赖和治理。
① 架构 / 分层 / 链路事实：一个业务链路从网关进来会经过哪些服务；每个服务负责什么；哪些是核心链路、哪些是旁路；哪些模块属于领域层、应用层、适配层；哪些接口同步、哪些异步；哪些数据强一致、哪些允许最终一致。
缺了这层，最典型的症状是「局部最优」：
- 某个逻辑应该在订单服务做，AI 改到了网关层；
- 某个校验应该靠领域对象保证，AI 散落在多个 Controller 里；
- 某个链路应该通过 MQ 解耦，AI 新增了一个同步 RPC 调用。
这些不是代码能力问题，是架构上下文不足。
② 架构约束：回答「系统设计上不允许怎么做」。核心链路不能新增强依赖；交易链路不能引入不稳定外部服务；某些接口只能由聚合服务调用；某些服务不能反向依赖上游；某些数据只能通过领域事件同步、不能跨库直查。
注意，架构约束和代码规范是两回事：代码规范约束代码怎么写，架构约束约束的是系统之间的关系和依赖方向。
③ 服务治理：服务等级、超时配置、重试策略、熔断降级、限流规则、接口负责人、依赖 owner、SLA、灰度策略、监控告警。这些不直接影响代码怎么写，但决定了方案能不能上线、风险是否可控、出了问题能不能快速定位。
一句话：
架构层的核心价值不是解释代码，而是做影响分析和服务寻址。
它决定技术方案的前半段靠不靠谱，需求该改哪些系统、影响哪些上下游、边界切在哪里。这类知识普通 LLM Code Wiki 是不擅长的，因为它跨越了单个仓库，必须从微服务生态里看关系。
4.3 系统层：让 AI 知道「这个服务内部怎么改才安全」
单个服务内部最核心的 AI Friendly 知识层，就三件事：事实、约束、验证。
① 系统事实：模块划分、核心领域对象、主要 API、数据库表、缓存 Key、MQ Topic、定时任务、核心流程、状态机、配置项。没有系统事实，AI 只能在代码里临时搜索，看到哪改哪，很难形成完整判断。
② 系统约束：public API 字段不能删除；数据库字段只能新增不能改语义；某个状态流转必须经过特定校验；某段历史兼容逻辑不能删；某个模块禁止大规模重构；某些目录只能通过适配层访问；某些写操作必须保证幂等。
这是 AI Coding 中最关键、也最容易缺失的知识。
③ 历史实践：单个系统内，历史上某一类需求主要用什么方案。和业务层的历史实践是同一件事，只是辐射的 scope 不同。
④ 验证 / 测试：很多 AI 改代码的问题不是「完全跑不起来」，而是验证方式太弱。新增接口要不要契约测试？改数据库要不要迁移验证？改状态机要不要跑核心流程用例？改 MQ schema 要不要验证生产者和消费者兼容？改缓存逻辑要不要验证穿透、击穿和失效策略？
不写清楚，AI 跑几个单测就以为任务完成了。
记住这个三段式：
知道系统事实，才能理解怎么改； 知道系统约束，才知道不能怎么改； 知道验证方式，才能证明改动是安全的。
4.4 基建层：让 AI 知道「底座规则是什么」
这一层在很多文章里被一笔带过，但在后端系统里非常重要。
① 中间件知识：注意，不是「Redis 是什么」、「Kafka 怎么用」。这类开源或行业标准级的通用知识，大模型早就内化了，不需要往知识库里塞。
要写的是本团队、本系统的使用约定：Redis Key 怎么命名，缓存过期时间怎么设，是否允许缓存空值，MQ Topic 命名规则是什么，消息是否要求幂等，分库分表规则是什么，大字段能不能进主表，慢查询阈值是多少。
② 代码规范约束：分层结构、命名规范、异常处理方式、日志规范、DTO / DO / Entity 的边界、依赖注入方式、事务边界、单测目录、Mock 方式。
这些看着底层，但直接决定 AI 生成的代码像不像你们团队写的代码。没有这层约束，AI 很容易写出「功能能跑，但不像这个团队写的」的代码。
③ 工程规范：依赖管理、发布流程、配置变更、灰度要求、安全扫描、监控埋点、报警规则、回滚策略。这些可能不在业务代码里，却决定了代码能不能安全上线。
这里给个务实建议：基建层的标准要匹配公司体量。大型互联网公司对稳定性和标准化要求高、能接受一定的迭代效率损失，规范可以厚；中小公司迭代效率优先，规范薄一点反而合理。别照抄大厂的清单。
基建层的价值在于给 AI 提供工程底座。大型系统里很多线上问题并不是业务逻辑错了，而是超时、重试、缓存、消息幂等、数据库性能、日志监控这些底座规则没处理好。
05 落地：每一层到底长什么样
分层讲完，下面是更实在的部分，每层用什么承载、文件长什么样。
5.1 先看一眼业界：Palantir 的 Ontology
调研阶段，我们先看了 Palantir 推崇的 Ontology（本体论）方法论。
Ontology 这个概念不新，几十年前就有，也不是软件工程独有。在软件工程 / AI 语境下，它指对特定领域概念、属性及关系的形式化、显式且可共享的规范说明，是构建知识图谱、实现机器推理与语义互操作的「语义骨架」。
它常被描述成「企业数字孪生」，这个说法太大，也太容易误导。更准确的理解是：
Ontology 定义了一种协议，让系统把自己的业务对象、属性、关系、动作和权限，以统一方式暴露出来。
四类核心要素：
- Data：每个系统贡献自己的数据，映射为对象、属性和链接。订单是对象，金额 / 支付状态 / 创建时间是属性，订单与用户、商家、履约单的关系是链接。
- Logic：业务规则、模型、算法、计算逻辑绑定到对象上。AI 不只看到「订单」，还知道围绕订单有哪些计算能力，比如风险评估、库存预测、履约优化。
- Action：决策执行被建模为原子化操作，支持模拟、审批和写回。也就是说，Ontology 不只让 AI 读系统，还让 AI 知道这个业务世界里可以做哪些动作。
- Security：权限不是事后补丁，而是和对象、属性、动作绑定在一起。不同人、不同 Agent、不同场景，能看什么、改什么、执行什么，都有动态控制。
对我们启发最大的是这一句：
如果每个系统都按同一种结构暴露自己的能力，那么跨系统的发现、组合、编排，就从一个私有 API 适配问题，变成了标准化建模问题。
对比一下就很清楚：
- 传统 API 文档告诉 AI：「这个接口怎么调」。
- Ontology 告诉 AI：「这个业务世界里有哪些对象，对象之间什么关系，对象上允许做哪些动作，动作执行前要满足什么权限和约束」。
Wiki 偏解释系统，Ontology 偏建模系统；Wiki 偏阅读，Ontology 偏行动。
顺带厘清一个常被混用的概念：
| 维度 | 本体（Ontology） | 知识图谱（Knowledge Graph） |
| 层级 | 模式层（Schema），定规则的骨架 | 实例层（Data），存事实的血肉 |
| 内容 | 定义概念、关系、逻辑约束 | 存储海量具体实体及关系三元组 |
| 核心能力 | 语义消歧、逻辑推理、一致性校验 | 关联查询、路径分析、可视化检索 |
| 类比 | 建筑设计图 / 语法书 | 建成的大楼 / 词典例句 |
5.2 业务层落地：一套可以直接抄的目录结构
业务知识库不应该只是业务文档的堆积，它要帮 AI 完成从产品需求、业务场景到技术链路的转换，理解业务元语、识别业务边界、定位相关系统，并在方案设计时拿到必要的历史经验和设计约束。
我们的做法是按业务域（Business）组织，每个域一套结构：
business/
├── index.md # 业务域总览入口
├── meta/
│ └── index.md # 业务元语：核心对象、概念边界、关键规则
├── principle/
│ ├── index.md # 设计原则总览
│ ├── timeout.md # 超时策略
│ ├── idempotency.md # 幂等性规范
│ ├── consistency.md # 一致性策略
│ ├── degradation.md # 降级预案
│ └── compatibility.md # 兼容性规范
├── scenario/
│ ├── index.md # 场景索引与路由
│ └── scenario-*.md # 具体业务场景文档
├── practice/
│ ├── index.md # 实践案例总览
│ └── practice-*.md # 具体实践 / 方案文档
└── history/
└── history-YYYYMMDD.md # 按日期归档的变更 / 决策记录五个目录，各管一件事。
- meta ：业务元语，解决歧义
存领域内的核心业务对象、概念边界和关键业务规则。这个目录解决的是一个非常现实的痛点：技术元语定义重复。
举个例子：外卖系统里，用户创建的外卖单叫「订单」，骑手接的「配送单」也有人叫订单。二者本质上是两个不同实体。当需求文档里出现「订单」两个字，到底指哪一个？
所以每个业务元语要有稳定的名称或标识，并说明：定义、别名、非同义词、业务边界、关联概念、核心规则。
「非同义词」这一栏尤其值得写，它是消歧的关键。
元语数量通常不多，初期集中维护在 meta/index.md 就够，领域复杂了再拆。
- principle ：跨场景复用的设计原则
它描述的不是某个具体页面或接口的调用链，而是架构师在这个领域长期坚持的关键考虑：
- 全链路超时预算如何分配；
- 多系统之间采用何种一致性与补偿策略；
- 哪些链路允许降级，哪些链路必须失败；
- API、消息和状态语义如何保持向后兼容；
- 核心链路和旁路链路如何划分；
- 状态聚合和展示状态应遵循哪些原则。
比如订单列表页和详情页：商品图片、营销标签这类信息可以降级，而订单主体信息属于不可降级的核心数据。这类原则如果分散写在每个场景里，既造成重复，也容易在长期维护中不一致。抽象到 principle，再由不同场景引用。
注意边界：principle 只承载当前业务域特有的、跨场景复用的原则。数据库、Redis、MQ、日志、发布流程这些公司或团队级通用规范，应该沉在基建层，避免每个业务域重复维护一套。
- scenario：业务场景到技术链路的转换核心
这是整个业务层最有价值的目录。
场景从用户 / 产品 / 业务视角出发：订单列表页、订单详情页、退款详情页、提交订单页，或者一个不依赖具体页面的完整业务使用场景。
每个场景先写业务目标、使用者、展示内容和业务边界，然后拆解到具体功能和用户操作。以订单列表页为例，可能包含：查询和展示订单列表、点击进入详情、删除订单、再次购买、申请退款。
针对每一项操作，继续往下写：
业务语义 → 前置条件 → 客户端请求的 API → 网关和聚合服务入口 → 内部领域服务调用链路 → 涉及的下游系统 → 数据变化 → 同步和异步事件 → 异常、降级和补偿方式 → 关联的
meta、principle和历史实践
举个具体的：「删除订单」在产品界面上只是一个按钮，但业务语义上通常不代表物理删除，而是把订单从当前用户的列表中隐藏。
于是场景文档必须写清：客户端请求哪个 API，订单服务如何校验订单归属和状态，是否需要查询退款及履约状态，最终修改的是订单主表还是用户与订单的展示关系，以及客服、对账和离线数据是否仍然能查到这单。
这样一来，scenario 实际上建起了一条完整的转换链路：
产品页面或业务场景
↓
页面功能和用户操作
↓
业务语义与前置条件
↓
客户端 API
↓
网关或聚合服务
↓
内部领域服务
↓
下游系统、数据与消息这条链路，就是「PRD 到技术方案」断层的填充物。
拆分策略上：场景较少（比如少于 20 个）、内容较轻时，可以都放在一个文件里；场景变多，或某个场景更新频繁、被独立引用、有独立 Owner，就拆成单文件，由 index.md 维护场景名称、业务关键词、核心功能和链接。
别把「20 个」当成硬标准，真正的判断依据是文件大小、内容复杂度、更新频率和独立引用需求。
- practice 历史实践，回答「为什么」
它关注的不只是「过去做过什么」，更重要的是解释「过去为什么这样做」、「哪些经验可以复用」「哪些坑不能再踩」。
内容可以包括：
- 某类需求的标准改造模式；
- 某次重要架构或业务决策；
- 历史兼容设计；
- 线上事故暴露出的隐性约束；
- 某类需求通常会影响的系统范围；
- 某种方案适用和不适用的条件。
回到开头那个翻车案例：新增一种订单状态时，历史实践会提醒 AI，除了修改订单服务状态机，还要检查客户端状态映射、客服系统、消息消费者、离线数仓和对账逻辑。
实践知识的价值不只是提供一个可复制的旧方案，而是帮 AI 判断某个历史方案在当前场景下是否仍然适用。
- history 知识库自身的变更日志
记录某天由谁、通过哪个 Skill、基于哪些资料生成或更新了哪些文件，经过谁的审核，以及当前还有哪些未确认事项。
务必区分 practice 和 history：
- practice 承载对未来技术方案仍有指导意义的业务和架构知识；
- history 只记录知识库本身何时、由谁、以什么方式发生了变化。
history 里保存的应该只是 log，不是知识本身。
文件格式：Markdown + YAML Front Matter
我们倾向于用带索引结构的 Markdown。它对产品、业务、研发和架构师都友好，也便于人工审核和持续修正。同时在文件头部加 YAML Front Matter，描述结构化信息：
---
id: scenario.order-list-page
type: business_scenario
domain: order
owner: order-domain-team
status: verified
related_meta:
- trade_order
related_principles:
- timeout
- degradation
updated_at: 2026-07-15
---正文继续用 Markdown 描述业务背景、流程、调用链和设计考虑。这样既保留了对人类的可读性，也为 AI 的检索、路由、过滤和按需加载提供了必要的结构化信息。
一句提醒：目录名不重要，能回答问题才重要
上面这套结构是我们结合实际建设过程给出的参考实践，不是标准。
不同团队的业务复杂度、文档体系、系统架构和 AI Coding 工作流都不一样：有的适合以页面场景组织，有的适合以用户旅程、业务流程或业务能力组织；有的把 Markdown 放在代码仓库里，有的更适合中心化知识平台。
真正重要的是，业务层知识能不能帮 AI 准确回答这几个问题：
- 需求中的业务概念是什么意思？
- 当前需求发生在哪个业务场景？
- 页面功能和用户操作对应哪些后端 API 与系统链路？
- 技术方案需要遵守哪些跨场景设计原则？
- 历史上类似问题如何处理，曾经发生过哪些风险？
- 当前这条知识是否经过确认，能否安全地作为 AI 行动依据？
只要这几个问题的回答质量在持续提升，业务层的建设就产生了实际价值。
承载上，可以使用 LLM Wiki 存业务层，主要图它方便人为编辑、人工查看和干预，并按「分领域知识库」组织，手车互联、驾车导航、停车推荐这些关联度较低的场景，各维护各的。
5.3 架构层落地：服务图谱 + 架构约束
这一层我们用的是 AI Native 时代打造的 AI 平台型基建。三个关键价值：
① 服务能力的 Skill 化
把每个后端服务的对外接口包装成 AI 技能。每个 Skill 包含一组相关 API、接入指南和质检文档，用来验证 Agent 调用该 Skill 时，输出是否准确、安全、符合预期的检验标准和测试用例集。Agent 装上技能，就能用自然语言调用对应服务能力。
这和 Ontology「把能力结构化暴露」的思路是一致的，只是粒度更贴近后端服务和接口，而不是完整的企业级业务对象体系。
② 服务间调用图谱
一条 graph <项目名> 就能查到任何项目的上下游依赖：谁调了我、我调了谁、用什么协议、HTTP 还是 RPC、具体哪个接口、超时多久。
这一点很关键：
很多技术方案设计最怕的不是不知道怎么改代码，而是不知道改完影响谁。
有了服务图谱，影响分析就不再完全依赖人肉问同事。
③ 架构约束
跨多系统的方案调研和设计，光有架构知识不够，还要有约束：核心链路有哪些、系统分级和链路分级是什么、哪些是高危系统改动前需要人工确认。
需要把各个领域、跨领域的几百个微服务和链路做了知识化治理，并建立了较强的检索能力，方便大家在需求调研、方案调研阶段快速熟悉不同后端系统及其职责、领域边界。它甚至深入系统内部，把核心的 DTO 和 Index 暴露出来，某种程度上起到了 Palantir Ontology 里 OSDK 的作用。
从走访情况看，这一层的检索能力是刚需，基本每个团队都有自己的解决方案。也有团队直接集成 LLM WiKi 搜索，本地做 cache 或增强。
顺带说一下这层知识最高频的三个使用场景：
- 需求调研：一个需求到底涉及多少系统，哪些能力已经存在。比如打车系统里，司机接单经过了几层系统、几层风控，每层做了什么策略和拦截？想加一个新策略，加到哪一层的哪个系统合适？对新人熟悉系统也很有价值。
- 技术方案设计与工作量评估：改造半径、改造风险、工作量评估，都依赖链路上的各种系统事实。
- 线上问题排查：真正的 7×24 场景下，大部分线上报警的排查、分析、处理都会 AI 化。而排查需要串通完整链路：从网关入口，到 API 层微服务，到下游领域服务，到中间件 RT 情况。Agent 必须同时具备系统架构事实和 runtime 事实，才能做出有效的分析和干预。
5.4 系统层落地：为什么最后选了 YAML 而不是 Markdown
这一层花的功夫最多。核心判断只有一句：
微服务的系统知识库，不能只是 LLM Wiki。
先说清楚：LLM Wiki 这类工具是有价值的。给一个仓库，AI 自动生成一份全面的 Markdown Wiki：项目概览、模块划分、核心流程、API 说明、数据模型，代码推送后还能增量更新，通过 MCP 提供 AI 访问，同时支持 BM25 和语义向量检索。
它最大的优势是零成本接入和自动维护：只要仓库有代码可读权限就能生成，不需要额外组织人力，也不需要工程师专门维护文档。对于「想让系统 AI Friendly、但暂时没有额外人力投入」的团队，这是非常现实的第一步。新人 onboarding、跨团队理解陌生服务、快速定位某个业务概念在哪实现，它都好用。
但站在 AI Coding 的角度看，默认的 LLM Wiki 生成策略有三个结构性限制：
自然语言的解析确定性不够。当 AI 需要做判断而不只是理解时，从一段 Markdown 里提取隐含约束的准确率，通常低于从 YAML 字段里直接读取。「这个接口不能修改字段语义」，写在 Markdown 里是一句话，写在结构化 policy 里就是一条明确规则。
- 云端存储存在一致性延迟。开发者刚提交了 breaking change，AI 在更新窗口内基于过期 Wiki 做决策，就可能出问题。普通理解场景还好，但自动改代码和生成方案这个延迟必须拉齐到完整的生产链路里评估。
- 对业务定制支持偏弱。LLM Wiki 的核心定位是「代码即事实」，尊重代码事实，业务定制能力天然弱。
于是我们做了自己的知识库生成 Skill：service-knowledge-generate。
设计目标：四条硬约束
① 标准化，分两层：
- 行业标准化：需要一套站在行业高度、行业普适、相对容易被认可的方案。在语义层面，这种「共同语言」既利于人类工程师理解，也利于大模型理解，毕竟大模型本身就是基于人类知识蒸馏出来的能力。
- 团队标准化：不能每个工程师按自己的理解写一份「AI 知识文档」。有人写 Markdown 长文，有人写 JSON，有人在代码注释里堆信息，有人在 IM 文档里维护接口说明，有人在 README 里写红线。结果是什么？每个 Agent 或 Coding 工具都要针对每个项目单独适配；团队换人后没人知道组织逻辑；工具链无法复用；也不知道建到什么程度算「够了」。早期探索这么干可以接受，但 Agentic Coding 要规模化落地，这笔额外成本会非常大。
② 适配不同规模的系统。中小规模微服务可能只有 100 多个程序文件、3 万行左右代码；大型微服务通常 300–700 个文件、5 万行以上。同一套工具要都能扛住。
③ 保留人工干预入口。实践下来，当前大模型已经足够强，能根据业务语义、代码语义、fanout 等维度较好地识别高危代码和分层。但公司隐形约束、监管需求这类，仍然需要人工去约束和干涉。产出物本身必须为「人工干涉 / 校验」保留入口和扩展性。
④ 大模型友好，也分两面：
- 生成友好：输入内容过多容易触发「记忆压缩」，而压缩意味着会话有损。要保证即使触发压缩，也不导致输出结果受损。
- 使用友好：Markdown 结构性差，每次都要大模型做结构化提取和理解。参考 Palantir 的实践，YAML（或 TOML）对大模型更友好，所以我们在知识库里采用了类似格式。
结构不是凭空发明：六个方法论的重新组织
| 方法论 | 落在哪个目录 | 解决什么 |
| 领域驱动设计（DDD） | object/ |
核心领域对象、聚合根、值对象、生命周期、不变量 |
| 微服务架构原则 | system/api/downstream/ |
服务边界、API 契约显式化、下游依赖显式管理 |
| 实体建模与状态机 | object/
的状态流转 |
created → paid → fulfilled / cancelled / refunded，每次流转的前置条件和副作用 |
| 基础设施即代码 | infrastructure/ |
数据库、MQ、缓存、定时任务、配置项 + 业务语义 |
| 安全与合规 | policy/ |
风险分级、红线、禁止项、审批要求、停止条件 |
| 测试金字塔 | test/ |
不同变更类型对应什么测试范围 |
几点展开：
- 领域对象不是普通数据结构，它承载了业务约束。订单、支付单、履约单、账户、权益、库存，这些对象的状态和流转规则，往往比接口本身更重要。
- 状态机是系统中风险最高的部分之一。AI 不理解状态机、只按局部代码改，很容易引入绕过校验、重复执行、状态不一致的问题。
- 数据库字段和 MQ schema 必须附带业务语义。很多线上问题都来自「看起来只是改个字段，其实破坏了上下游契约」。
- 测试不是写一句「跑测试」就完事。新增 API 跑契约测试，改数据库跑迁移验证和回归，改状态机跑核心流程，改 MQ schema 跑生产者消费者兼容性验证。
这些方法论本来就存在，只是过去主要服务于人类工程师。
service-knowledge-generate做的事，是把它们重新整理成 AI Agent 可消费的知识结构，不是创造新概念，是把老经验变成新协议。
产出物：两类文件
第一类：AGENTS.md，可以理解为 Bootloader。
放在仓库根目录，告诉 Agent 去哪里加载知识、以什么顺序工作、什么不能做。它不应该复制大量正文，而要短、清楚、权威，像一个入口说明。
第二类：.knowledge/ 目录下的 YAML 文件。
其中 index.yaml 是路由中心。它定义整个知识库的索引结构，同时按常见开发任务类型定义必读文件清单：
knowledge_base:
name: "alibaba-*-*"
version: "1.0.0"
generated_at: "2026-07-07T07:15:00Z"
repository:
branch: "test/knowledge-20260707-skg"
commit: "391fc2989729cfd68650f7db90d2d498b370936d"
# 全局 index
catalog:
system: ".knowledge/system/"
object: ".knowledge/object/"
api: ".knowledge/api/"
downstream: ".knowledge/downstream/"
infrastructure: ".knowledge/infrastructure/"
flow: ".knowledge/flow/"
test: ".knowledge/test/"
policy: ".knowledge/policy/"
task_routes:
add_api:
required:
- api/public_api.yaml
- api/api_compatibility.yaml
- test/test.yaml
- policy/policy.yaml
modify_database:
required:
- infrastructure/database_schema.yaml
- test/test.yaml
- policy/policy.yaml
fix_bug:
required:
- flow/
- test/test.yaml
- policy/policy.yamltask_routes 是我认为最值得抄的一个设计。
它把「这次任务是什么类型」和「必须读哪些上下文」硬绑定，相当于给 Agent 装了一个强制前置检查，不是等 AI 自己想起来去查约束，而是任务一进来就把约束推到它面前。
完整的文件树长这样：
.knowledge
├── api # 对内对外 API
│ ├── api_compatibility.yaml
│ └── public_api.yaml
├── downstream # 下游依赖梳理
│ ├── feature_service.yaml
│ ├── route_service.yaml
│ └── search_service.yaml
├── flow # 核心业务 Flow，独立设计，可脱离 MVC 等代码架构存在
│ ├── park_point_management.yaml
│ ├── reach_radar_recommend.yaml
│ └── v2_scene_recommend.yaml
├── generated # 历史生成报告
│ ├── latest.md
│ └── report-20260616-100000.md
├── index.yaml # 全局 YAML 索引文件
├── infrastructure # 基础架构依赖层，如 Database、MQ 等
│ ├── database_schema.yaml
│ └── message_queue.yaml
├── object # 系统内核心实体定义
│ ├── park_point.yaml
│ ├── reach_radar.yaml
│ └── reach_scene.yaml
├── policy # 代码开发约束，可初步自动识别
│ └── policy.yaml
├── system # 上下游、技术栈、系统简介等
│ ├── architecture.yaml
│ ├── card.yaml
│ └── tech_stack.yaml
└── test # 测试用例等
└── test.yaml最后单独拎一个细节出来：policy 里的 confirmed: false。
它意味着这条知识还没有被人确认，Agent 不能把它当作强事实使用。
这个小字段解决了一个大问题：AI 生成的知识库，你怎么区分「机器推断的」和「人工背书的」？没有这个标记，所有知识的可信度就被拉平了，而这恰恰是最容易出事的地方。
5.5 基建层落地
基建层的四个特点，决定了它的承载方式：
- 偏静态：发布 MCP、灰度策略这类，团队内部基本可以拉齐复用；
- 更新频率低：代码规范是「法条」级别的约束，法本身不会经常变；
- 作用于不同研发阶段：代码规范作用于 coding 阶段，CI 知识更多是公司内的流程，彼此关联度很低；
- 结构性偏低：不像系统层有强结构化的实体和状态机定义，基建层的知识往往真的就是「知识」本身，甚至难以成为「数据」。
所以我们最终跟业务层一样，用 LLM Wiki 承载，通过对应的 MCP 或 Prompt 作用于实际开发流程。
5.6 知识中台全景
| 层 | 承载方式 | 内容 |
| 业务层 | LLM Wiki / MCP / Prompt | 业务知识、业务与架构映射、历史实践 |
| 架构层 | AI 原生基建 | 服务图谱、上下游依赖、架构约束、影响分析 |
| 系统层 | service-knowledge-generate（仓库内 .knowledge/） |
系统事实、系统约束、任务路由、验证规则 |
| 基建层 | LLM Wiki / MCP / Prompt | 中间件知识、代码规范、工程规范、CI/CD 规则 |
四层共同服务于同一条链路：技术方案设计 → AI Coding → 验证测试 → Review 交付。
顺便说一下我们怎么衡量这套东西建得好不好，主要看三个指标：
- 内容全面性：面对几十个微服务，知识库能不能反馈系统全貌。举个真实的坑，本来已经有一个微服务可以根据经纬度获取用户 POI，知识库里漏了这一点，AI 就会重新设计开发一个一模一样的 API。
- 内容准确性：AI 时代内容准确性已经大幅提高（大量知识库依赖 AI 生成，比人工梳理提效很多）。剩下的痛点主要是技术元语定义重复，以及代码变更后知识库是否及时联动更新。
- 召回效率和质量：跨多仓库的知识召回，准确率和 query 优化、召回引擎强相关。别忘了一个物理事实，大模型上下文窗口虽有几百 KB 甚至 MB 级别，但有效注意力往往集中在前几十 KB。
06 最大的坑：AI Friendly ≠ 文档越多越好
必须泼一盆冷水。
很多团队一听要给 AI 建知识库，第一反应是焦虑：是不是每个函数、每个类、每个接口、每个工具方法都得写一遍说明？
如果这么干，基本很快就会失败。
因为没人愿意维护，也没必要维护。更糟的是，大量低价值文档会干扰 AI 判断，让它在真正关键的信息之外消耗上下文和注意力。
那什么值得写？三个特征：高复用、高风险、高隐性。
① 高复用：被多个需求、多个系统、多个团队反复使用的知识。公共 API、核心领域对象、通用业务流程、下游依赖、测试策略、公共中间件使用方式。这类知识沉淀一次，之后每次方案设计和 AI Coding 都能复用，ROI 极高。
② 高风险：改错后果严重的知识。交易状态机、支付流程、资金对账、权限系统、核心数据库表、MQ schema、风控策略、降级兜底逻辑。
即使代码量不大也要优先显式化，因为 AI 最容易在「局部看起来合理」的地方做出危险修改，而高风险模块恰恰不能只看局部。
③ 高隐性：代码里看不出来、或者很难从代码中稳定推断出来的知识。历史兼容原因、线上事故教训、审批规则、组织红线、特殊业务约束。
第三条最关键，因为这里必须划一条线：
模型再强，也无法推断不存在的信息。
- 「这个 API 字段是公司级红线不能删除」代码里可能有 100 个字段，模型没有任何线索知道哪些绝对不能删。
- 「修改状态机必须经过人工审批」这是组织决策、流程约束，代码不会告诉你。
- 「变更超过 3 张表的 DDL 必须发起变更单」同理。
这些信息的共同特点是：它们是规范性的，不是描述性的。
它们不存在于代码中，只存在于人的脑子里、团队约定里、事故复盘里，或者某个分散文档里。没有人把它们显式化，任何模型都推断不出来。
给一份可以直接对照的清单：
✅ 优先显式化
服务边界 / 核心领域对象 / 状态机 / API 兼容性规则 / 数据库表业务语义 / MQ 事件契约 / 下游依赖 / 风险红线 / 测试策略
❌ 不要浪费精力
普通工具函数说明 / 从代码一眼能读出来的实现细节 / 经常变化但没有业务约束的临时代码 / 低风险 CRUD 的重复描述
一句话：
AI Friendly 的关键不是文档越多越好，而是把那些「AI 容易猜错、人类又经常忘记、改错代价很高」的知识显式化。
文档只是知识的载体，不是目标本身。真正有价值的 AI 知识库，不是信息堆得足够多，而是能在关键时刻告诉 AI：这里是什么、为什么这样设计、哪里不能动、改完以后怎么证明是安全的。
07 如果大模型把这些能力都内化了，今天做的是不是无用功？
这是被问得最多的一个问题，值得认真回答。
当前主流强基模已经展现出一个高阶能力：自主编排多个工具。
你给一个 Agent 同时接入架构知识 MCP、LLM Wiki MCP 和本地文件读取能力，它能自主决定：先用 LLM Wiki 做业务知识转换分析，看看业务元语该映射到哪些技术系统链路；再用架构知识 MCP 检索对应的 API 和链路，理解核心流程；最后读 .knowledge/policy.yaml 检查约束，判断这次修改的风险等级。
它不需要你预先写死「先做 A 再做 B」的工作流。模型自己判断什么时候需要什么信息，然后主动去取。在很好地理解了这些知识和代码结构之后，它甚至能按同样的标准反向产出和维护知识库。
这意味着两件事。
第一，哪怕你的知识库不够强大、流程编排不够精巧，不断进化的基模都可能很好地理解和包容这些不完善。门槛在降低。
第二，今天这套架构设计里的大部分内容，可能在不久的将来被大模型内化成自身能力。
我在和其他公司的朋友交流时，不止一次听到这样的担心：自己辛苦做的平台化能力、标准化 Skill，可能没多久大模型天然就支持了，感觉做了无用功。
我倒是乐于见到那一天。
因为我们和大模型不是竞争关系，是合作伙伴关系。大模型内化的能力越强，人类工程师需要做的事就越少，这本身就是好事。我们真正的目标是AI Native 的 7×24 小时生产，而不是证明某个工具不可替代。
更重要的是：
今天做知识库建设，并不是在和未来的大模型能力赛跑，而是在把团队的业务理解、架构经验、系统约束和工程规范显式化。
哪怕未来模型再强，这些显式知识也不会浪费。它们只是会换个身份，从「喂给 AI 的上下文」，逐渐变成「组织工程能力的结构化资产」。
而后者，从来就不是任何一个模型能替你生成的。
08 写在最后：一份冷启动路线图
如果你的团队现在从零开始，不建议四层齐头并进。按投入产出比排，建议这个顺序：
第 1 周：先止血
挑 1–2 个核心系统，只写两个文件：policy.yaml（红线和禁止项）和 test.yaml（不同变更类型的验证要求）。这两个东西成本最低、防翻车效果最直接。
第 1 个月：补事实
用 LLM Wiki 类工具自动生成系统事实（模块划分、API、数据模型、核心流程），再人工补 object/（核心实体和状态机）。自动化能覆盖的部分，不要人肉写。
第 1 个季度：打通链路
建服务图谱和上下游依赖，让「改这个会影响谁」能被机器回答。同时开始沉淀业务层的 meta（消歧）和 scenario（PRD 到 API 的映射），这两个是「PRD to 技术方案」断层的解药。
持续：建闭环
把每次方案评审的遗漏、每次 Code Review 的风险、每次线上问题暴露的隐性依赖，反向写回知识库。可以用 git hook 之类的工具做自动化维护和提醒。
最后再重复一遍那句最重要的话：
AI 最怕的不是没有上下文，是拿到了错误的上下文。
过期的知识库，比没有知识库更危险。
来源：https://www.51cto.com/article/851321.html