文档治理实战:让 Wiki 重新变得可信

20天前我写过一个 《AI Native 时代，什么样的文档才能真正”协作”？》，最近我把这个问题具象化了，并且在AI的帮助下，找到了可能的解决方案,并且封装成了skill。

先回顾下问题——

给人读的问题:找文档 15 分钟起步,最后还是直接找人问。找到了也不敢信,经常需要查代码验证。新人入职三天还在问”这个接口怎么调”。上下游联调一半时间都在理解对方的系统。

给 AI 读的问题:Coding Agent 看了文档写出来的代码,业务逻辑一堆坑。文档里充斥着”如前文所述””该模块”这种指代,AI 根本检索不到上下文。大量约束、坑点、边界条件只存在于老员工脑子里.

AI Native 时代的新要求

AI Native 开发改变了文档的意义。

过去文档是”记录”——记录设计、记录流程、记录讨论结果。现在文档必须变成”协议”——AI 根据文档生成代码,人根据文档判断 AI 是否写对。

为什么会这样?

AI 会严格按照文档描述的逻辑写代码,不会像人类一样”灵活理解”。人类可以靠 Code Review 发现业务偏差,AI 会直接把错误逻辑写进代码。而且 AI 的 Context Window 有限,文档必须做到”一个主题一份闭环文档”。

问卷调研:现状触目惊心

我们对团队 23 位同事做了调研,结果验证了这些困境。

人读维度

查找效率方面,只有 26% 的人能在 5 分钟内找到信息,39% 的人已经形成”直接找人”的习惯。

内容准确度方面,87% 的人认为文档存在过期问题,43% 的人”经常需要查代码验证”文档真实性。

关键信息缺失是个普遍问题,变更记录、业务背景、接口协议、运维指南这四类信息都不完整。

AI 就绪度

文档结构化方面,91% 的文档不能直接给 AI 使用,78% 需人工补充上下文。

约束显性化方面,没人认为当前约束是完整记录的,100% 的团队存在隐知识问题。

存量清理方面,74% 的人不敢清理存量文档,当前没有文档生死机制,持续形成”文档垃圾山”。

核心矛盾

找到文档不等于敢用文档,最大阻力不是搜索,而是信任断裂。

真正影响协作和 AI 结果的,不是”有没有写”,而是关键约束是否脱离人脑。

文档对人已经不够省时间,对 AI 更是不够”自闭环”。

过时文档没人敢动,新文档没有稳定同步机制,噪音越来越大。

“没人看”本质上说明文档没有进入协作流程、问答流程和 AI 开发流程。

治理方法

基于这些问题,我们总结了一套文档治理方法。

第一步:资产盘点

遍历,不要搜索。

搜索只能找到包含关键词的文档,会遗漏大量不包含关键词但属于该 Wiki 的文档。实测发现搜索遗漏率可能高达 85%。

盘点时要收集主题、相关 wiki 页面、相关代码入口、Owner、使用频率、风险和当前可信度。

第二步:四问法初筛

对每篇文档问四个问题,快速判断是否需要校准:

Q1: 有代码路径或文件名吗?比如 GitLab URL、文件路径、目录名。

Q2: 有技术实现描述吗?比如算法描述、架构图、接口定义.

Q3: 新人会用它写代码吗?比如”如何”步骤、环境搭建、代码示例.

Q4: AI 会用它继续开发吗?比如代码入口点、模块依赖、架构设计.

只要满足一个问题,就需要校准。

第三步:三方校准

对重要文档做三方对比:Wiki 说了什么、代码实际是什么、Owner 确认是什么。

校准重点是代码路径是否存在、算法描述是否匹配实现、配置参数是否一致、边界条件是否文档化、代码在哪个分支。

输出三方校准卡片,记录什么一致、什么不一致、什么需要 Owner 确认。

第四步:行动决策

每篇文档归类为四种行动:

retain: 仍然当前,内容准确,补充元数据即可。

revise: 核心仍有效,部分内容过时,更新过时部分。

rewrite: 重要但不可信,大量内容过时,全文重写。

archive: 历史文档,不再使用,标记为”历史/过期”。

关键是历史文档可以保留,但要标记为”历史”,不能假装是当前的。一个主题一份正式文档,避免重复和混淆。

第五步:正式化

对重要主题,创建或更新一份正式文档。

必须包含:这是什么、谁会用、当前规则、代码入口、Owner、状态、最后更新时间。

结构上要标题语义化,比如”Flink 实时数仓数据倾斜的排查与解决步骤”而不是”常见问题”。每个段落要能独立表达逻辑,不依赖”如前文所述”。约束要显性化,明确”禁止””必须”,不用”建议””推荐”。要消除代词模糊,”该模块”改成具体模块名。

第六步:治理循环

建立更新机制,避免文档再次腐化。

定义哪些变更需要写回 Wiki,比如 API 变更、架构调整、接口协议修改。定义谁审批更新,比如 Owner 和 Tech Lead。定义多久检查一次,月度或季度。

建立文档生死机制,可以废弃、可以归档、可以标记过期。

执行策略:AI 和 Owner 分工

治理失败常见原因是把所有工作都推给 Owner,Owner 拖延或拒绝。

我们用混合执行方案。

Phase 1: AI 帮忙补充技术性内容(1.5 小时)

AI 负责补充代码路径、创建 API Reference 文档、创建 Configuration Reference 文档、创建 Code Structure 文档。

输出到治理报告,不要直接修改原 Wiki 文档。

Phase 2: Owner 确认业务性问题(30 分钟)

Owner 负责 P0 时效性问题:API Host 是否还有效、S3 链接是否已过期、代码路径是否还存在、流程是否还是最新的。

P1 业务细节:QPS 限制是多少、超时时间设置多少、降级策略是什么.

P2 常见问题:实际遇到过哪些坑、哪些错误最常见.

提供问题清单,Owner 30 分钟内完成。

Phase 3: AI 帮忙更新文档(1 小时)

AI 根据 Owner 的回答更新文档,补充错误处理说明,补充常见问题.

分工原则是 AI 做技术性内容(客观性,基于代码),Owner 做业务性确认(主观性,基于经验),所有输出先到治理报告,确认后再改原 Wiki.

AI Native 时代的更高要求

基于问卷调研,我们明确了 AI Native 开发对文档的新标准.

目标是接口透明、逻辑闭环,让外部同事不找我们开会就能把事做成,让 AI Agent 不产生业务偏见就能把代码写对.

文档即协议,文档是代码的”高维表征”,人通过高维表征理解意图,AI 通过高维表征生成/优化代码.

隐知识显性化,把”只有老员工知道”的约束、坑点、边界条件变成 AI 和新人都能消费的显性知识。

建立文档生死机制,不是让每篇文档都更漂亮,而是让文档有保留、废弃、归档、过期标记.

形成消费闭环,文档不只是”被存起来”,而是能真正被 OpenClaw 问答、Coding Agent、开发协作、文档更新流程持续消费.

工具化

为了更高效地执行这套流程,我把整个治理方法封装成了一个 wiki-governance-ops skill,可以直接在 OpenClaw 中使用。

核心能力包括自动化盘点、四问法初筛、三方校准支持、行动决策建议、Owner 问题生成、治理报告生成。

使用方式是在 OpenClaw/ClaudeCode 中说”帮我做 wiki 治理”,并且附上WIki和入口和代码链接,OpenClaw/ClaudeCode 会引导你完成整个流程:遍历盘点文档、用四问法初筛、对核心文档做三方校准、生成行动决策和问题清单、和 Owner 确认后更新文档.

技术实现上用飞书 MCP 读取 Wiki 文档内容,用 GitLab API 提取代码路径和结构,用 AI 分析对比文档和代码识别不一致,自动生成问题清单、治理报告、正式文档模板。

已在实际项目中验证有效,可以显著降低文档治理的人力成本,同时提升文档质量和可信度.

如何开始

Wiki 治理不需要一次性做完,可以从一个领域试点.

第一步选择试点领域,选择你负责的模块,或者选择文档质量最影响协作的模块.

第二步使用 wiki-governance-ops skill,在 OpenClaw 中说”帮我做 [模块名] 的 wiki 治理”,AI 会自动执行盘点、初筛、校准流程.

第三步生成治理报告,包含问题和建议,包含 Owner 问题清单.

第四步和 Owner 确认后更新文档,AI 帮忙技术性内容,Owner 确认业务性问题.

第五步建立月度检查,定期检查文档时效性,建立文档生死机制.

不要从代码生成 Wiki,代码会变,Wiki 会过时.按主题处理,不是按页数,重要的先做. AI 可以帮忙,但人决定真相,技术性内容 AI 做,业务性问题 Owner 确认.每个重要主题一份正式文档,历史文档要标记.先让项目级上下文能用,再谈全库治理.