Harness Engineering 实践：LLM Wiki 什么时候、怎么引入?

LLM Wiki 的作用是什么？什么时候开始引入？

最近想单独写 LLM Wiki，是因为看到旁边团队一上来就准备直接引入 LLM Wiki。

问题不在于 LLM Wiki 不好，而在于他们的基础知识建设还没落地。产品规划、需求设计、技术方案、接口约束、测试用例、测试执行、评审记录、发布记录、运行约束都还没有形成稳定事实源，就准备把 LLM Wiki 放到产研知识体系的入口位置。

这事看起来先进，但风险不小。

如果底层知识不可信，LLM Wiki 很容易把“混乱”包装成“智能”。回答很流畅，页面很完整，但事实可能还是散的、旧的、没人负责的。

我个人的实践观点：

和产品交付直接相关的核心知识，应该优先进入 Git 知识底座；LLM Wiki 是这个场景的补充阅读层。在其他非核心、弱约束、探索型知识场景里，LLM Wiki 可以承担更多主力工作。

这里说的“研发团队”，不是只写代码的开发团队，而是完整的产研交付团队：产品、设计、开发、测试、运维。因为真实的软件质量，不是代码一个环节决定的。

产品定义会影响代码，测试结论会影响发布，运行约束会反向影响设计。只要这些知识和产品交付强相关，就不能只放在一个会总结、会问答的 Wiki 里。

一、LLM Wiki 到底是什么

LLM Wiki 不是传统 Wiki。

它通常把代码仓库、产品文档、设计文档、测试资产、Issue、PR、发布记录、Runbook 等资料接入后，通过模型完成索引、摘要、结构化、语义检索和自然语言问答。

它最有价值的地方，不是“保存知识”，而是“读懂已有知识”。

比如新人接手一个订单模块，LLM Wiki 可以帮助他快速理解业务场景、模块边界、相关接口、测试关注点和历史风险。产品同学可以问某个能力是否已有类似设计，测试同学可以问某个异常场景过去是否覆盖过，Agent 可以用它快速定位背景材料。

但边界也要说清楚：

LLM Wiki 不适合替代产品评审、需求澄清、架构决策、测试设计、代码 Review 和发布审批。

LLM Wiki 擅长解释，不擅长负责。

负责这件事，仍然要回到团队的产研流程和事实源。

二、哪些知识应该进 Git，哪些适合交给 LLM Wiki

讨论 LLM Wiki 之前，先要把知识分层。

我会把产研知识粗略分成三类。

第一类，是和产品交付直接相关的核心知识。

包括正式 PRD、验收标准、技术方案、ADR、API contract、数据模型、核心测试用例、自动化用例索引、测试执行结论、发布记录、Runbook、traceability。

这类知识一旦和代码不一致，就会影响交付质量。它应该优先进入 Git 或同等可版本化、可审计、可追溯的事实源。

原因很简单：Git 离代码近，天然有版本、差异、分支、Review、回滚和审计。产品定义变了，代码要跟着变；接口变了，测试要跟着变；Runbook 变了，发布和运维动作要跟着变。这些变化最好在同一条变更链路里被看见。

第二类，是过程态知识。

比如 PRD 草稿、方案讨论、测试计划草稿、评审意见、缺陷分析、待确认问题。这类知识可以先放在 change-requests/CR-* 里（我这里用的CR，其他团队可能用的issue、task之类的，不碍事），跟着一次变更走。等评审通过、代码合并、测试完成，再把稳定部分写回 specs/、delivery/ 或 constraints/。

LLM Wiki 可以读取它们，但必须知道它们是过程态，不能默认当成最终事实。

第三类，是探索型和横向知识。

比如早期产品脑暴、客户访谈、竞品观察、会议纪要、市场材料、团队经验贴、临时调研。这类知识不一定要全部进 Git。它们更适合放在协作文档工具里，再由 LLM Wiki 做检索、摘要和问答。

也就是说，LLM Wiki 的适配范围要收缩：

产品交付强相关：Git 是主事实源，LLM Wiki 做阅读和检索补充。

探索沟通弱相关：协作文档加 LLM Wiki，可以承担更多主力工作。

三、Git 知识底座和 LLM Wiki 怎么配合

我不建议把问题讨论成“到底用 Git 还是用 Wiki”。

这是一种偷懒的二分法。

更合理的关系是：Git 管事实，LLM Wiki 管使用。

Git 知识底座解决的是：

•哪些内容是当前事实；•谁改过，为什么改；•改动是否经过 Review；•产品、技术、测试基线是什么；•需求、设计、代码、测试、缺陷、发布之间怎么追溯。

LLM Wiki 解决的是：

•人怎么更快理解这些事实；•产品、开发、测试怎么跨角色查资料；•Agent 怎么快速定位上下文；•历史知识怎么更容易被发现。

组合方式可以很简单。

关键产研知识进入 Git；协作文档保留探索和沟通；LLM Wiki 索引两边，但回答必须带来源；发现 Wiki 回答有问题时，不在 Wiki 页面里“修表述”，而是回到源头改 PRD、SDD、测试用例、Runbook 或 ADR。

还有一个规则很重要：

一个问题被问三次，就不应该只存在于问答记录里。

如果团队反复问“这个需求验收标准是什么”“这个异常场景测没测”“这个接口为什么不能改”，说明源文档不够好。正确动作是回写知识底座，而不是夸 LLM Wiki 终于答出来了。

四、什么时候该引入 LLM Wiki

我建议不要按工具热度引入，而要按团队阶段引入。

小团队、早期产品，先别急。

如果团队只有几个人，产品还在快速试错，产品、开发、测试靠高频沟通推进，优先把最小事实源建起来：产品目标、关键 PRD、验收标准、核心测试用例、关键 ADR、Runbook、接口说明、AGENTS.md。这时候上完整 LLM Wiki，容易制造虚假的完整感。

中等团队、模块变多，可以小范围试点。

当团队开始出现新人理解慢、跨模块问题总要问老人、测试回归范围靠经验、文档“曾经是对的”这些现象，就可以选一个知识密度高的模块试点，比如订单、权限、计费、工作流。

试点时不要看页面生成得漂不漂亮，要看几个信号：回答是否引用来源，错误是否能追溯到源文档，高频问题是否能回写，测试同学是否更容易定位影响范围，Agent 是否少找错上下文。

大团队、复杂系统，LLM Wiki 价值会明显变大。

当仓库多、产品线复杂、测试矩阵复杂、跨团队协作频繁，真正的成本不是写一篇文档，而是找到可信答案。这时候 LLM Wiki 可以成为产研组织的知识入口层。

但越是大团队，越要配套权限、数据分级、来源追溯、回答质量抽检和成本控制。

没有这些治理，LLM Wiki 只是一个更大的误导入口。

五、成本不是只有钱

很多团队评估 LLM Wiki，只看工具订阅费和 token 成本。

这太窄了。

真正的成本至少有五类：

•维护成本：索引范围、刷新频率、历史归档、源系统接入都要有人管；•治理成本：回答错了，谁负责修源头；•安全成本：客户信息、测试数据、故障复盘、未发布功能都可能被过度暴露；•质量成本：八九不离十的回答最危险，尤其会影响新人、测试判断和 Agent 执行；•组织复杂度：多一个入口，就多一套权限、流程、责任边界和故障点。

这些成本不是坏事，但它们是真实存在的。

所以不要为了“我们也有 AI Wiki”而引入。那基本属于给组织加装饰件。

六、一个务实的引入路径

如果让我给一个产研团队设计引入路径，我会分四步。

第一步，先把关键产研知识收进 Git 或可追溯事实源。

不用一开始很完整，但至少让核心模块的 PRD、验收标准、SDD、ADR、API contract、核心测试用例、测试策略、Runbook、traceability 有稳定位置。

第二步，建立最小状态模型。

至少区分探索中、草稿、评审中、已批准、执行中、已发布、已归档。否则 LLM Wiki 会把所有材料都当成同一类“资料”。

第三步，选择一个模块试点。

不要全量铺开。选一个复杂但边界清楚的模块，接入产品定义、代码、CR 记录、测试资产、缺陷记录、Runbook 和 ADR，观察问答质量。

第四步，把问答反馈纳入知识回写。

每周看一次高频问题和错误回答。能修产品文档的修产品文档，能补 ADR 的补 ADR，能补测试用例的补测试用例，能改 Runbook 的改 Runbook。

LLM Wiki 的价值，不是让大家少写文档，而是让团队更容易发现哪些事实已经漂移、哪些测试资产没有跟上、哪些知识应该回到主事实源。

七、最后还是那个老判断：别盲目引入

我现在对很多 AI 工程工具的态度都差不多：

先承认它有价值，再判断自己是否到了该承担它代价的时候。

LLM Wiki 当然有价值。它能降低理解成本，改善新人 onboarding，帮助跨角色检索，辅助 Agent 定位上下文，也能让历史知识重新被看见。

但它不是免费的。

不是说价格不免费，而是复杂度不免费、治理不免费、质量风险不免费、安全边界不免费。

所以关键不是“要不要 LLM Wiki”，而是先问几个问题：

你的产研事实源是否已经相对稳定？
你的文档状态是否能区分探索、过程和基线？
你的核心知识是否能追溯到产品规划、需求、设计、代码、测试、评审和发布？
你的测试用例、测试规划、测试执行和质量结论是否已经进入知识链路？
你的团队是否有人负责修正错误回答背后的源头？
你的 AI Agent 是否知道 Wiki 只是导航，不是最终裁决？

如果这些问题还没有答案，先别急着上大系统。

先把 Git 知识底座补起来，至少先把和产品交付直接相关的事实补起来。

如果新人理解系统慢，产品、研发、测试之间反复对口径，跨仓库查资料痛苦，Agent 经常找错上下文，老文档和新代码、新测试不断打架，那就可以引入 LLM Wiki。

但引入方式应该是：小范围试点，源头可追溯，回答可校验，问题可回写，权限可控制。

Git 负责让产品交付知识可信，LLM Wiki 负责让知识更容易被使用。

这两件事都重要。

但顺序不能乱。