在大语言模型应用开发中，向量检索加 RAG（Retrieval-Augmented Generation）已成为事实标准方案。然而，随着知识库规模扩大，向量索引的维护成本、检索精度衰减、幻觉问题等问题逐渐显现。Andrej Karpathy 提出的 idea file 方案提供了一条截然不同的工程路径：放弃对向量索引的强依赖，转而使用结构化的 Markdown wiki 作为知识载体，让 LLM 本身负责知识的组织、维护和检索。这一方案在中等规模知识库（数百至数千条概念条目）场景下具有显著的工程简洁性优势。
Idea File 的核心设计理念
Idea file 本质上是一份由人类 curator 提供、由 LLM 维护的结构化蓝图。与传统 RAG 将知识全部转化为向量嵌入不同，idea file 保留了知识的原始可读性和结构化属性。具体而言，idea file 定义了一套模式（schema），告诉 LLM 如何摄取（ingest）、链接（link）和呈现（present）信息。人类负责提供原始数据源和问题，LLM 则承担知识的摄入、组织和日常维护工作。
这种设计的核心优势在于降低了对外部向量数据库的依赖。传统 RAG 需要经历文本分块、向量化、索引构建、相似度检索等多个环节，每个环节都有参数调优的空间，但也引入了不确定性。Idea file 将知识组织为人类可读、机器可解析的 Markdown 文件，配合明确的元数据字段，使得检索过程可以被解释和审计。当知识库规模适中时，这种基于链接的检索方式已经足够高效，且省去了向量计算的额外开销。
从工程实践角度看，idea file 适合以下场景：知识总量在几百到几千个概念条目之间；知识具有较强的结构化和层级关系；团队需要频繁查阅和编辑知识库内容；需要明确的血缘追溯和版本控制。如果你的场景是超大规模文档检索或语义相似度匹配要求极高的场景，传统 RAG 仍然更为适用。
目录结构与文件组织规范
一个完整的 idea file 知识库通常采用分层的目录结构。最顶层包含两个核心目录：raw 目录存放未经处理的原始数据源，wiki 目录存放经 LLM 加工后的结构化概念页面。在 wiki 内部，每个概念对应一个独立的 Markdown 文件，文件名采用 kebab-case 格式以确保跨平台兼容性。
典型的目录结构如下：根目录下有 raw/、wiki/、index.md 和 CLAUDE.md（或 AGENTS.md）四个核心组件。raw 目录存放各类原始文档，按照来源或主题进一步划分子目录。wiki 目录存放概念页面，每个概念一个 .md 文件，文件头部包含 YAML 格式的元数据。index.md 是知识库的入口文件，列出所有概念页面的链接和最近更新内容。CLAUDE.md 是模式定义文件，描述知识库的编辑规范、工作流程和格式约定。
以一个具体概念为例，其 Markdown 文件应包含以下部分：文件头部使用三横线包裹的 YAML 元数据，包含 id、title、type、tags、sources、created_at、updated_at、owner 等字段；正文部分依次为概念定义、背景上下文、相关资产链接、提示词变体、评估记录和关系链接。这种结构确保了每个概念的知识原子性，便于独立检索和版本追踪。
Schema 定义与元数据规范
CLAUDE.md 或 AGENTS.md 作为整个知识库的 “宪法” 文件，定义了 LLM 维护知识库时需要遵守的所有规范。一个完整的 schema 定义应包含以下几个方面：摄入规则定义了从 raw 到 wiki 的转换逻辑，包括如何提取关键信息、如何生成摘要、如何建立概念间的关联；格式化约定明确了 Markdown 标题层级、列表样式、代码块语言标签等写作规范；工作流程描述了知识库的日常维护节奏，包括何时更新索引、何时检查链接有效性、何时生成反向链接；所有权与审批规则定义了哪些人可以编辑哪些概念，以及变更需要经过何种审批流程。
元数据字段的设计需要平衡信息完整性和维护成本。建议核心字段包括：id（唯一标识符，采用 kebab-case）、title（显示名称）、type（概念类型，如 concept、prompt、experiment、asset）、tags（标签数组，用于分类检索）、sources（原始来源列表，带 URL 链接）、created_at 和 updated_at（时间戳）、owner（负责人）。可选字段包括：status（概念状态，如 draft、review、published、deprecated）、related（关联概念列表）、evaluation（评估指标和结果）。
这些元数据字段的价值在于支持结构化查询和自动化维护。例如，通过解析 tags 字段可以生成按主题分类的索引；通过比较 updated_at 与当前时间可以识别长期未更新的概念；通过 evaluation 字段可以追溯每个概念的实验历史。
摄入工作流与自动化实践
摄入（inggestion）是将原始数据转换为结构化知识的过程，也是 idea file 方案中最需要自动化的环节。一个完整的摄入工作流通常包括以下步骤：首先将新的原始文档放入 raw 目录的相应子目录；然后由 LLM 读取文档内容，识别关键概念和知识点；接着为每个新概念创建或更新 wiki 目录下的 Markdown 文件，包括元数据填充和正文撰写；随后更新 index.md，添加新概念的链接并更新最近变更列表；最后扫描所有概念页面，识别并添加反向链接（backlinks），更新关系图谱。
在实际工程实现中，可以利用文件系统监控工具（如 inotifywait 或 fswatch）监听 raw 目录的变化，触发自动摄入脚本。摄入脚本可以调用 LLM API 完成概念提取和页面生成，整个过程对用户透明。一种常见的做法是将 CLAUDE.md 作为系统提示词（system prompt）的一部分，让 LLM 在每次交互时都遵循知识库的编辑规范。
工作流的触发策略有两种常见选择：事件驱动模式，即在检测到 raw 目录变化时立即触发摄入；定时批处理模式，即每天固定时间批量处理新增的原始文档。事件驱动模式适合知识更新频繁的场景，定时批处理模式则更适合团队协作场景，可以将多个变更合并处理以减少 LLM 调用次数。
检索策略与查询优化
虽然 idea file 方案降低了向量索引的依赖，但仍然需要高效的检索机制。基础检索策略是直接遍历 wiki 目录，匹配文件名和元数据中的关键词。更进一步，可以通过解析 Markdown 文件内容实现全文搜索，这可以使用简单的 grep 工具或专门的 Markdown 搜索工具如 ripgrep。
对于需要语义匹配的查询，可以保留轻量级的向量索引，但仅针对 wiki 中的概念定义部分（而非完整文档）建立索引。这样做的好处是减少了向量化的文档数量，降低了索引维护成本，同时保留了语义检索的能力。一种折中方案是仅对概念页面的 title、tags 和摘要（通常为文件第一段）进行向量化，而非对整个知识库进行 indexing。
链接导航是 idea file 方案独有的检索优势。通过维护完整的双向链接图谱，用户可以从一个概念出发，沿着关系链浏览相关知识。这种基于图结构的导航方式在某些场景下比关键词检索更高效，特别是当用户需要了解某个主题的完整上下文时。建议使用 Obsidian 或类似的 Markdown 笔记工具作为前端，它们原生支持双向链接和图谱可视化。
维护监控与健康检查
任何知识管理系统都需要持续的维护和监控，idea file 方案也不例外。建议设置以下几类健康检查任务：
断链检测是最基本的维护任务。每周扫描所有概念页面中的内部链接，识别指向不存在文件的链接并自动修复或标记。断链通常发生在概念被重命名或删除后，如果不及时处理，会影响知识库的可导航性。
元数据完整性检查定期扫描所有概念页面的元数据字段，确保 required 字段不为空，date 字段格式正确，tags 和 sources 为有效数组。这一检查可以发现因 LLM 幻觉导致的缺失字段或错误格式。
更新频率监控通过分析 updated_at 字段，识别长期未更新的概念。如果某个概念超过 30 天未更新，可能意味着该领域知识已经过时或需要补充新的研究成果。建议将此类概念列入定期审查清单。
索引一致性检查验证 index.md 中的链接列表与 wiki 目录中的实际文件是否一致，确保目录结构的变更及时反映在索引文件中。这一检查可以防止因手动操作失误导致的索引失效。
与传统 RAG 的选型对比
在工程实践中选择 idea file 还是传统 RAG，需要根据具体场景权衡。以下是关键的决策因素：
知识规模是首要考量。当知识条目在几百到几千的量级时，idea file 的基于链接的检索效率已经足够，且省去了向量索引的维护开销。当知识规模超过数万条时，传统的向量检索在召回率上仍具有优势。
结构化程度决定了方案的有效性。如果知识本身具有清晰的层级和关联关系，idea file 能够很好地捕捉这种结构。如果知识是扁平的文档集合，缺乏内在关联，RAG 的语义检索能力更为适合。
团队协作需求影响方案可行性。Idea file 本质上是 Git 友好的文本文件，天然支持版本控制和多成员协作。如果团队已经习惯使用 Git 工作流，idea file 的学习和迁移成本很低。
可解释性要求在某些场景下是硬性约束。Idea file 的每条知识都可以追溯到原始来源和编辑历史，检索结果完全可解释。如果应用场景对可审计性有严格要求，idea file 是更自然的选择。
快速启动建议
对于初次尝试 idea file 方案的团队，建议按照以下步骤快速启动：首先创建一个根目录（如 km/ 或 wiki/），在其中初始化 index.md 和 CLAUDE.md 两个文件，CLAUDE.md 中先写入基础的 schema 定义，包括目录结构说明、元数据字段定义和基本的编辑规范。然后在 raw 目录下放入三到五个代表性的原始文档，运行一次手动摄入流程，观察 LLM 生成的概念页面质量，据此调整 schema 定义。最后将摄入流程自动化，可以使用简单的 Shell 脚本配合 LLM API 调用实现事件驱动的自动摄入。
在工具选择上，Obsidian 是最推荐的 Markdown wiki 前端，它原生支持双向链接、图谱可视化和丰富的插件生态。如果团队偏好更轻量的方案，VS Code 配合 Markdown All in One 插件同样可以满足编辑需求。对于自动摄入脚本，可以使用 Python 或 Node.js 编写，配合文件系统监控工具实现自动化。
资料来源：本文参考了 Andrej Karpathy 提出的 LLM wiki 与 idea file 方案，详见 Karpathy's LLM Wiki: The Complete Guide to His Idea File。