AI Friendly 知识库体系：后端系统知识显式化（模式）

摘要：后端系统 AI Friendly 化的核心不是"代码写清楚、文档多写点"，而是把冰山藏在水下的 90% 系统知识显式化，让 AI 从 coworker 走向 agentic operator。本文给出四层知识库体系（业务/架构/系统/基建）与"高复用、高风险、高隐性"显式化原则（stated）。

定义与核心问题

冰山模型：AI 不是看不懂代码（读代码/解释/补测试能力已很强），问题在于后端系统大量关键知识不在代码中，或分散在不同仓库、配置、历史 PR、口头约定里（stated）。

人类工程师靠长期经验、团队沟通和事故记忆补全上下文；AI Agent 没有"组织记忆"，只能读取明确给它的东西（stated）。

我们到底要把哪些系统知识显式化，显式化之后以什么形态交给 AI 使用？—— 这是知识库建设的底层问题（stated）。

为什么技术方案设计是决胜环节

AI 时代放大了方案质量的杠杆效应（stated）：

1. AI 执行速度放大错误传播：错误方案下 AI 10 分钟可完成涉及 5 文件/3 接口/2 表的变更，回滚成本是人工编码数倍；且错误往往是"业务理解错/边界改错/兼容破坏/下游影响漏"，语法和单测抓不住
2. AI 默认"忠实执行"而非"质疑方案"：senior 工程师会质疑循环依赖/并发场景/接口改动，AI 对需要系统全局理解的问题往往直接执行
3. AI Coding 的核心价值是处理执行细节，前提是方向正确：方案错了，高效执行 = 高效返工

知识库贯穿全流程：需求理解（业务元语翻译）→ 现状/影响分析（回到真实系统）→ 技术方案设计（改动边界/兼容策略）→ 编码执行（约束如何行动）→ 验证测试（怎么证明安全）→ 沉淀闭环（评审遗漏/线上风险反向沉淀回知识库）（high）。

四层知识库体系

1. 业务层：让 AI 知道"为什么改"和"业务落在哪里"（最易被低估）

• 业务知识：系统服务什么业务（订单/支付/履约/风控…），核心规则、正常/高风险状态变化
• 业务与架构映射（最关键、最易缺失）：业务概念落在哪些系统/模块/接口/表/消息上 —— 否则 AI 把跨系统需求误判成单服务局部修改
• 历史实践：过去为什么这么做（多余字段、兼容老逻辑的代码、不能删的 MQ 分支背后可能是历史事故/灰度兼容/合规要求）

2. 架构层：让 AI 知道"系统之间怎么协作"

• 架构/分层/链路事实：链路经过哪些服务、核心 vs 旁路、同步 vs 异步、强一致 vs 最终一致 —— 防止"局部最优"方案（逻辑该在订单服务却改到网关层）
• 架构约束：核心链路不能新增强依赖、交易链路不能引不稳定外部服务、接口只能由聚合服务调用、不能反向依赖上游（约束的是系统间关系与依赖方向，区别于代码规范）
• 服务治理：服务等级、超时/重试/熔断/限流、owner、SLA、灰度策略、监控告警

3. 系统层：让 AI 知道"这个服务内部怎么改才安全"（AI Coding 最核心层）

• 系统事实：模块划分、核心领域对象、API、数据库表、缓存 Key、MQ Topic、状态机、配置项
• 系统约束（最关键也最易缺失）：public API 字段不能删、数据库字段只能新增不能改语义、状态机流转必须经特定校验、历史兼容逻辑不能删、写操作必须幂等
• 验证/测试：新增接口要契约测试？改数据库要迁移验证？改状态机要跑核心流程用例？改 MQ schema 要验证生产者消费者兼容？（否则 AI 只跑单测就以为完成）

4. 基建层：让 AI 知道"底座规则是什么"

• 中间件使用约定（非通用知识）：团队如何用 Redis/Kafka/ES/配置中心 —— Redis Key 命名、缓存过期策略、MQ Topic 命名规则、消息幂等要求、分库分表规则
• 代码规范约束：分层结构、命名规范、DTO/DO/Entity 边界、事务边界、Mock 方式 —— 让 AI 写出"像这个团队写的代码"
• 工程规范：依赖管理、发布流程、配置变更、灰度要求、安全扫描、监控埋点、回滚策略

显式化原则：AI Friendly 不是"文档越多越好"

大量低价值文档反而干扰 AI 判断、消耗上下文。真正值得显式化的知识有三个特征（stated）：

特征	含义	例子
高复用	多需求/多系统/多团队反复使用	公共 API、核心领域对象、通用业务流程
高风险	改错后果严重	交易状态机、资金对账、权限系统、MQ schema、风控策略
高隐性	代码里看不出来、难稳定推断	历史兼容原因、事故教训、审批规则、组织红线

关键划界：模型再强，也无法推断不存在的信息（stated）。"这个 API 字段是红线不能删""改状态机必须人工审批"是规范性知识，不在代码里，不显式化任何模型都推断不出来。

• 适合优先显式化：服务边界、核心领域对象、状态机、API 兼容性规则、数据库表业务语义、MQ 事件契约、下游依赖、风险红线、测试策略
• 不适合：普通工具函数说明、一眼能读出的实现细节、经常变化的临时代码、低风险 CRUD 重复描述

建设目标（衡量指标）

• 内容全面性：几十个微服务下能否反馈系统全貌（漏掉已有 API 会导致 AI 重复造轮子）
• 内容准确性：技术元语定义重复问题（"订单" vs "配送单" 歧义）；代码变更后知识库及时联动更新
• 召回效率：跨仓库知识召回、query 优化（模型有效注意力往往集中在前几十 KB）

展望：与不断内化的大模型共处

当前强基模已能自主编排多个工具（接入 kbase MCP + aitom MCP + 本地文件读取后，自主决定先做知识转换分析、再搜 API、再查约束）—— 不需要预先写死工作流（stated）。

核心心态：做知识库建设不是和未来模型能力赛跑，而是把团队的业务理解、架构经验、系统约束、工程规范显式化。哪怕模型更强，这些显式知识不会浪费 —— 它们会从"喂给 AI 的上下文"变成"组织工程能力的结构化资产"（stated）。

关联词条

• Harness Engineering 与知识工程：数据研发企业落地实践（pattern · 知识工程双支柱）
• Harness 工程搭建式业务 Agent 评测（pattern）
• Loop Engineering：让 AI 自主闭环运转（pattern）
• Harness（智能体执行框架）（concept）