从 0 到 1 打造 AI 驱动的研发知识库实战指南
  AI

从 0 到 1 打造 AI 驱动的研发知识库实战指南

 次点击
 23 分钟阅读

如果项目完全没有过文档维护这就是从 0 到 1 补课的最佳时机。既然你现在是“文档白纸”，反而能通过 AI 建立起最纯净、最符合规范的体系。

操作核心： 你不需要手动写，你要做的是**“授权”和“审校”**。

以下是针对你的目录规范，为你设计的 “四步走”自动化文档抢救计划，以及对应的实操提示词。（前提是要安装好Obsidian的Skills，参考前面的文章）

准备工作：环境确认

在运行提示词前，确保你已经在项目根目录创建好了文件夹：
/docs/
├── raw/                 # 📦 原始资料输入区 (Read Only)
│   ├── 01-prd/          # 产品需求文档 (PRD) / 业务流程说明
│   ├── 02-architecture/ # 架构设计草案 / 技术方案评审文档
│   ├── 03-api_docs/     # 接口定义文件 (如 Swagger 导出的 Markdown/JSON)
│   ├── 04-database/     # 数据库字典 / 原始 SQL 建表脚本
│   ├── 05-domain/       # 业务领域模型 / 属性字典映射表
│   └── 09-archive/      # 已处理/过期的文件归档，禁止 AI 读取
├── wiki/                # 🧠 正式知识库输出区 (Write/Read)
│   ├── sources/         # AI 整理后的结构化知识点
│   ├── index.md         # 知识库入口导览
│   └── log.md           # 自动追加的更新日志
├── lib/                 # 📚 公共依赖层 (Submodule / Read Only)
└── assets/              # 🖼️ 静态资源区
    └── architecture.canvas # 图片、白板架构图等

快捷命令：创建所有目录

mkdir -p docs/raw/{01-prd,02-architecture,03-api_docs,04-database,05-domain,09-archive} docs/wiki/sources docs/lib docs/assets

如果你使用的是 Windows (PowerShell)，可以使用以下命令：

New-Item -ItemType Directory -Force -Path docs/raw/01-prd, docs/raw/02-architecture, docs/raw/03-api_docs, docs/raw/04-database, docs/raw/05-domain, docs/raw/09-archive, docs/wiki/sources, docs/lib, docs/assets

补充环节：引入公共知识库 (Submodule)

如果你们团队有跨项目的依赖如：架构规范、测试自动化规范或者公共字典表，强烈建议把它们独立成一个 Git 仓库，并作为 Submodule 引入到 docs/lib/ 目录下。这样所有项目都能实时查阅，且修改一处，处处生效。

引入命令：

# 将团队的公共规范仓库引入为只读子模块
git submodule add https://github.com/your-company/public-architecture-specs.git docs/lib/public-specs

# 拉取最新公共代码
git submodule update --init --recursive

第一步：代码“大普查”（生成原始技术素材）

这一步让 AI 扫描全量代码，将其转化为人类可读的“生料”放入 raw/。

实操指令（在 Claude Code 或 Cursor Chat 中输入）：

Prompt:
"你是系统架构师助手。请扫描当前 Java 项目的全量代码，为我执行‘技术逆向工程’，生成以下原始素材并存入 docs/raw/ 对应目录：

  1. 扫描 pom.xml 和配置类，生成 02-architecture/raw-tech-stack.md（包含技术栈版本、核心依赖、中间件）。

  2. 扫描所有 @Entity 和 DTO，生成 05-domain/raw-domain-models.md（列出所有核心实体及其关系）。

  3. 扫描所有 @Controller 或 @RestController，生成 03-api_docs/raw-api-list.md（列出所有 Endpoint、请求方法、输入输出描述）。

  4. 扫描目录结构，生成 02-architecture/raw-project-structure.md（解释包名规范和各模块职责）。

要求： 不要排版，不要美化，只需准确记录代码中反映的事实。完成后告诉我。"

第二步：业务逻辑“深挖”（生成逻辑素材）

代码结构有了，现在需要让 AI 解释“它是怎么跑的”。

实操指令：

Prompt:
"基于你刚才对代码的理解，请深入分析项目中的 Service 层和业务流，生成以下素材：

  1. 识别核心业务流程（如：下单、支付、用户注册），为每个流程生成一个简单的逻辑描述文件，放入 docs/raw/02-architecture/。

  2. 识别项目中的关键配置（如：分布式锁实现、缓存策略、异常处理机制），生成 02-architecture/raw-infra-logic.md。

  3. 参考 docs/lib/（如果已挂载子模块）中的架构规范，找出本项目代码实现中与之对应的部分，记录在 02-architecture/raw-spec-alignment.md。

要求： 重点描述逻辑，而不是粘贴代码。每一个逻辑点都要标注对应的类名。"

第三步：正式“编译” Wiki（从 Raw 到 Wiki）

这是最关键的一步，AI 将把杂乱的 raw 文件转化成相互关联的 Obsidian 知识库。

实操指令：

Prompt:
"现在，请作为一名资深技术文档工程师，将 docs/raw/ 下的所有‘生料’正式编译为 docs/wiki/sources/ 下的 Obsidian 维基。

规范要求：

  1. 文件命名： 使用 Prefix-Topic 格式（如 Arch-Project-Structure.md, Domain-Order-Entity.md, API-User-Services.md）。

  2. 建立链接： 必须使用 [[wikilinks]]。例如，在 API 文档中提到订单，必须链接到 [[Domain-Order-Entity]]。

  3. 元数据： 每个文件顶部必须包含 YAML Frontmatter（type, status: stable, tags）。

  4. 目录： 更新 docs/wiki/index.md，作为整个知识库的入口地图。

  5. 外部引用： 涉及架构原则时，请引用 docs/lib/ 目录下的相关规范。"

第四步：视觉化与自检（Canvas 与 关系图）

利用 Obsidian 的特性，让 AI 帮你画出拓扑图。
这一步的作用是给人看的，我们人类要看所有文档是不现实的，我们可以让Obsidian给我们生成一个拓扑图，帮助我们理解项目的架构和依赖关系。

实操指令：

Prompt:
"请调用 json-canvas 技能，根据 docs/wiki/sources/ 中的领域模型和 API 依赖关系，在 docs/assets/ 目录下生成一个名为 project-landscape.canvas 的文件。

要求： > 1. 将核心业务实体作为节点。
2. 使用连线表示它们的调用关系或依赖关系。
3. 在 Canvas 中添加一个说明面板，解释这个项目的核心架构模式（如：六边形架构或分层架构）。"

第五步：日常增量维护（让文档永不过时）

知识库建好后，最怕的就是“代码在跑，文档在睡”。借助 Claude Code 和 Obsidian Skills 的结合，后续的文档增量维护只需要你动动嘴皮子。

实操指令（按需选择）：

场景 A：小步重构后的精准更新

Prompt:
"我刚刚修改了 XxxQueryFacade 的核心逻辑，增加了一个校验参数。请读取最新的代码变更，使用 obsidian search 找出 docs/wiki/ 中引用了该类的笔记，并更新相关章节。同时在 docs/wiki/log.md 追加一条更新记录。"

场景 B：基于 Git 状态的无脑同步（大杀器）

Prompt:
"我刚才完成了一波代码 commit。请读取我的 git diff，评估这些修改影响了知识库中的哪些架构或 API 文档？如果有影响，请直接调用 Obsidian Skills 帮我更新它们，确保文档与最新代码对齐。"

场景 C：全新功能模块的接入

Prompt:
"我新开发了 KYC 认证模块，最新的 Swagger 接口定义我已经存入 docs/raw/03-api_docs/kyc-api.md。请结合我的最新代码和该接口文档，在 wiki/sources/ 下为其创建全新的系统笔记，记得打上对应的 tags，并把它挂载到 docs/wiki/index.md 的目录中。"

场景 D：对齐团队最新的公共规范

Prompt:
"我刚才执行了 git submodule update，团队的 docs/lib/ 公共规范库有了更新。请帮我检查一下 docs/lib/public-specs/ 里最新发布的《数据库表结构设计规范》，然后扫描我当前代码库中的所有 Entity，看看是否有不符合新规范的地方？如果有，请帮我在 docs/wiki/log.md 记录一份待办重构清单。"

落地建议：你是如何“开干”的？

  1. 分批次运行： 建议先跑“第一步”，等 AI 反馈生成了哪些文件，你进去看一眼，如果觉得准确，再跑后面的步骤。

  2. 提供外部上下文： 如果项目有 Swagger 接口文档地址，或者线上的需求文档，可以直接丢给 Claude Code 提取（利用 defuddle 技能抓取），存入 raw/ 目录，这样 AI 生成的知识库会更丰满。

  3. 纠偏机制： 如果在第一步发现 AI 对某个包的理解有误，立即回复：“com.xxx.adapter 这一层不是数据库访问，而是三方接口适配，请修正并重新生成。”

  4. 建立入口导航： 在第三步生成 Wiki 后，一定要让 AI 顺手更新一下 docs/wiki/index.md。这个文件是人类查阅知识库的起点，没有它会很容易迷失在海量节点中。

  5. Vibe 感受： 当你运行完这四步，你会发现 Obsidian 的 Graph View（关系图谱） 瞬间炸开，所有的代码逻辑已经形成了一个互相交织的网络。

现在，你就可以直接把第一步的提示词复制到你的 Claude Code 里。需要我帮你针对你具体的包名（比如 com.xxx.automation）微调一下提示词吗？

© 本文著作权归作者所有，未经许可不得转载使用。