在多人的研发团队中，文档往往是“熵增”最快的地方。为了解决文档没人写、没人看、没人同步的顽疾，我们引入了一套结合 Obsidian 思想与 Git Submodule 隔离机制的全新文档工作流。
一、 核心理念：从“手动维护”转向“自动化编译”
我们不再把文档看作死板的文字，而将其视为 “可编译的语料”。
输入 (Raw)： 研发过程中的碎片资料（SQL、代码、草案）。
编译器 (AI Agent)： 负责理解逻辑、建立关联。
产出 (Wiki)： 最终呈现在 Obsidian 中的结构化、可跳转的知识体系。
二、 目录规范：隔离与引用的艺术
我们在项目根目录约定了严格的 /docs/ 规范（本章着重讲 /docs/lib 文件夹），并通过 CLAUDE.md 约束 AI 行为：
/docs/
├── raw/ # 📦 原始资料输入区 (Read Only)
│ ├── 01-prd/ # 产品需求 / 业务流程
│ ├── 02-architecture/ # 架构草案
│ └── ... # 其他原始输入
├── wiki/ # 🧠 正式知识库输出区 (Write/Read)
│ ├── sources/ # AI 编译出的标准系统笔记
│ └── index.md # 知识库入口导览
├── lib/ # 📚 公共依赖层 (Git Submodule - Read Only)
│ ├── arch-kb/ # 全局架构规范
│ └── test-kb/ # 自动化测试标准
└── assets/ # 🖼️ 静态资源区 (Canvas, Images)
三、 深度解析：为什么 lib/ 规划为 Git Submodule？
这是本套方案中最具“架构感”的设计：在物理层面做“硬隔离”，在逻辑层面做“无感集成”。
1. 物理隔离：解决“知识腐烂”
单点维护： 架构规范和测试标准是公司级的资产。通过 Submodule 引入，意味着项目引用的永远是“标准源”。
版本锁死： 我们通过 Git 的 Commit ID 锁死依赖版本。当全局规范更新时，项目组可以根据自身节奏决定何时
git pull更新，避免文档内容产生“非预期抖动”。
2. 逻辑统一：对 Obsidian 的“透明性”
无感使用： Obsidian 并不感知 Submodule 的存在。对它而言，
lib/只是一个普通的文件夹。双向链接： 我们在项目 Wiki 中可以直接使用
[[lib/arch-kb/Auth-Standard]]引用全局规范。价值： 这种设计实现了 “分布式的管理权限” 与 “单体式的知识搜索体验”。
3. 项目独立：对 CI/CD 与新人友好
独立存在： 每个项目都是自洽的。如果不使用 Obsidian，它依然是一个标准的代码+文档库。
隔离修改： Submodule 机制强制了“只读”习惯。新人改不动
lib/，这保护了全局规范不被业务代码中的特例逻辑所污染。
四、 落地：AI 如何与这套结构协作？
当我们需要更新业务逻辑文档时，工作流如下：
投放语料： 将新的代码片段或设计草案丢进
/docs/raw/。调用编译器： 唤起 AI Agent：“请对比
raw/里的新 SQL 和lib/arch-kb里的设计规范，为我更新wiki/sources/下的领域模型笔记。”自动关联： AI 会在生成笔记时，自动识别
lib/下的外部依赖并打上双向链接。视觉观测： 开发者在 Obsidian 中打开
wiki/，通过 Graph View (关系图谱) 确认业务逻辑是否符合lib/定义的架构边界。
五、 给团队的建议
这套方案的目标是：让文档在 raw 里野蛮生长，在 wiki 里优雅编译，在 lib 里严谨统一。
作为研发成员，你只需要：
克隆时带上递归（如有外部依赖）：
git clone --recursive。维护好
raw/： 给 AI 提供真实的原材料。享受 Obsidian： 把它当作你理解复杂项目的 IDE。
一句话总结：
我们通过 Git Submodule 在各个项目间共享“法律”（lib），通过 AI 编译器在项目内生成“历史”（wiki），最终在 Obsidian 中统一我们的“认知”。
这种方案不仅是对独立项目最友好的管理方式，也是 AI 时代构建企业级知识图谱的最短路径。