Agent开发系列（八）-组织知识库建设

一、组织知识库的分层架构

二、知识分类:研发团队该存什么

[2.1 输入层:Raw Sources(原始事实)](#2.1 输入层:Raw Sources(原始事实))

[2.2 沉淀层:Wiki(可消费的"理解")](#2.2 沉淀层:Wiki(可消费的"理解"))

[2.3 规则层:Schema(约束一切)](#2.3 规则层:Schema(约束一切))

[三、LLM 自动化流水线](#三、LLM 自动化流水线)

[3.1 机制 1:自动化(机器跑的部分)](#3.1 机制 1:自动化(机器跑的部分))

[3.2 机制 2:流程(人参与的"卡点")](#3.2 机制 2:流程(人参与的"卡点"))

[3.3 机制 3:角色(谁负责)](#3.3 机制 3:角色(谁负责))

[3.4 机制 4:考核(怎么让人愿意做)](#3.4 机制 4:考核(怎么让人愿意做))

四、如何落地组织知识库

[4.1 第一阶段：建骨架 + 立规矩](#4.1 第一阶段：建骨架 + 立规矩)

[4.2 第二阶段：高价值低成本的内容](#4.2 第二阶段：高价值低成本的内容)

[4.3 第三阶段：核心运营内容 + Lint 体系](#4.3 第三阶段：核心运营内容 + Lint 体系)

[4.4 第四阶段：自动化加深 + Agent 化](#4.4 第四阶段：自动化加深 + Agent 化)

一、组织知识库的分层架构

组织知识库的关键设计：

Raw sources层：只能由机器/系统写入(代码、PR、监控)，人不直接改这一层；
**Wiki层：**LLM写、人读、改动由 LLM 提议 + 人批准;
Schema层：人写、LLM 读、变更走 PR review。

┌─────────────────────────────────────────────────┐
│ Schema 层(规则) │
│ - 知识分类体系、命名约定、ADR 模板 │
│ - LLM 行为规则:什么时候更新、什么时候叫人 │
│ - 治理:谁有权改、谁负责质量 │
└─────────────────────────────────────────────────┘
↓ 指导
┌─────────────────────────────────────────────────┐
│ Wiki 层(LLM 维护的"理解") │
│ - 架构图、依赖图、API 文档、ADR 索引 │
│ - 概念词典:领域名词 ↔ 代码位置 │
│ - 决策记录:为什么 A 不选 B │
│ - 失败案例:踩过的坑、撤销的决策 │
└─────────────────────────────────────────────────┘
↑ 编译自
┌─────────────────────────────────────────────────┐
│ Raw Sources 层(只读的事实) │
│ - 代码仓库(git)、PR/CI/CD 日志 │
│ - Issue/工单/Slack/会议纪要 │
│ - 外部依赖文档、SDK、RFC │
│ - 监控告警、用户反馈 │
└─────────────────────────────────────────────────┘

二、知识分类:研发团队该存什么

不是所有"知识"都值得存。用一个问题过滤:这条知识三个月后还会被谁、用在什么场景下消费?

按价值密度排序,优先建这五类:

类型	内容	价值	更新频率
ADR(架构决策记录)	选型理由、Trade-off、被否决的方案	极高(防重复争论)	低但关键
API / 服务契约	接口、字段、依赖、变更历史	极高(人和 Agent 都要消费)	中
领域词典	业务名词 ↔ 代码模块 ↔ 负责人	高(新人入职第一周)	低
失败 / 事故档案	怎么挂的、根因、修复、复盘	高(防重复踩坑)	事件驱动
运行手册(Runbook)	告警处理、回滚、扩容	高(值班用)	中

不优先建:新人onboarding手册(从 ADR + 领域词典 + Runbook 自动生成)、技术博客(发到外部,内部只存索引)、会议纪要全文(只存"决策"和"行动项")。

2.1 输入层:Raw Sources(原始事实)

这一层只读不写,是知识库的"水源"。软件开发团队的输入源,按价值密度排:

来源	抓什么	怎么接
Git 仓库	commit、branch、merge、blame	git hook + 定期 dump
PR + Review	diff、讨论、批准记录	GitHub / GitLab API
Issue/工单	创建、关闭、根因	Jira / Linear API
监控告警/事故	触发、响应、复盘	Datadog / PagerDuty + 复盘文档
会议纪要	决策、行动项、悬而未决	飞书/腾讯会议 + 飞书妙记
Slack / IM	决策讨论、答疑	飞书/Lark API
外部依赖	SDK、API、RFC 版本变更	定期抓 + LLM 摘要
客户/用户反馈	投诉、需求、NPS 原文	客服系统 + 调研工具
设计/PRD	决策点、被否决方案	Figma/语雀

输入层的设计原则 :所有源必须有"摄取路径"------没路径的源不接,接了也跑不通。优先接 4 个最有价值的:Git、PR、工单、会议纪要,这四个覆盖率到 80%。

2.2 沉淀层:Wiki(可消费的"理解")

这一层LLM 写 + 人读 + Lint 校。按"价值密度 + 更新频率"双维度排：

复制代码

高价值 · 低更新   │  ADR  决策记录
                  │  领域词典
                  │  知识地图(谁负责什么)
──────────────────┼────────────────────
高价值 · 高更新   │  API 契约 / 服务依赖图
                  │  Runbook / 故障处理
                  │  事故档案
──────────────────┼────────────────────
中价值 · 中更新   │  技术债清单
                  │  性能基线
                  │  容量规划
──────────────────┼────────────────────
低价值 · 任意     │  Onboarding 手册(从上面自动生成)
                  │  会议纪要原文(只存索引)
                  │  培训材料(从 ADR 生成)

关键判断 :**Onboarding 手册不要单独维护，**它该是 ADR + 领域词典 + Runbook 的"渲染产物"。单独维护的 onboarding 文档 100% 会过时。

2.3 规则层:Schema(约束一切)

这一层人写,所有自动化读。一个研发团队的 schema 必须包含:

知识分类体系:五种知识类型的定义、模板、命名
LLM 行为规则:什么时候更新、什么时候叫人、改动怎么走 PR
质量标准:什么样的 wiki 算合格,什么样算"过时"
治理规则:谁能改 schema、谁能批准新分类、矛盾谁仲裁

Schema 写得越具体,LLM 跑得越准。一份"vague"的 schema 等于没有 schema。

三、LLM 自动化流水线

这是研发知识库跟一般 wiki 拉开差距的地方。LLM 应该是 7×24 跑的"维护工",不是被叫来才动。包含四个自动化触发器：

**PR merged → 自动总结：**LLM 读 PR diff + commit message + review 评论,生成 1-2 段"这个 PR 改变了什么,为什么",写入对应模块的 wiki 页面。
定期 lint(每天/每周)： LLM 跑全量检查:
- 哪些 wiki 页面引用的代码路径已经不存在了
- 哪些 ADR 被新的 PR 推翻但没标记"superseded"
- 哪些概念在 wiki 里有定义但代码里没对应
- 哪些"决策"和"代码现状"矛盾(代码做了 X 但 ADR 说要做 Y) 生成 lint 报告,人 review 后批量更新。
Issue/工单关闭 → 归档：LLM把"非平凡"的工单(关掉后还有信息价值的)压缩成 1 段"问题/根因/解法",归档到对应模块的"事故档案"或"常见问题"。
**代码重大变更 → 触发 ADR 草稿：**当 LLM 检测到某个模块连续 N 个 PR 都集中在同一方向,自动草拟一份 ADR 草稿,提醒架构组 review 是否值得记一笔。

Schema 里要明确定义： LLM 写的内容必须带 [🤖 LLM-generated, last reviewed: <date>] 标记；超过 30 天没被 review 的页面，自动降权(搜索排后)。

3.1 机制 1:自动化(机器跑的部分)

让 LLM 7×24 跑四条流水线:

流水线	触发	动作
PR-ingest	PR merged	读 diff + review,写 1-2 段摘要到对应模块页
Daily-lint	每天 0 点	跑 5 类检查,出报告
Issue-archive	工单关闭	非平凡工单 → 事故档案/常见问题
ADR-trigger	模块 N 个 PR 集中同方向	草拟 ADR,提醒架构组 review

Lint 的 5 类检查是命脉:

代码引用一致性:wiki 提到的代码路径是不是还存在
ADR 现状一致性:代码是否已偏离 ADR
孤儿页:有页面但没人引用
内部矛盾:两页说相反的话
覆盖度:哪些代码模块在 wiki 里完全没出现

LLM 写的内容必须带机器标记 :[🤖 auto, last reviewed: <date>]。30 天没 review 的自动降权,这是 Schema 写死的。

3.2 机制 2:流程(人参与的"卡点")

流程	卡点
PR review	review 模板必填"是否需要更新 wiki"
重大架构变更	合并前必须有 ADR,否则不准合
事故复盘	24h 内出初稿,72h 内归档到事故档案
Onboarding	新人首周"必读 wiki 清单"自动生成,完成度有记录
季度 wiki 健康度	报告覆盖率、过时率、矛盾数、孤儿数

这些流程看起来是"流程税",但没有它,知识库 3 个月内必崩。

3.3 机制 3:角色(谁负责)

必须明确的三个角色,缺一就烂:

角色	数量	职责	通常谁来当
Schema Owner	1-2 人	维护规则、批准新分类、仲裁矛盾	架构师 / 首席工程师
Wiki Gardener	1-2 人(可兼职)	Review LLM 提议、处理 Lint 告警、清理孤儿	资深开发 / 模块 Owner
Module Owner	每个核心模块 1 人	本模块知识第一责任人,处理模块级 Lint	Tech Lead

关键原则：

LLM 没有写权限,只有"提议 + 写草稿"权限。所有 wiki 变更走 PR,人 review 后合并。
Lint 报告的"问题"是任务,不是建议。schema 规定:30 天内没人处理的 lint 告警,自动升级到模块 owner。
代码改 ≠ wiki 改。代码改动 wiki 不会自动跟着变------必须显式触发 LLM 维护流程(避免 LLM 把"理解"写得跟代码不同步)。
Schema 变更最难,门槛最高。改 schema = 改知识分类体系 = 几乎等于知识库重建,要走架构组 review。

最常被忽略的:Module Owner。没有模块级的"知识 owner",lint 告警就没人处理,wikipedia 就慢慢烂掉。

3.4 机制 4:考核(怎么让人愿意做)

指标	谁负责	怎么算
ADR 数量	Tech Lead	每个架构决策都有 ADR,无 ADR 不算决策
模块 Lint 告警处理率	Module Owner	30 天内处理 90%
新人 Onboarding 体验评分	Schema Owner	季度调研
事故复盘归档及时率	SRE/值班长	72h 内归档 100%
Wiki 覆盖率	全员	关键模块 100% 覆盖

考核的关键不是罚，是让"维护知识"成为"晋升/调薪"的输入项。没有这一条,所有机制都会被当成"额外工作"。

四、如何落地组织知识库

4.1 第一阶段：建骨架 + 立规矩

做这三件事,缺一不可:

Schema v0.1------五种知识类型的模板、命名、ADR 模板、LLM 行为规则、质量标准
ADR 流程------每次架构讨论必须产出一份 ADR,不产出不算"决策完成"
三个角色就位------Schema Owner、Wiki Gardener、首批 Module Owner(2-3 个核心模块)

为什么先做这个： Schema 是后面所有自动化的依据,角色是后面所有治理的依据。没有这两样,后面建的内容 100% 会烂。这一阶段零"内容产出",但价值是后面所有内容能活着的前提。

不做:不要在这一阶段接任何自动化、不要建任何 wiki 页面、不要写任何 Onboarding 文档。先立框架,再填内容。

4.2 第二阶段：高价值低成本的内容

优先填这两类------价值密度最高,LLM 自动化能跑通:

ADR------补历史的(过去 6 个月的重要架构决策)+ 立规矩(新决策必须有 ADR)
领域词典------LLM 从代码 + 会议纪要 + 文档自动抽取"业务名词 ↔ 代码模块 ↔ 负责人"

为什么排第二 :ADR 是研发团队的"宪法",新人入职第一周读的就是它,ROI 是最高的 ;领域词典可以 LLM 自动生成,建设成本接近零。这两类用 3-4 周跑通,团队的"知识基建"就有了底子。

同时启动"PR-ingest"流水线 ------PR 合并后自动写摘要到对应模块页。这是 LLM 维护 wiki 的最小可行循环,必须在内容开始有积累之前就上线,否则新内容从第一天起就过时。

4.3 第三阶段：核心运营内容 + Lint 体系

做这三件事:

API 契约 / 服务依赖图------LLM 从代码自动生成,人 review
事故档案------补历史的 + 立"事故 72h 归档"流程
Runbook------从告警 + 复盘 + 历史处理记录里 LLM 草拟,值班长 review

同时把 Lint 体系建全:

代码引用一致性（必做）
ADR 是否被代码推翻（必做）
孤儿页 / 内部矛盾 / 覆盖度（三选一先做）

为什么排第三:这一阶段内容"建得起但也烂得快",必须等 Lint 能查"代码引用一致性"之后再开始建,否则你建完当天就有过时内容。

Lint 体系是关键拐点------从这一阶段开始,wiki 才真正"自维护"。

4.4 第四阶段：自动化加深 + Agent 化

做这两类:

扩展自动化流水线------Issue-archive(工单归档)、ADR-trigger(代码集中变更触发 ADR 草稿)、定期 Wiki 健康度报告
暴露给 Agent 消费------把 wiki 接到 Claude Code / Cursor / 自研 Agent(MCP 协议),让开发工具直接消费知识

为什么排最后 :Agent 化是放大器------前三个阶段没跑通，Agent 化就是把混乱放大。前三个阶段是"造干净的水"，Agent 化是"接上水龙头"。顺序反了,水龙头放出来的是脏水。

Agent开发系列（九）-知识库建设（领域词典）-CSDN博客

Agent开发系列（十）-知识库建设（架构总览）-CSDN博客

Agent开发系列（十一）-知识库建设（知识地图）-CSDN博客

Agent开发系列（十二）-知识库建设（ADR）-CSDN博客