这是 2026 年的第 41 篇文章
（本文阅读时间：约 20 分钟）
从「让 AI 看懂代码」到「让 AI 正确行动」
在探讨后端系统 AI Friendly 设计时，核心判断在于：仅靠清晰的代码、完善的 README 或完整的接口注释，只能解决“人和 AI 读懂局部代码”的问题，无法解决"AI 在复杂系统中做出正确工程判断”的难题。
真正的挑战在于系统边界的认知：AI Agent 是否知晓接口兼容性红线？是否了解看似无用实则被下游依赖的字段？是否清楚旧模块中关键的交易兜底逻辑？人类工程师依靠经验、沟通和事故记忆补全上下文，而 AI Agent 缺乏这种“组织记忆”，只能依赖显式提供的信息。
因此，“知识库怎么选”本质上是“将哪些系统知识显式化”以及“以何种形态交付给 AI"。新人 Onboarding 仅需 Markdown Wiki，但跨服务影响分析需要服务图谱与依赖关系，安全修改代码则需要明确的约束、红线及验证标准。本文旨在探讨如何设计后端系统 AI Friendly 化的知识库，挖掘冰山下的隐性知识，推动 AI 从 Coworker 向 Agentic Operator 演进。
知识库 to 技术方案—决胜环节
为什么技术方案设计如此重要
无论是 CoWorker 模式还是 7x24 小时全自动 Agentic Operator 模式，技术方案设计都是研发流程中最关键的一环。AI 时代放大了方案质量的杠杆效应：
首先，AI 的执行速度放大了错误传播。人类工程师走偏半天仅产生少量代码，易被 Review 纠正；而 AI Agent 在错误方案指引下，十分钟即可完成涉及多文件、多接口、多表的变更，回滚成本极高，且此类错误多为业务理解偏差或兼容性破坏，难以通过单测发现。
其次，AI 默认行为是“忠实执行”而非“质疑方案”。资深工程师能基于全局视角指出需求矛盾或潜在风险，而 AI 往往缺乏对系统全局的理解，容易直接执行存在隐患的方案。
最后，AI Coding 的核心价值在于处理执行细节，前提是执行方向正确。若因方案设计失误导致大量返工和线上异常，净效率提升将趋近于零。
技术方案设计强依赖知识库
AI Coding 时代的技术方案设计，要求 AI 拥有准确的结构化系统上下文，即完善的知识库。知识库需回答：系统架构与模块边界、上下游依赖与接口契约、数据库 Schema 与隐含依赖、历史变更踩坑记录以及操作红线等。
此外，建立“业务元语”与技术链路的映射（业务层），能极大提升方案设计的效率与准确性。目标不仅是让 AI 看懂代码，更是让其在设计方案和执行变更时拥有正确、完整、可验证的系统上下文。
知识库贯穿 AI Coding 全流程
知识库不应仅是 RAG 文档库，而应贯穿从需求理解到 Review 交付的全流程：
- 需求理解阶段：帮助 AI 理解“业务元语”，将自然语言需求翻译成系统可识别的技术对象和链路。
- 现状与影响分析阶段：提供架构层知识、服务依赖关系及历史实践，避免 AI 做出“单仓库合理但全链路不合理”的方案。
- 技术方案设计阶段：确定改动边界、数据流、兼容策略及验证范围，防止生成形式完整但上下文错误的危险方案。
- 编码执行阶段：明确目录修改权限、跨层调用限制、字段删除禁令及幂等性要求，约束 AI 行动。
- 验证测试阶段：定义不同改动类型的验证规则（如契约测试、迁移验证、兼容性检查），确保修改安全。
知识库应形成闭环，将评审遗漏、Code Review 风险及线上问题反向沉淀，避免提供过期或错误的上下文。
知识库的建设目标与分层
建设目标
基于互联网架构思维，知识库建设主要衡量以下指标：
- 内容全面性：反馈系统全貌，避免重复造轮子（如重复开发已存在的微服务能力）。
- 内容准确性：消除技术元语歧义（如区分“交易订单”与“配送单”），并确保随代码变更及时联动更新。
- 召回效率和质量：优化 Query 与召回引擎，确保在有限上下文窗口内精准加载最相关知识。
知识库的分层设计
针对产品需求转技术链路瓶颈、跨系统事实缺失、RAG 检索增强及单一系统抽象程度不足等挑战，将知识库分为四层：业务层、架构层、系统层、基建层。
（注：蓝色背景框部分为高性价比模块，建议优先投入。）
业务层：让 AI 知道“为什么改”和“业务落在哪里”
业务层包含三类核心知识：
- 业务知识：定义系统服务的业务概念、核心规则及状态流转含义，解决 AI 只看代码不懂业务语义的问题。
- 业务与架构映射：明确业务概念落地的系统、模块、接口及消息，防止将跨系统需求误判为单服务修改。
- 历史实践：记录“过去为什么这么做”，解释看似不优雅设计背后的历史事故、灰度兼容或合规要求，避免 AI 盲目重构。
架构层：让 AI 知道“系统之间怎么协作”
架构层解决系统间的分工、调用与治理问题：
- 架构事实：描述系统组织方式、核心/旁路链路、同步/异步调用及一致性模型，避免局部最优方案。
- 架构约束：规定系统设计红线，如核心链路禁止新增强依赖、禁止跨库直查等。
- 服务治理：涵盖服务等级、超时配置、熔断降级、SLA 及灰度策略，影响方案上线可行性与风险控制。
该层核心价值在于帮助 AI 进行影响分析和服务寻址，确保技术方案前半段的可靠性。
系统层：让 AI 知道“这个服务内部怎么改才安全”
系统层是单个服务内部最核心的 AI Friendly 知识层：
- 系统事实：模块划分、领域对象、API、数据库表、缓存 Key 及状态机等基础信息。
- 系统约束：明确不可随意修改的内容，如 Public API 字段语义、状态机流转校验及幂等性要求。
- 验证/测试：定义不同变更类型的验证标准，如契约测试、迁移验证及兼容性检查。
此层需结合 CodeWiki（生成系统事实）与 service-knowledge-generate（结构化约束与验证规则），组织好“事实 + 约束 + 验证”三要素。
基建层：让 AI 知道“底座规则是什么”
基建层提供工程底座规则：
- 中间件知识：团队特定的 Redis、Kafka、DB 等使用约定（如 Key 命名、分库分表规则、慢查询阈值）。
- 代码规范约束：分层结构、命名规范、异常处理及事务边界等，确保生成代码符合团队风格。
- 工程规范：依赖管理、发布流程、灰度要求及安全扫描等，决定代码能否安全上线。
方案调研
Ontology 本体论
Palantir 推崇的 Ontology（本体论）方法论，是对特定领域概念、属性及关系的形式化规范说明。其核心要素包括类、属性、关系、公理及实例。
Ontology 与知识图谱的区别在于：前者是定义概念与逻辑约束的模式层（Schema），后者是存储实体数据的实例层。Ontology 定义了企业数字孪生的协议，包含 Data（对象映射）、Logic（业务规则）、Action（原子化操作）及 Security（动态权限），使跨系统编排从私有 API 适配变为标准化建模问题。
KBase（Code Wiki）平台
阿里集团内部的 KBase 平台能自动生成全面的 Markdown Wiki，支持增量更新与语义搜索。其优势在于零成本接入和自动维护，适用于新人 Onboarding 和跨团队协作。但在 AI Coding 场景下存在局限：自然语言解析确定性不如结构化数据、云端存储可能存在一致性延迟、对业务定制支持偏弱。
知识检索平台
多个团队建设了独立的知识检索引擎或基于 KBase 的 RAG 能力，主要用于需求调研（定位系统与能力）、技术方案设计（评估改造半径与风险）及线上问题排查（全链路分析）。通过集成 CI/CD 平台、监控报警平台的 MCP 能力，结合 Architecture as Wiki，可有效梳理系统现状。
落地实践与选型
业务层实践
业务层知识库应帮助 AI 完成从产品需求到技术链路的转换。推荐目录结构如下：
business/
├── index.md
├── meta/ # 业务元语、核心对象、概念边界
├── principle/ # 跨场景复用设计原则（超时、幂等、兼容性等）
├── scenario/ # 业务场景与技术链路转换（页面功能->API->下游）
├── practice/ # 历史设计与实践（决策原因、避坑指南）
└── history/ # 知识库自身变更日志采用带 YAML Front Matter 的 Markdown 格式，既保留人类可读性，又提供结构化信息供 AI 检索路由。重点在于明确业务概念定义、场景转换链路及历史经验教训。
架构层实践（aitom 平台）
采用 aitom 平台实现架构层知识治理，核心价值包括：
- 服务能力 Skill 化：将后端接口包装为 AI 技能，支持自然语言调用。
- 服务间调用图谱：可视化展示上下游依赖、协议类型及超时配置，辅助影响分析。
- 架构约束：定义核心链路、系统分级及高危操作确认机制。
系统层实践（service-knowledge-generate）
针对微服务系统，研发了 service-knowledge-generate SKILL，融合 DDD、微服务架构、实体建模及测试金字塔等方法论。核心产出为两类文件：
- AGENTS.md：入口说明，指导 Agent 加载顺序与禁忌。
- .knowledge/*.yaml：结构化知识库，包含 system（架构）、object（领域对象）、api（接口契约）、downstream（下游依赖）、infrastructure（基础设施）、flow（业务流程）、policy（约束红线）及 test（验证策略）。
YAML 格式相比 Markdown 更利于大模型结构化提取与理解，减少记忆压缩带来的信息损耗。
基建层实践
基建层知识偏静态、更新频率低且结构性较弱，主要涵盖中间件使用约定、代码规范及工程流程。建议沿用业务层存储方式，以 KBase 承载，通过 MCP 或 Prompt 作用于开发流程。
总览
AI Friendly 不是「文档越多越好」
AI Friendly 的核心不在于文档数量，而在于显式化高复用、高风险、高隐性的知识：
- 高复用：公共 API、核心领域对象、通用业务流程等，ROI 高。
- 高风险：交易状态机、资金对账、风控策略等，改错代价极大。
- 高隐性：历史兼容原因、组织红线、特殊业务约束等，代码无法推断。
模型无法推断不存在的信息。规范性知识（如“某字段严禁删除”、“变更需人工审批”）必须显式化。应避免将普通工具函数、一眼可知的实现细节及低风险 CRUD 重复描述，以免干扰 AI 判断。
面向未来：大模型内化了这些能力怎么办？
随着基础大模型迭代，其自主编排工具的能力日益增强。强基模 Agent 可自主决定调用 KBase 分析业务、利用 aitom 检索链路、读取本地 Policy 检查约束，无需预设死板工作流。
这意味着当前的知识库架构未来可能被大模型内化。但这并非无用功，因为建设过程是将团队的业务理解、架构经验及工程规范显式化的过程。无论模型如何进化，这些显式知识都将从“喂给 AI 的上下文”转化为“组织工程能力的结构化资产”，助力实现 AI Native 的 7x24 小时生产。
References
[1]: https://palantir.com/docs/foundry/ontology/overview/ "Overview • Ontology"
[2]: https://www.domainlanguage.com/ddd/ "DDD Resources"
[3]: https://martinfowler.com/bliki/BoundedContext.html "Bounded Context"
[4]: https://martinfowler.com/microservices/ "Microservices Guide"
[5]: https://martinfowler.com/bliki/InfrastructureAsCode.html "Infrastructure As Code"
[6]: https://martinfowler.com/articles/practical-test-pyramid.html "The Practical Test Pyramid"
本文的完成离不开李岩、芦楠、郄延春等同学的帮助与支持，在此一并致谢。
