目录
一、组织知识库的分层架构
二、知识分类:研发团队该存什么
2.1 输入层:Raw Sources(原始事实)
2.2 沉淀层:Wiki(可消费的"理解")
2.3 规则层:Schema(约束一切)
三、LLM 自动化流水线
3.1 机制 1:自动化(机器跑的部分)
3.2 机制 2:流程(人参与的"卡点")
3.3 机制 3:角色(谁负责)
3.4 机制 4:考核(怎么让人愿意做)
四、如何落地组织知识库
4.1 第一阶段：建骨架 + 立规矩
4.2 第二阶段：高价值低成本的内容
4.3 第三阶段：核心运营内容 + Lint 体系
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 化是"接上水龙头"。顺序反了,水龙头放出来的是脏水。
