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

目录一、组织知识库的分层架构二、知识分类:研发团队该存什么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、blamegit hook 定期 dumpPR Reviewdiff、讨论、批准记录GitHub / GitLab APIIssue/工单创建、关闭、根因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-ingestPR merged读 diff review,写 1-2 段摘要到对应模块页Daily-lint每天 0 点跑 5 类检查,出报告Issue-archive工单关闭非平凡工单 → 事故档案/常见问题ADR-trigger模块 N 个 PR 集中同方向草拟 ADR,提醒架构组 reviewLint 的 5 类检查是命脉:代码引用一致性:wiki 提到的代码路径是不是还存在ADR 现状一致性:代码是否已偏离 ADR孤儿页:有页面但没人引用内部矛盾:两页说相反的话覆盖度:哪些代码模块在 wiki 里完全没出现LLM 写的内容必须带机器标记:[ auto, last reviewed: date]。30 天没 review 的自动降权,这是 Schema 写死的。3.2 机制 2:流程(人参与的卡点)流程卡点PR reviewreview 模板必填是否需要更新 wiki重大架构变更合并前必须有 ADR,否则不准合事故复盘24h 内出初稿,72h 内归档到事故档案Onboarding新人首周必读 wiki 清单自动生成,完成度有记录季度 wiki 健康度报告覆盖率、过时率、矛盾数、孤儿数这些流程看起来是流程税,但没有它,知识库 3 个月内必崩。3.3 机制 3:角色(谁负责)必须明确的三个角色,缺一就烂:角色数量职责通常谁来当Schema Owner1-2 人维护规则、批准新分类、仲裁矛盾架构师 / 首席工程师Wiki Gardener1-2 人(可兼职)Review LLM 提议、处理 Lint 告警、清理孤儿资深开发 / 模块 OwnerModule Owner每个核心模块 1 人本模块知识第一责任人,处理模块级 LintTech 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 Owner30 天内处理 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 化是接上水龙头。顺序反了,水龙头放出来的是脏水。