运行与解答：系统必须自己会说话

代码是实现的真相，但不是语义的真相。交付一个系统的同时，必须交付一个能回答"这个系统能做什么、为什么这样做"的知识层——给人看，也给 AI 挂载。

一、被忽略的下半场

系统上线后，开发团队面对的高频请求其实只有两类：

业务的"能不能做"——运营问：这个功能支持吗？要传什么参数？改个规则要多久？传统链路是：业务问开发 → 开发翻代码 → 隔天回复。开发成了系统的人肉说明书，而且是唯一一本。

运维的"哪里出了问题"——告警响了，排查靠少数几个"熟悉这块"的人翻日志、读代码、凭记忆重建调用链。

有人会说：现在有 AI 了，直接让 AI 读代码回答不就行了？不够，原因有三：

1. 代码只有实现现状，没有语义。"为什么重复请求返回原单而不是报错"、"这个字段能不能改"、"这条限制是业务规则还是技术妥协"——都不在代码里，在当初的决策里；
2. 每次都从零推导。AI 读几万行代码重建一次系统理解，慢、贵、且结论不稳定——同一个问题两次回答可能不一致；
3. 推导结果无人背书。AI 从代码猜出来的接口语义，业务敢直接照着接吗？出了错算谁的？

这三个问题的共同根源：系统的语义从来没有被当成交付物。它散落在聊天记录、某个人的记忆和已经过时的 wiki 里。

二、方案：知识层——把系统语义做成交付物

知识层（knowledge layer）是与代码同库、随代码演进的一组结构化文档，人可读、AI 可挂载：

组成	内容	回答什么问题	更新时机
行为规格库	各模块的 EARS 规则（写法）	系统承诺了什么语义	需求变更时（变更走规格）
接口目录	端点、参数、错误码、权限、限流、幂等语义	调什么接口、传什么参数	随 PR，CI 强制
流程图 / 逻辑图	核心链路的 Mermaid 图（图即代码，入库）	这个流程怎么走、分支在哪	随 PR
ADR 决策记录	结构决策 + 理由 + 被否方案（格式）	为什么这样设计、能不能改	每次结构决策
数据字典	表、字段、约束、归属、敏感级别	数据在哪、什么含义	随迁移脚本
缺陷库	已知失效模式（组织方式）	这里以前出过什么事	验证闭环回流

四条组织原则：

① 知识层是交付物，不是事后文档。 它在工作单的输出要求里、在交付验收清单里（见交付物标准）。事后补写的文档从出生起就在腐烂。

② 图即代码。 流程图用 Mermaid 这类文本格式写、进版本库、随 PR diff 一起 review——AI 能生成、能更新、能检查图和代码是否漂移。截图和画板文件做不到这三点。

// Mermaid 示例（文本入库，diff 可审）
flowchart LR
  A[接收变更事件] --> B{幂等检查}
  B -- 已处理 --> C[跳过, 位点前移]
  B -- 新事件 --> D[类型映射/清洗]
  D --> E[目标端幂等写入]
  E --> F[提交位点]
  E -- 失败 --> G[错误记录表, 任务不中断]

③ 为 AI 消费而写。 结构化（表格、受控句式）优于散文；每个文档开头一句"本文档回答什么问题"；通过检索或 MCP 挂载给 AI。判断标准：AI 只读知识层（不读代码）能否正确回答业务的接口咨询——能，知识层合格。

④ 单一事实源。 知识层和代码同库同 PR，禁止在 wiki、聊天、口头维护第二份。这是规格驱动开发"变更走规格"纪律在运行期的延伸。

三、两个场景：换了行业，同一套机制

场景 A · 业务自助解答（智能仓储 WMS）

运营在群里问："波次拣选能不能按承运商截单时间自动排序？"

• 没有知识层：@开发 → 开发翻调度模块代码 → 半天后回复"现在不行，得改"；
• 有知识层：业务直接问挂载了知识层的 AI → AI 查接口目录（波次创建接口 strategy 参数支持 BY_CARRIER_CUTOFF 吗？不支持）→ 查行为规格（排波规则现有三条，无此规则）→ 查 ADR（排波策略设计为可插拔）→ 回答："当前不支持，现有策略为 X/Y/Z；扩展点已预留（策略接口可插拔），新增此规则影响面为调度模块内部，不动库存和面单。"——业务当场拿到答案和依据，开发只在真正立项时才进入。

场景 B · 故障排查（数据同步平台）

告警：某任务同步延迟持续增长。

• 排障 Agent 拿到三样输入：可观测指标（位点滞后量、目标端写入耗时上升）、知识层（位点语义：先写入后提位点；重试策略：指数退避）、调用链；
• 推理路径：位点滞后 + 写入耗时上升 → 瓶颈在目标端写入 → 查数据字典发现目标表本周新增了两个索引 → 结论：写入放大，附证据链；
• 人做的事：裁决结论、决定处置。整个定位过程没有人翻代码。

两个场景一个是仓储一个是数据基础设施，机制完全相同：结构化语义 + AI 检索 + 人裁决。这就是这套方法行业无关的含义——领域知识在知识层的"内容"里，方法论只规定"结构"。

四、排查闭环：修完必须回流

排查不是独立活动，它是验证闭环第四道闸门在运行期的延续：

告警 → 定位（AI：指标 + 知识层 + 调用链，输出证据链）
     → 裁决（人：确认根因，决定处置）
     → 修复（走工作单，L 级流程，不许热改）
     → 回归 → 回流：
        · 新失效模式 → 缺陷库
        · 语义被误解导致的故障 → 知识层补规格
        · 监控盲区 → 补指标

回流那一步是"闭环"和"救火"的区别：每次故障之后，系统要么防线变厚，要么可观测变好，要么知识层变准——三者必居其一，否则这次故障白出了。

五、防腐：知识层怎么不变成又一堆过时文档

过时的知识层比没有更危险——AI 会一本正经地引用它。三道防线：

• CI 强制同步：改接口签名的 PR 若未更新接口目录条目，构建失败（机制同 ArchUnit 边界测试——纪律进 CI，人和 AI 一视同仁）；
• 契约测试对齐：接口目录中的参数、错误码写成契约测试跑在 CI，目录和实现漂移即红；
• 定期审计：每个文档回答"删掉它，最近一个月哪个问题会答错？"——答不上来就归档（与上下文规则文件同一判据，知识层本质就是面向运行期的上下文工程）。

六、边界

• 原型和一次性脚本不需要知识层——它服务的是要长期运行、多人协作、业务会来问的系统；
• 知识层不是全量文档。实现细节、内部函数、临时逻辑不进知识层——只收录语义级内容（对外承诺、结构决策、数据含义）。"最小高信号集合"原则在文档层的投影：写得越全，腐烂越快，信噪比越低。

七、本章小结

• 交付后的两类高频请求（业务问"能不能做"、运维问"哪里坏了"）传统上都压在"人肉翻代码"上；AI 直接读代码也解决不了语义缺失、重复推导、结论无背书三个问题。
• 知识层 = 规格库 + 接口目录 + 流程图 + ADR + 数据字典 + 缺陷库，与代码同库同 PR，人可读、AI 可挂载。
• 四原则：交付物而非事后文档、图即代码、为 AI 消费而写、单一事实源。
• 排查闭环必须回流：每次故障后防线、可观测、知识层三者必厚其一。
• 机制行业无关：WMS 和数据同步平台用的是同一套结构，领域知识只是内容。

下一章 交付物标准，把"一次合格的交付到底包含什么"定成一张可验收的清单。

---

参考资料

• Anthropic, Model Context Protocol——知识层挂载给 AI 的标准通道。
• Mermaid——文本化图表：可入库、可 diff、可由 AI 生成与更新。
• llms.txt 提案（2024）——让网站/文档对 LLM 可结构化消费的社区规范，知识层对外发布时可采用。