设计思路 · 调研与选型

为什么这样设计知识库体系

不是拍脑袋选一个"时髦"的范式，而是基于对开源项目和大厂实践的系统调研，提炼六大设计范式的取舍，再组合出能同时解决 P1-P5 全部痛点的方案。

23+
开源项目
10
大厂实践
6
范式对比
5
核心痛点
起点 · 问题

我们要解决的五个痛点

任何知识库体系都不能抽象地讨论"好"与"坏"——只有对着具体问题，才能判断某个设计是否值得落地。

#
问题
表现
根因
P1
AI 不了解项目上下文
生成的代码不符合架构、不复用已有组件、命名不一致
repo 里没有 AI 上下文文件，或写得极粗糙
P2
产品 Spec → 研发上下文断层
研发拿到需求要自己理解、拆解、重新整理才能喂给 AI
产品文档在内部文档平台，格式不统一，AI 无法直接消费
P3
跨团队重复造轮子
A 团队踩的坑、总结的实践，B 团队完全不知道
没有跨团队知识共享机制
P4
AI 不懂业务领域
供应链、商品、交易的专有概念和业务规则 AI 频繁出错
业务知识散落在人脑和碎片文档中，未结构化
P5
知识腐烂
文档写完就过时，Spec 和实现逐渐 drift
没有自动化的新鲜度检测和一致性校验机制
方向 · 目标

六条可验证的设计目标

每条目标都能翻译成可观测的工程结果——这意味着最终方案是否成立，可以事后被验证而不是靠感觉。

G1 · 三层知识体系全局 → 项目 → 需求，三个粒度全覆盖。
G2 · 产品工作流不变PM 继续在内部文档平台写作，同步管线自动转化结构化知识。
G3 · AI 原生可读每个 repo 有标准化 .ai/ 目录，所有主流 AI 编码工具直接读取。
G4 · 跨团队知识汇聚规范、实践、踩坑、词典集中管理、自动下发到各仓库。
G5 · 抗腐烂自动化管线保障知识新鲜度和 Spec-实现一致性。
G6 · 低人工成本配套 AI 技能覆盖创建和维护全流程，降低知识维护开销。
调研 · 六大范式

业界有哪些解法，各自的局限

我们从 23 个开源项目和 10 家大厂实践中提炼出六种主流设计范式。下面逐个展开：代表项目、核心思想、六维评分、我们采纳/不采纳的部分和理由。

范式一

指令文件模式 · AI Context as File

核心思想：repo 根目录放 Markdown 文件（CLAUDE.md / .cursorrules / AGENTS.md），告诉 AI 项目规则。所有主流 AI 工具原生读取。
awesome-cursorrules ★39K AGENTS.md 6万+ 项目 context-engineering-intro ★12.7K Aider ★43K
覆盖范围★★★★★
维护成本★★★★★
抗腐烂★★★★★
AI 适配★★★★★
产品参与★★★★★
跨团队复用★★★★★
采纳.ai/ 目录结构、YAML front-matter 元数据、per-directory 嵌套指令（来自 AGENTS.md）。
不采纳单文件模式（复杂项目 token 超限）；纯编码规则视角（不能覆盖业务知识）。
范式二

仓库即知识库 · Repo as Context

核心思想：代码本身是最权威的知识，用工具结构化地喂给 AI，不需要额外维护文档。
repomix ★23.6K gitingest ★14.3K gpt-repository-loader ★3K
覆盖范围★★★★★
维护成本★★★★★
抗腐烂★★★★★
AI 适配★★★★★
产品参与★★★★★
跨团队复用★★★★★
采纳Aider 的 repo-map 思想（AST 提取关键结构而非全量代码），作为 .ai/CONTEXT.md 自动生成的数据源。
不采纳全量打包模式——存量"屎山"代码会误导 AI；只有"怎么做"，没有"为什么"和"应该做什么"。
范式三

决策记录 · Architecture Decision Records

核心思想：只记录决策（Context → Decision → Consequences），每个决策一个文件，编号递增，可被后续决策 supersede。
architecture-decision-record ★15.6K adr-tools ★5.4K log4brains ★1.4K
覆盖范围★★★★★
维护成本★★★★★
抗腐烂★★★★★
AI 适配★★★★★
产品参与★★★★★
跨团队复用★★★★★
采纳Context/Decision/Consequences 模板结构，扩展为产品决策记录（PDR）；adr-tools 的 CLI 工作流（create/list/link/supersede）。
不采纳只做架构决策——覆盖面太窄，无法独立支撑业务领域知识和编码规范。
范式四

活文档 · Living Documentation

核心思想：需求规格 = 测试用例 = 文档，三者同一份文件。代码变了测试失败，文档自动"报警"——从根本上解决腐烂问题。
gauge (ThoughtWorks) ★3.2K serenity-bdd ★700+ Cucumber Given-When-Then
覆盖范围★★★★★
维护成本★★★★★
抗腐烂★★★★★
AI 适配★★★★★
产品参与★★★★★
跨团队复用★★★★★
采纳"Spec 与实现绑定"的核心理念——通过 CI 管线做 Spec vs 实现的 diff 校验（轻量化活文档）；Gauge 的 Spec-as-Markdown 格式印证 gospec Spec 模板；Serenity 需求覆盖率追踪纳入一致性管线。
不采纳完整 BDD 执行——落地太重，国内实践普遍不理想；覆盖范围也不够（只覆盖功能行为）。
范式五

开发者门户 · Developer Portal

核心思想：统一的知识门户提供服务目录、TechDocs、API、模板。产品研发在同一个平台协作，知识沉淀在平台上。
Backstage (Spotify) ★33.1K Outline ★38.1K BookStack ★18.7K Docusaurus (Meta) ★64.6K
大厂实践参照：GitLab Handbook-first · Google g3doc + Design Doc · Spotify Backstage + TechDocs · 字节跳动飞书知识中枢 · 阿里巴巴语雀 Book/Chapter/Page · Stripe RFC 文化
覆盖范围★★★★★
维护成本★★★★★
抗腐烂★★★★★
AI 适配★★★★★
产品参与★★★★★
跨团队复用★★★★★
采纳Backstage TechDocs 的"Markdown in repo → 自动发布到门户"模式——内部文档平台做人的阅读入口，git 做 AI 消费端，同步管线连接两者；GitLab Handbook-first 的知识变更审查理念；BookStack 的 Book/Chapter/Page 层次组织产品知识库。
不采纳建新门户平台——团队已有内部文档平台，推广新平台阻力太大；AI 工具不能直接读取门户内容。
范式六

知识图谱 · Code Knowledge Graph

核心思想：用 LSP / tree-sitter 解析代码，构建可查询的知识图谱。AI 精准查询，token 消耗最低。
code-to-knowledge-graph code-review-graph 减少 6.8x token
覆盖范围★★★★★
维护成本★★★★★
抗腐烂★★★★★
AI 适配★★★★★
产品参与★★★★★
跨团队复用★★★★★
采纳"需求→代码"关联追踪的思想——短期用轻量方式实现（文件级交叉引用 + front-matter 标签）。
不采纳图数据库基础设施——技术门槛太高，当前项目过于早期；作为远期演进方向保留。
决策 · 选型

结论：组合范式，取各家之长

没有任何单一范式能同时解决 P1-P5 全部问题。选型逻辑是——先锚定问题，再按痛点拼合范式。

问题 对应范式 采纳方式
P1 AI 不了解项目上下文 范式一（指令文件） 每个 repo 标准化 .ai/ 目录
P2 Spec → 研发上下文断层 范式五（门户，内部文档平台 ↔ git 同步） 内部文档平台作为产品写作端，git 作为 AI 消费端，同步管线连接
P3 跨团队重复造轮子 范式三（决策记录）+ 范式五（门户） 全局 knowledge-base repo 集中管理最佳实践和踩坑记录
P4 AI 不懂业务领域 范式五（结构化领域知识） 产品知识库中的 domain-rules/ 和 glossary/
P5 知识腐烂 范式四（活文档） Spec vs 实现 diff 校验 + 新鲜度扫描（轻量化活文档）

为什么不选单一范式？

  • 纯"指令文件"（范式一）解决不了业务知识和跨团队复用
  • 纯"开发者门户"（范式五）在已有内部文档平台的前提下推广阻力太大，且 AI 不能直接读取
  • 纯"活文档"（范式四）落地太重，BDD 在国内实践普遍不理想，覆盖范围不够
  • 纯"知识图谱"（范式六）技术门槛太高，项目过于早期

为什么是这个组合？

  • 范式一为基座：.ai/ 是所有 AI 工具原生入口，零集成成本，必选项
  • 范式五提供产品侧入口：PM 不可能离开内部文档平台，用同步管线桥接两个世界
  • 范式三提供决策追踪：ADR 的三段式模板天然适合产品和架构决策
  • 范式四提供抗腐烂能力：不做完整 BDD，但采纳 Spec-实现绑定校验
  • 范式二、六作为补充：repo-map 用于自动生成上下文；知识图谱作为远期方向
落地 · 架构

三层知识 + 两条管线

最终架构直接对应选型决策：三层解决"知识放在哪里"，两条管线解决"知识怎么流动、怎么不腐烂"。

全局知识层 · knowledge-base repo

源自 · 范式三 ADR + 范式五 门户理念

domain/（供应链/商品/导购/交易）· standards/ 编码规范基线 · patterns/ 跨团队最佳实践 · pitfalls/ 踩坑记录 · glossary/ 全局术语表

↕ 自动同步：规则下发 / 实践上报

项目知识层 · 每个 repo 的 .ai/ 目录

源自 · 范式一 指令文件 + 范式二 repo-map

CONTEXT.md 项目上下文 · RULES.md 编码规则（含全局继承）· DOMAIN.md 本项目业务知识 · SPECS.md 当前活跃 Spec 摘要 · CHANGELOG.ai.md 面向 AI 的变更日志

↕ Spec 桥接

需求知识层 · 产品知识库 + 文档平台同步

源自 · 范式五 门户 + 范式三 决策记录

product-knowledge repo（AI 消费端）：specs/ · domain-rules/ · decisions/ PDR · faq/
内部文档平台（PM 主写端，人的阅读入口）

管线 A · 知识流动
参考：范式五 Backstage TechDocs 双向同步
  • 内部文档平台文档 → 同步管线 → product-knowledge repo（结构化提取）
  • Spec 发布 → 提取业务规则/接口/术语 → 注入 .ai/SPECS.md
  • 全局规则变更 → 自动同步到各 repo 的 .ai/RULES.md
  • 研发踩坑 → 提炼 → 上报到全局 patterns/ 和 pitfalls/
  • 一致性偏差 → 自动回写到文档平台评论区（反向通知产品）
管线 B · 一致性守护
参考：范式四 活文档 Spec-实现绑定
  • 代码 MR → 检查 .ai/ 是否需要同步更新 → 告警/阻断
  • Spec 变更 → diff 分析 → 标记受影响代码区域和负责人
  • 定期扫描 → 文档新鲜度报告 → 标记腐烂文档
  • 迭代结束 → Spec vs 实现一致性校验 → 输出偏差报告

这套设计最终落地成什么？

以上调研和决策最终转化为三阶段交付：10 个 AI 技能、4 份使用指南、6 项效能指标。每一个技能或指南，都能在上面的选型逻辑里找到来源。

查看交付物 → 阅读完整设计文档（917 行）