核心理念

这篇文章解释 AIOps 知识治理的设计思路：它要解决什么问题，为什么采用这些设计决策，以及它和传统文档管理的区别在哪里。

问题：AI coding agent 为什么需要不一样的知识管理

先看一个典型的日常场景：

你让 Claude Code 给用户认证模块加一个 OAuth 登录。它看了 auth.ts，加了 OAuth 流程。但它不知道三个月前团队在 ADR 里决定过"不做第三方登录，只维护自己的账号体系"。结果代码是对的，决策是错的。

这个场景的问题不在于 agent 的能力，而在于它拿不到做判断需要的上下文。

传统项目管理知识的做法是写文档——README、Wiki、设计文档、接口文档。这些文档对人来说没问题，但对 agent 有几个障碍：

结构不固定。同一类信息，A 项目写在 README 第三段，B 项目藏在 Wiki 子页面里。agent 不知道该去哪找。
更新滞后。代码改了三版，文档还是第一版的内容。agent 召回的是过时信息。
缺少关联。架构文档说"认证模块负责登录"，但接口变更记录在另一个地方。agent 不知道它们之间的关系。
叙事为主，事实分散。人写的文档倾向讲故事，把事实埋在大段描述中。agent 需要直接的事实陈述和明确的路径引用。

总结下来，agent 需要的知识管理和人需要的知识管理，关键差异在三个地方：

	给人看的知识	给 agent 用的知识
查找方式	浏览、搜索标题	按路径和关键词召回
内容偏好	连续叙事、背景铺垫	结构化事实、明确引用
更新频率	想起来才改	随代码变更自动触发

AIOps 知识治理的设计目标，就是建立一套 agent 能用的知识基础设施——同时不额外增加人的写作负担。

设计一：以项目为治理单位

不按"一篇文章"或"一个目录"管理。以整个项目为治理单位。

原因很简单：一条代码变更可能同时影响 PRD、架构、规格和工作流。如果治理系统只看单篇文档，它发现不了"改了接口规格，但架构图还指向旧接口"这种不一致。

实际做法：

.aiops/projects/<project>/
  project.yaml        # 项目元信息、产品注册表、文档路径
  iteration-bindings.yaml # 项目迭代、产品版本、微服务主分支绑定
  README.md           # 知识库索引（只做导航）
  open-questions.md   # 待确认的问题
  iterations/         # 项目迭代文档
  products/           # 产品和微服务文档
  guides/             # 给人读的连续叙事站点

项目下继续细分产品和微服务：产品描述产品版本、能力边界和产品内架构；微服务描述单个代码服务的接口、模型、运行形态、业务规则和验证入口。五类文档仍然存在，但它们落在项目、产品或微服务各自的目录里。

维护时关注的是整个项目知识库的一致性——改一个接口规格，可能影响微服务 specs、产品 architecture、项目迭代 release scope 和 guides。

设计二：两层文档模型

Agent 和人对文档的需求不同，所以分成两层。

Canonical 层（权威知识层）

这是事实来源。每一篇文档的目标读者是 agent。写法要求：

路径稳定，agent 知道去哪找
事实陈述直接，不埋在大段叙事里
引用源码路径、配置文件、接口签名，让 agent 可以验证
区分"已确认"和"推测"，不确定的内容写进 open-questions.md

Canonical 文档不需要好读。它需要准确、可召回、可维护。一个人读 PRD 的 canonical 文档可能觉得干巴巴的——这没问题，因为人应该去 reading 层看。

Reading 层（阅读层）

给人看的连续叙事，放在 guides/ 下面。内容从 canonical 层关联生成，用 VuePress 渲染成站点。

Reading 层的更新方向是单向的：canonical 层变更后同步更新 reading 层。保证人看到的信息和 agent 召回的信息来自同一份事实。

为什么不能只用一份文档

用一个常见的反对意见来回答："直接让 agent 读给人看的文档不行吗？"

短期内可以。但给人看的文档结构不稳定——每次重构目录、调整大纲，agent 的召回路径就变了。而且人在叙事中夹杂的背景、比喻、铺垫，对 agent 来说都是噪声。

两层模型的核心是分离关注点：canonical 管准确性和稳定性，reading 管可读性和导航。各司其职。

设计三：Hook 记录，Agent 维护

持续维护是所有文档系统的软肋。人工维护靠自觉，靠自觉就一定会过期。

AIOps 的维护机制分两层：

平台 Hook — Claude Code 和 Codex 的 Hook 在代码变更时自动追加记录到 .aiops/diff-records/pending.md。不做判断，只记录。
Agent 维护 — aiops-daily-doc-maintenance 技能定期被触发，读取 pending 记录，理解语义变化，召回受影响的文档，执行跨文档一致性更新。

Hook 是轻量的、可靠的。它不替代 agent 的判断，只保证"变更不会被漏掉"。真正需要理解语义的步骤留给 agent。

这个设计还有一个好处：人可以参与也可以不参与。在 high 和 xhigh 治理等级下，agent 自动维护并提交文档变更；在 low 和 medium 下，agent 提醒但等人确认。团队根据自己的情况选择。

设计四：三个场景，同一套知识结构

AIOps 知识治理按输入来源分成三个场景，但它们共享同一套知识结构：

历史项目入库：从已有代码逆向生成知识，输入是源码和旧文档
文档维护：随代码变更增量更新知识，输入是 Hook 的 pending 记录
新项目初始化：从需求输入建立知识骨架，输入是 PRD 或会议记录

不管从哪个入口进入，最终产出的都是同一套 .aiops/projects/<project>/ 知识结构。这意味着一个项目可以先从历史入库开始梳理，然后在后续开发中使用维护流程持续更新。中间不需要"切换系统"或"重建文档"。

新的维护锚点是 iteration-bindings.yaml。Agent 修改 canonical docs 前，应先确认当前项目迭代、相关产品版本和相关微服务主分支；本地源码分支与绑定主分支不一致时，默认提醒人工切换或确认，而不是按临时分支静默改写文档。

这套方案不做什么

弄清楚边界和弄清楚能力同样重要：

不替代人做决策。Agent 可以整理事实、发现不一致、提出建议，但架构决策、产品方向仍然是人来定。
不追求文档完美。第一轮只建立 agent 进入项目所需的最低知识闭环，之后持续迭代。从第一轮就开始用，边用边完善。
不绑定特定工具。技能和知识结构是标准化的，CLI 支持 Claude Code 和 Codex，未来可以扩展到更多平台。
不对代码做假设。Agent 维护文档的依据是源码、配置、测试和 Hook 记录，每项依据都可追溯。

下一步

理解了核心理念之后，可以按你的场景阅读对应的文档：

手上有老项目要整理 → 历史项目入库
项目在持续开发中 → 日常文档维护
刚启动一个新项目 → 新项目初始化
想了解背后的规则设计 → 治理模型