模型越来越强，复杂业务仓库还需要知识库吗？

——从知识路由、流程约束到维护与评测的工程实践

✨ AI 摘要

复杂业务仓库中的多版本、动态配置、跨端差异和外部依赖，会增加 Agent 的搜索成本与方案偏差。本文提出一套以知识路由为核心的工程实践：通过控制层、知识层与事实层组织上下文，将知识证据接入 SDD 流程，并以生成、回写、巡检和分层评测形成维护闭环，帮助 Agent 更稳定地进入正确上下文并回到源码验证事实。

前言

说明：本文源自笔者最近的工作实践和思考，相关项目细节及数据均已抽象化和脱敏。

模型越来越强后，知识库并不会自动变成刚需。目录清晰、边界简单的仓库，直接搜索和阅读源码通常已经足够；如果文档只是复述代码，反而会带来维护负担。

但在长期演进的复杂仓库中，同一个业务可能存在多个版本，还会叠加动态配置、跨端差异和外部依赖。Agent 即使最终能找到答案，也可能经历更长的搜索路径、消耗更多上下文，并产生更大的方案方差。

因此，我们要建设的不是“代码说明书”，而是一套可执行的知识路由：先把 Agent 带到正确上下文，再让它回到源码对结论负责。

可执行知识路由系统

什么时候值得建设知识库

判断标准不应只是代码行数，而要看下面四类错位是否反复发生：

错位	典型表现	风险
代码位置与业务版本错位	同一业务存在多个历史版本或运行时分支	方案落在已退出主流程的代码上
局部实现与整体职责错位	组件能读懂，但不清楚页面、状态和事件归属	局部正确，整体方案错误
接入代码与能力归属错位	仓库里存在调用点，但主体能力来自外部模块	把“本仓接入”误判为“本仓实现”
有文档与找到正确文档错位	同一关键词命中业务、技术和历史方案	错误召回与没有召回同样危险

当这些问题偶尔出现时，继续依靠源码搜索即可；当它们在日常需求中反复产生纠偏成本，知识工程才值得投入。

一条有效的知识路径应该是：

业务问题
  → 确定页面、版本和职责
  → 选择相关技术专题
  → 收敛源码入口和验证范围
  → 回到源码确认最终事实

知识负责缩小搜索空间，源码负责裁决事实。

用三层结构组织知识

把所有说明塞进一个超长的 AGENTS.md，会让规则、业务事实和实现细节混在一起。更可维护的方式是分成三层：

层次	核心资产	回答的问题
控制层	仓库级 Agent 指令	这类任务先读什么、何时深入？
知识层	业务文档、技术专题、职责边界	它是什么、怎样实现、由谁负责？
事实层	当前源码、配置、依赖和验证结果	系统现在实际如何工作？

仓库级指令是路由，不是百科全书。一个典型读取顺序是：

1. 先读技术索引，只获取专题地图。
2. 涉及页面、场景或用户行为时，再读业务索引。
3. 涉及内外部协作时，补读职责边界。
4. 范围确定后，只加载真正命中的技术专题。
5. 修改、评审或测试时，再读取编码与交付规范。
6. 最终回到源码核实；冲突时以源码为准，并记录知识缺口。

知识层的渐进式披露

知识目录无需照搬，但问题边界应清晰：

docs/
├── architecture/       # 应该怎样实现
├── business/           # 这是什么业务
├── responsibility.md   # 由谁负责
└── coding-standards/   # 如何修改、验证和交付

证据优先级也要明确：

产品白皮书 / PRD       → 规范业务语义，决定 WHY / WHAT
业务与技术知识         → 定位范围、职责和方案约束
当前源码与验证结果     → 裁决实现事实

这与 OpenAI 分享的 Harness Engineering 实践结论相近：面向 Agent 的可读性不在于一次灌入更多内容，而在于让正确知识可发现、可验证。

知识库不要成为“第二份源码”

越详细的文档不一定越可靠。把状态字段、事件名称和分支条件全部复制一遍，只会制造更新更慢的第二份源码。

长期知识更适合遵循四条原则：

1. 自顶向下建模：按页面容器、页面版本、核心模块、状态单元逐层定位，不复制完整组件树。
2. 稳定标识绑定源码实体：同一路径复用同一文档标识；发现冲突时先处理冲突，不继续生成新 ID。
3. 业务语义不能只从代码反推：产品白皮书负责场景、术语和业务规则，源码负责验证当前实现。业务定义由产品经理（PM）或业务负责人确认，差异由研发负责人（下文简称 RD）处理。
4. 源码锚点是入口，不是结论：路径有效不代表内容正确；路径失效也不等于实现缺失，还可能是迁移、外部依赖或初始归属错误。

文档应该解释业务语义、职责归属和适用边界；可自动判断的规则，应下沉到类型、静态检查、测试、脚本或流程约束。代码结构本身有问题，就治理代码，而不是不断给文档追加补丁。

以 OpenSpec 为例，把知识路由接入 SDD

知识库放在仓库里，不代表 Agent 会在正确时机使用它。更进一步的做法，是让知识证据随着需求、方案和实施产物向前传递。

OpenSpec 可以作为公开示例。它通过 proposal、spec、design 和 tasks 等变更产物，帮助人和 Agent 先对齐要做什么，再进入实施；默认 OPSX 流程以 explore、propose、apply、sync 和 archive 为核心，具体以 OpenSpec 官方工作流 为准。

但 OpenSpec 与知识门禁不能直接画等号。它提供通用的 SDD 载体，不会自动理解某个仓库的业务版本和职责边界。这些约束仍需通过 AGENTS.md、openspec/config.yaml 的项目上下文、自定义 schema 或评审规则补充。

OpenSpec 环节	知识动作	边界
explore / propose	读取技术地图、业务索引和职责边界	先确认 WHY / WHAT
proposal / specs	固化范围、行为变化、场景和缺口	业务语义与职责可追溯
design / tasks	组合技术专题、源码触点和验证策略	开始回答 HOW
apply / update	继承证据范围，变化时更新产物	实施阶段不应在未说明的情况下扩大 WHAT 范围
sync / archive	同步长期规格并保留上下文	业务知识仍由项目侧维护

以 OpenSpec 为例把知识路由接入 SDD

核心只有两条：需求层不要过早锁定未经验证的实现；实施触点超出方案时，先更新变更产物并重新评审。

用三类 Skill 形成维护闭环

知识库最大的挑战不是第一次建起来，而是持续迭代后仍然可信。维护需要同时覆盖事件驱动的增量变化和周期驱动的长期漂移。

知识库的生成、回写与巡检闭环

实践中，我们把维护闭环抽象成三类可复用的 Skill：

能力	示例 Skill	主要输入	主要产出
文档生成器	page-doc-gen	产品白皮书、业务索引、当前源码	页面、模块和状态知识单元
增量回写助手	biz-docs-backfill	需求、方案、实施记录和源码变更	供 RD 确认的候选知识
周期巡检器	maintain-knowledge-base	路由、链接、源码锚点和文档结构	带证据的知识缺口队列

这些名称只是能力示例，不是采用这套方法的前置依赖。真正重要的是职责分离：

• 生成器解决“如何按稳定模型开始”；
• 回写助手解决“这次实现新增了什么长期知识”；
• 巡检器解决“过去的知识是否已经漂移”。

回写也不是把实施日志搬进文档。纯样式调整、一次性排障、环境问题和不改变职责的内部重构，不应进入长期业务知识。

最终分工应保持清晰：

• Agent 负责按路由阅读、回到源码验证、生成初稿和整理缺口；
• 脚本负责重复、机械、可确定的检查；
• RD 或业务负责人确认业务事实、职责边界和最终回写。

脚本可以证明路径不存在，却不能仅凭这一点判断责任归属；Agent 可以归纳证据，也不应单方面宣布新的业务规则成立。

用分层评测证明真实增益

知识库评测可以分成三个层级：

知识库效果评测的三个层级

层级	回答的问题	典型证据
L0 静态健康	文档是否可访问、可解析、能定位到源码？	索引、链接、锚点、结构完整性
L1 任务效果	Agent 是否更准确地完成定位和方案设计？	消融对照、触点命中、方案命中、成本
L2 真实协作	是否减少范围纠正和理解偏差导致的返工？	RD 纠正、方案返工、重复知识缺口

L0 是地基，不能证明任务效果；L1 能用于观察 Agent 行为，但实验样本未必代表真实开发；L2 最接近业务价值，更适合长期观察。SDD 产物是否完整，与知识库本身是否带来增益，也是两个不同问题。

一次探索性消融实验

我们对同一任务做过一次有无知识上下文的对照。任务被抽象为：修改一个配置驱动的页面交互，涉及页面入口、动态内容容器和一个承担交互边界的组件。

两组使用相同代码版本、模型、推理强度和工具权限：

• 基线组只使用基础提示和源码；
• 完整组加载仓库级知识路由和分层知识。

评测前固定三个预期职责触点、核心方案和评分口径。

数据说明： 以下数据来自隔离环境中的单次测试，仅反映该测试样本的运行结果，不代表任何真实业务数据，也不构成稳定收益结论，仅供方法讨论参考。

对比项	基线组	完整知识组
耗时	3 分 47 秒	2 分 29 秒
输出 Token	约 4.2K	约 2.4K
预期职责触点命中	2/3	3/3
严格方案命中	33.3%	100%

基线组找到了主要入口，也给出了局部可行方案，但遗漏了部分交互边界；完整组覆盖了三个职责触点，并复用了已有状态和事件数据流。

在这次测试中，完整知识组耗时减少约 34%，输出 Token 减少约 43%。更重要的变化不是“多找到一个文件”，而是方案更早进入正确的职责边界。

这仍然只是单样本观察：它不能证明统计显著性；同时移除仓库指令和知识文档，也无法区分收益具体来自路由规则、业务文档还是技术专题。更严谨的评测应固定任务、代码版本、模型、工具权限和评分口径，进行多次运行，并记录人工纠正。

可以借鉴 Agent Skills 的评测方法，把失败样本持续反馈到文档、路由、职责边界或流程规则中。

结语

这套实践不是一份适用于所有仓库的标准答案。仓库复杂度、代码质量和协作方式不同，知识库的形态也不会一致。本文分享的也不是一套固定目录或模板，而是我们如何把零散经验逐步变成可执行、可维护、可评测的知识路由。

回到最初的问题：复杂仓库是否需要知识库，没有统一答案。结构简单时，直接读源码已经足够；在复杂仓库中，知识库的价值也不在文档数量，而在于能否减少搜索成本、方案波动和人工纠偏。

没有路由，文档只是散落的文件；没有源码验证，知识库可能成为新的权威幻觉；没有回写、巡检和评测，知识本身也会持续漂移。

好的业务知识库，不是替 Agent 读代码，而是让它用更短、更稳定的路径进入正确上下文，并对最终结论负责。