AI 知识库最佳实践：用纯文件系统构建 Agent 可用的知识库

我的知识库有 1000 多个文件，涵盖 7 个品牌的内容资产、60 多条工作流、80 多个 CLI 工具的配置——Claude Code 能在 3 秒内精确定位到任何一个文件，不用向量数据库，不用 RAG 管线，靠的是纯文件系统加一套 CLAUDE.md 多级路由。

这篇文章拆解这套方案的完整设计。你读完就能从零搭一个同款知识库，让 AI Agent 像翻目录一样找到它需要的一切。

要点速览

• 纯文件系统 + CLAUDE.md 路由方案在 1000 文件规模内精度碾压 RAG
• 多级路由分 L0-L5 六层，每层收窄搜索范围，Agent 最多读 3 个文件就能定位目标
• 8 个顶层目录按职责分区，触发词路由表让 Agent 零歧义匹配
• 本地 CLI 做确定性审计和归档，判断逻辑不藏进黑箱
• 规模化靠归档分层（活跃 → 收件箱 → NAS）控制活跃文件数量

为什么不用向量数据库

先回答最多人问的问题：都 2026 年了，为什么不直接上 RAG？

答案很直接——对 AI 编程 Agent 的工作场景来说，向量数据库解决的不是我的问题。

RAG（Retrieval-Augmented Generation，检索增强生成）管线的核心假设是：你有一大堆非结构化文本，需要用语义相似度从中捞出相关片段喂给大模型。这个假设在客服知识库、法律文档检索、海量论文查询的场景下完全成立。

但 AI Agent 的知识库不一样。它的特征是：

结构化程度高——每个文件有明确职责，放在哪个目录、叫什么名字、管什么事情都是确定的。

访问模式确定——Agent 要么是按触发词路由到目标文件，要么是按工作流步骤顺序读取。不存在「我也不知道在哪，帮我模糊搜一下」的场景。

精度要求极高——Agent 取到错误的文件会直接执行错误的操作。RAG 的召回率 80% 在聊天机器人上可以接受，在 Agent 工作流里是灾难。

迁移审计成本——文件就是正本。cat 能读、rg 能搜、git 能追踪。向量数据库的 embedding 是黑箱，换个模型全部重建。

💡 通俗讲：向量数据库像百度——你输入关键词，它给你「可能相关」的结果，你得自己判断哪个对。CLAUDE.md 路由像目录——你知道要找什么，它告诉你在第几层第几个抽屉，打开就是。

这不是说 RAG 没用。当你的知识库超过 10000 个文件、内容高度非结构化（比如扫描件、客服对话记录、用户评论）、查询意图模糊时，RAG 是正确选择。但对于我这种「个人工作流知识库」的规模和结构，文件系统方案的精度和可维护性碾压。

和 Karpathy 的 LLM Wiki 的关系

2025 年 Andrej Karpathy 提出了 LLM Wiki 模式——用结构化 Markdown 文件组成一个 AI 可维护的个人知识库。核心思想是三层：源材料输入层、LLM 维护的 wiki 层、CLAUDE.md 行为协议层。

我的方案和它有血缘关系，但走得更远：

Karpathy 的方案适合「个人笔记整理」场景。当知识库需要承载多品牌运营、多工作流编排、多 Agent 协同时，单层 CLAUDE.md 撑不住——你需要多级路由和治理机制。

CLAUDE.md 多级路由系统

整个方案的核心架构就是一句话：用链式 CLAUDE.md 文件构建一棵导航树，Agent 从根节点出发、按触发词逐级深入、最多 3 跳到达目标。

六层路由架构（L0-L5）

Agent 的寻路过程是这样的：

用户说「写一篇官网文章」
→ Agent 读 L1 根 CLAUDE.md
→ 命中触发词「官网文章发布」→ 指向 工作流/翔宇-创作-Ghost-文章/CLAUDE.md
→ Agent 读 L3 工作流 CLAUDE.md
→ 获得完整执行路径和子工作流列表
→ 开始执行

整个过程确定性 100%。不依赖语义相似度，不存在「召回了错误文档」的可能。

L1 根 CLAUDE.md 的结构设计

根 CLAUDE.md 是整个知识库的灵魂，它必须做到两件事：让 Agent 能快速定位目标、让人能快速理解全局。

一个生产级的根 CLAUDE.md 包含这些板块：

## 行为准则       ← Agent 的操作规则（工具优先、改前读规范、向前演进等）
## 工具体系       ← MCP 列表 + 本地工具路由表
## 知识库导航     ← 8 个顶层目录的触发词路由表
## 命令速查       ← 常用 CLI 命令
## 直读指引       ← 高频内容的绝对路径快速定位

触发词路由表是关键设计。它的格式是：

| 目录 | 职责 | 触发词 |
|------|------|--------|
| 品牌/ | 多品牌身份/受众/视觉资产/竞品 | 人设、表达风格、画像、爆款 |
| 工作流/ | 多步创作管线和发布流水线 | 出课、引流、三联发、建站 |
| 工具/ | CLI 脚本、MCP、凭据、最佳实践 | 工具、脚本、凭据 |

Agent 读到用户的请求后，在这张表里做关键词匹配。匹配成功就跳到对应目录的 L2 CLAUDE.md 继续深入。

🔍 深入一步：触发词不是随便写的。每个触发词必须满足两个条件——唯一性（不和其他目录的触发词冲突）和覆盖性（用户可能的所有自然表达都要覆盖）。我的实际操作是：每次 Agent 走错了路由，就回来补一个触发词。跑了半年，触发词表从最初的 20 个长到了现在的 200 多个。

直读指引：跳过路由的快车道

对于高频访问的内容，逐级路由反而慢了。所以根 CLAUDE.md 还有一块「直读指引」——直接给出绝对路径，Agent 一步到位：

### 品牌

| 触发词 | 路径 |
|--------|------|
| 定位 / 价值观 | 品牌/{brand}/身份/定位.md |
| 表达风格 / 语气 | 品牌/{brand}/身份/表达风格.md |
| 受众 / 画像 | 品牌/{brand}/受众/CLAUDE.md |

### 工作流

| 触发词 | 路径 |
|--------|------|
| 写官网文章 | 工作流/翔宇-创作-Ghost-文章/CLAUDE.md |
| 写公众号 | 工作流/翔宇-创作-微信公众号-引流文/CLAUDE.md |

这张表本质上是一个「缓存层」——把最热的路由直接平铺在 L1，省去中间跳转。

目录结构设计原则

知识库的目录结构不是随心情建的。它遵循三个原则：职责唯一、边界清晰、正本归位。

8 个顶层目录

每个目录有且只有一个职责。文件该放哪里，看这张归位规则表：

⚠️ 常见踩坑：新手最容易犯的错是「不知道放哪就新建一个目录」。三个月后你会有 20 个模糊目录，Agent 每次都要在其中纠结。正确做法是严守这张归位表——找不到位置说明你的顶层分类需要调整，而不是加目录。

目录内部的同构原则

同一层级的目录应该遵循相同的内部结构。以品牌目录为例：

品牌/
├── 翔宇工作流/
│   ├── 身份/          ← 定位、表达风格、介绍
│   ├── 受众/          ← 画像分析
│   ├── 视觉资产/      ← Logo、头像、封面
│   └── 竞品/          ← 对标分析
├── AWP/
│   ├── 身份/
│   ├── 受众/
│   ├── 视觉资产/
│   └── 竞品/

两个品牌目录结构完全一样。Agent 学会了一个品牌的路径模式，另一个品牌也能直接套用。这就是同构的价值——减少 Agent 的认知负担。

收件箱：运行态的唯一入口

收件箱是最容易失控的地方。我的规则很简单：

收件箱只处理运行态。什么是运行态？正在跑的任务（调度中台）、正在写的草稿（AI 草稿箱）、正在产出的中间数据（运行数据）、需要交接给下一个 Agent 的上下文（任务交接）、已经结束只需追溯的历史（存档）。

禁止新建中转桶。不许建 待处理/、临时/、待归位/ 这类目录——它们会变成垃圾堆。能判断归属的文件直接放到正确位置；不能判断的放收件箱对应区域，但必须在 30 天内清理。

收件箱的子区设计：

收件箱/
├── Farm CLI 调度中台/    ← 多 Agent 任务派发
├── 任务中台/   ← 自动化任务
├── AI 草稿箱/{YYYYMM}/  ← 一次性产物
├── 任务交接/{YYYYMM}/   ← 会话接力
├── 运行数据/{固定任务}/  ← JSON、log、采集数据
├── 规划/{YYYYMM}/       ← 在途调研
└── 存档/{YYYYMM}/       ← 软删除

从零搭建一个 AI 知识库

下面是完整的建库流程。你按这个顺序走一遍，半天时间能搭出一个可用的知识库骨架。

第一步：建顶层目录

mkdir -p ~/knowledge-base/{品牌,工作流,工具,业务,研究,规范,生活,收件箱}
mkdir -p ~/knowledge-base/工具/{app,凭据,最佳实践}
mkdir -p ~/knowledge-base/收件箱/{存档,运行数据}

目录名用中文。AI Agent 对中文目录名的理解没有任何问题，而中文目录名对人来说可读性远好于英文。

第二步：写根 CLAUDE.md

这是最重要的一步。根 CLAUDE.md 决定了 Agent 怎么理解你的知识库。

核心板块：

# 知识库

> 基础路径：~/knowledge-base/

## 行为准则

- 工具优先：先查本地 CLI，禁止跳过直调 MCP
- 改前读规范：修改前先定位对应规范
- 向前演进：直接覆盖正确做法，不向后兼容

## 知识库导航

| 目录 | 职责 | 触发词 |
|------|------|--------|
| 品牌/ | 品牌身份和资产 | 人设、风格、画像 |
| 工作流/ | 执行管线 | 出课、发布、建站 |
| 工具/ | CLI 和配置 | 工具、脚本、凭据 |
| 业务/ | 落地资产 | 产品、项目、内容 |
| 研究/ | 源材料 | 书籍、论文、报告 |
| 规范/ | 编写标准 | 规范、检查清单 |

## 直读指引

| 触发词 | 路径 |
|--------|------|
| ... | ... |

写根 CLAUDE.md 有几个铁律：

1. 行为准则放最前面——Agent 启动时先读行为规则，再读内容索引
2. 触发词表覆盖自然表达——用户可能说的话都要能匹配到
3. 直读指引只放高频内容——不是所有路径都要平铺，否则太长
4. 变更记录放最后——保留最近 10 条，方便追溯最近改了什么

第三步：写子目录 CLAUDE.md

每个一级目录写一个 CLAUDE.md，格式统一：

# {目录名}/

> 一句话定位。

## 子目录索引

| 子目录 | 定位 | 触发词 |
|--------|------|--------|
| ... | ... | ... |

## 使用边界

- 本目录做什么
- 本目录不做什么

## 变更记录

| 日期 | 变更内容 |
|------|---------|

关键点：每个 CLAUDE.md 只管自己这一层。不要在品牌目录的 CLAUDE.md 里写工具使用方法——那是工具目录的事。

第四步：建规范入口

规范目录是知识库的「宪法」——它不直接产出内容，但约束所有内容的质量。

规范/
├── CLAUDE.md              ← 规范总入口 + 覆盖矩阵
├── {某领域}编写规范/
│   ├── CLAUDE.md
│   ├── 具体规范1.md
│   └── 具体规范2.md

初始阶段不需要太多规范。建议从这三个开始：

1. Markdown 编写规范——统一格式，Agent 生成的内容不会乱
2. 文件编写规范——文件命名、变更记录格式
3. CLAUDE.md 编写规范——路由文件本身的标准

第五步：配置凭据

API Key 和 Token 不能硬编码在文件里。建一个凭据目录：

工具/凭据/
├── CLAUDE.md      ← 凭据索引 + 取号方式
├── 通用/          ← 可跨机同步的凭据
└── 敏感/          ← 本机保留

Agent 通过凭据解析器读取密钥，而不是直接从文件内容中提取。这样知识库可以安全地同步到其他设备。

第六步：配置本地 CLI 并跑审计

知识库不是搭完就不管了。你需要一个 CLI 做日常维护：

# 检索
KB search all "关键词"

# 结构审计——检查目录是否符合规范
KB audit structure

# 文档审计——检查 CLAUDE.md 索引是否与实际文件一致
KB audit docs

# 冗余审计——找出重复或过时的文件
KB audit redundant --limit 20

第一次跑审计很可能发现一堆问题——目录没有 CLAUDE.md、文件放错位置、变更记录过期。修完它们，知识库就进入可用状态了。

🔍 深入一步：CLI 做确定性动作——检索、审计、归档、凭据管理。判断逻辑不放进 CLI。比如「这个文件应该归档到哪里」是 Agent 的判断，CLI 只负责执行 archive 命令把文件移到指定位置。这条边界很重要：CLI 是工具不是大脑。

知识库运维

搭完骨架只是开始。知识库是活的——每天有新文件产生、旧文件过期、路由需要更新。运维是持续动作。

日常维护循环

每次修改文件后的标准流程：

1. 先读根 CLAUDE.md 和目标目录最近的 CLAUDE.md
2. 按规范定位对应编写标准
3. 修改正文或工具
4. 同步上下游 CLAUDE.md——新增/删除文件后必须更新索引
5. 跑对应 CLI 自验
6. 用 rg 回扫旧口径——确保没有过期引用

第 4 步是最容易遗漏的。你新建了一个工作流但忘了在根 CLAUDE.md 的触发词表里加一条——结果 Agent 永远找不到它。

审计机制

三种审计覆盖三类问题：

审计发现的问题按优先级处理：结构问题（缺 CLAUDE.md）当天修、文档问题（索引不一致）三天内修、冗余问题（过时内容）攒一批统一归档。

归档分层

文件不是越多越好。活跃知识库里只保留「当前还在用」的东西：

归档不是删除。归档后在原位置留一个指针文件（CLAUDE.md 写明「已归档到 XX 位置」），Agent 需要时可以追溯。

⚠️ 常见踩坑：把大体量书籍（PDF、epub）直接扔在知识库活跃路径里。一本 50MB 的 PDF 对 Agent 没有任何用处——它读不了 PDF。正确做法是：书籍转成 Markdown 后放 研究/ 对应话题，原始文件归档到 NAS。

变更记录

每个 CLAUDE.md 末尾都有一个变更记录：

## 变更记录

> 滚动窗口，保留最近 10 条，每条 ≤20 字。

| 日期 | 变更内容 |
|------|---------|
| 2026-06-06 | 加研究库最佳实践 |
| 2026-06-05 | 加视频理解CLI |

这不是 git log 的替代品。它的作用是让 Agent（和人）快速了解这个区域最近发生了什么——不用翻 git history，扫一眼就知道。

规模化：从 10 文件到 1000+ 文件

知识库的治理方式随规模变化。10 个文件和 1000 个文件面对的问题完全不同。

10-50 文件：种子期

这个阶段不需要复杂治理。做好三件事：

1. 根 CLAUDE.md 写清楚
2. 每个目录有 CLAUDE.md
3. 文件命名一致

50-200 文件：成长期

开始出现「找不到文件」的问题。解法：

• 给高频内容加直读指引
• 建 CLI 做检索（search all "关键词"）
• 开始写规范约束新增文件的格式

200-500 文件：治理期

需要引入正式的运维机制：

• 定期审计（结构 + 文档 + 冗余）
• 归档规则落地——不用的东西必须归档
• 触发词表膨胀——需要做去重和合并
• 变更记录强制——没有记录的改动等于没发生

500-1000+ 文件：稳态期

到了这个规模，单纯靠人维护 CLAUDE.md 已经不现实。需要：

• CLI 辅助同步——文件变动后自动检查关联索引是否更新
• 多级路由严格分层——L3 以下的路由不再出现在 L1
• 活跃文件数量控制——通过归档把活跃文件控制在 800 以内
• 分区授权——不同工作流只读自己需要的区域，不读全库

🔍 深入一步：1000 文件听起来很多，但实际上知识库的「热区」只有 200-300 个文件——Agent 日常访问的主要是工作流、工具配置和当前项目的业务文件。另外 700 个文件是研究素材、归档历史、低频规范，Agent 很少主动触达。控制热区文件的质量，比管好全部 1000 个文件更重要。

和 RAG / 向量数据库方案的深度对比

为了让对比公平，我把两种方案放在同一个评估框架里：

结论：如果你的知识库满足以下条件，文件系统方案是更优选择：

• 文件数量 1000 以内
• 内容结构化程度高（有明确分类）
• 需要高精度路由（Agent 执行型场景）
• 需要版本控制和审计追踪
• 多人/多设备同步（Syncthing / git）

如果你的场景是：海量非结构化文档、语义模糊查询为主、不需要精确到文件级别的定位——RAG 是正确答案。

混合方案

实际上两者不冲突。我的知识库在「结构化导航」层用文件系统 + CLAUDE.md 路由，在「全文检索」层用本地 CLI 的关键词搜索（rg / BM25）。如果未来规模突破 2000 文件，可以在 CLI 层加一个轻量向量索引作为补充——但路由主干仍然是 CLAUDE.md。

这个混合策略的关键是：路由和检索分离。路由靠确定性的 CLAUDE.md 层级结构，检索靠关键词或向量作为兜底。两者互不依赖，哪个坏了另一个还能工作。

设计哲学

回到最底层的设计选择。

文件即正本——不存在「数据库里有一份、文件系统里有一份」的双写问题。Agent 读什么、人读什么、同步什么、备份什么，都是同一个文件。

路由即文档——CLAUDE.md 既是 Agent 的导航系统，也是人的文档。你打开任何一个 CLAUDE.md，不需要启动 Agent 就能理解这个目录下有什么、怎么用。

确定性胜过智能——CLI 做审计不用 AI 判断。归档命令不猜你想归到哪——你必须明确指定。路由靠关键词匹配不靠语义推断。在执行层面，确定性比智能更可靠。

人管结构，Agent 管内容——目录怎么建、CLAUDE.md 怎么写、触发词怎么定——这是人的决策。但在这个结构内部填充什么内容、生成什么产物、按什么工作流执行——这是 Agent 的工作。

归档是第一等公民——信息的默认归宿是「归档」而不是「永久保留」。只有正在用的东西才留在活跃区。这条原则让知识库不会无限膨胀。

实操清单

如果你现在就想开始，按这个清单做：

第一天：

• [ ] 建 8 个顶层目录
• [ ] 写根 CLAUDE.md（行为准则 + 触发词路由表）
• [ ] 写每个一级目录的 CLAUDE.md

第一周：

• [ ] 把散落各处的文件归位到正确目录
• [ ] 写 2-3 条核心规范（Markdown、文件命名、CLAUDE.md 格式）
• [ ] 配置凭据目录
• [ ] 用 Claude Code 对话测试——它能不能找到你放的文件

第一个月：

• [ ] 搭建本地 CLI（至少做检索和归档两个命令）
• [ ] 建立周审计习惯
• [ ] 补全直读指引（把高频路径平铺到根 CLAUDE.md）
• [ ] 写第一条工作流并验证 Agent 能跑通

持续：

• [ ] 每次新增文件后同步 CLAUDE.md
• [ ] 每月清理一次归档
• [ ] 每季度回顾触发词表——去重、合并、补漏

我用这套方案跑了快一年。从最初 50 个文件的草台班子，到现在 1000+ 文件的生产级知识库，中间经历了三次大重构、无数次路由优化、反复推翻又重建的目录设计。

我的判断是：对于个人或小团队的 AI 编程工作场景，纯文件系统 + CLAUDE.md 路由是当前最实用的知识库方案。它不是最酷的方案——没有向量数据库那种「语义检索」的科技感。但它是最可控的方案——你能看清每一步路由逻辑，能用 cat 读每一个文件，能用 rg 搜全库。

当工具足够简单时，复杂性才不会反噬你。

延伸阅读

• CLAUDE.md 编写最佳实践——如何写好一个 CLAUDE.md 文件
• Agent 知识库与 AI 写作——知识库如何驱动 AI 写作工作流
• 知识库上云教程——多设备同步和云端备份方案

深入实操：对应课程模块

这篇讲的知识库架构设计，在我的 AI 编程实操课中有对应的完整实战模块——从建目录到写路由到搭 CLI 到跑审计，每一步都有录屏演示和源码。

• 📚 国内版（FlowUS）：https://flowus.cn/xiangyugongzuoliu/share/d392dcad-b537-44ee-a3e2-56ff5af02bce
• 🌏 国际版（Buy Me a Coffee）：https://buymeacoffee.com/xiangyu

常见问题

知识库必须用 Claude Code 吗？

不必须。CLAUDE.md 路由的核心机制是「结构化 Markdown 导航」，任何能读文件的 AI Agent 都能用——Codex 用 AGENTS.md 是同一思路。只是 Claude Code 对 CLAUDE.md 的原生支持最好。

文件太多 Agent 会不会读不完？

不会。Agent 不是把整个知识库装进上下文窗口——它按路由层级逐步深入，每次只读当前需要的 1-3 个文件。1000 个文件的知识库，Agent 处理一次请求平均读 4-6 个文件。

和 Obsidian / Notion 能共存吗？

可以。知识库的底层是文件系统，Obsidian 可以直接打开同一个目录。Notion 不行（Notion 的数据不在本地文件系统）。但要注意：Obsidian 的双向链接和 CLAUDE.md 路由是两套独立的导航系统，不要试图把它们混在一起。

多人协作怎么办？

用 git。知识库的每个文件都是 Markdown 文本，天然适合 git 版本控制。多人各改各的区域，冲突时 merge 就行。如果不用 git，Syncthing 的实时同步 + 版本保留也能覆盖个人多设备场景。

下一步

AI 编程实操课：Claude Code + Codex + Agent 工作流，覆盖一人公司、自媒体自动化、AI 副业全场景。实战教程 + 最佳实践 + 源码包，跟着做就出成果。国内版-FlowUS | 国际版-BMC

国内版和国际版内容完全相同，根据你的支付渠道自行选择即可。