AI代理知识库维护协议：7条军规与8阶段编译法实现代码库维基自动化-深圳市維司達科技有限公司

1. 项目概述：一个为AI代理设计的“维基维护宪法”

如果你正在用Claude Code、Cursor这类AI编程助手，或者任何能访问文件系统的AI代理来开发项目，你肯定遇到过这个痛点：每次开启一个新的对话会话，AI都得从头到尾把你的代码和文档再读一遍，才能理解项目上下文。这不仅烧钱（每次都是几千个token的上下文开销），更关键的是，知识无法沉淀。今天AI帮你理清的一个复杂模块关系，明天它又忘了，你得重新解释一遍。

这就是“Karpathy维基”模式要解决的问题。它本质上是一个由AI代理维护的、位于项目根目录下的wiki/文件夹。里面不是普通的文档，而是一个编译后的知识层。AI在开始工作前，先读这个维基，而不是去扫描海量的原始代码和文档，从而获得一个结构化、高保真、低token消耗的项目心智模型。

听起来很美好，对吧？但几乎所有尝试过这个模式的人，最终都失败了。失败的原因出奇地一致：维基无法持续维护，迅速腐烂。AI今天创建了页面，明天代码改了，它却忘了更新对应的维基条目。几周后，维基里的信息和实际代码就完全对不上了，变得毫无价值。

我手上这个karpathy-wiki-protocol项目，就是为了彻底解决这个“维护”难题而生的。它不是又一个展示5篇文章就完事的周末实验项目。它的每一条规则，都源自一个真实的生产级代码库——一个拥有22个功能域、139个维基页面、594个内部链接和425个经过审计的知识缺口的大型项目。简单说，这是一套从血泪教训中提炼出来的、让AI代理能像人类工程师一样可靠地维护知识库的“操作宪法”。

2. 核心设计理念：从“文档”到“可执行协议”

大多数AI维基方案，其核心是一堆描述性的“指南”。它们告诉AI“最好保持维基更新”，但缺乏明确的执行边界和验证机制。karpathy-wiki-protocol的设计哲学完全不同：它是一份给AI的、无歧义的、可验证的操作协议。

2.1 协议 vs. 指南：关键区别

你可以把传统的AI指南想象成一本哲学书，充满了“建议”和“最佳实践”。而这份协议，更像是一份飞行检查单或法律条文。

指南会说：“在修改代码后，记得更新相关的维基页面。”
协议规定：“规则1：任何代码变更，无论多小，都必须触发一次维基编译任务。任务定义为：识别所有受影响的维基页面，并确保其内容与变更后的代码状态一致。PASS条件：变更提交前，wiki/log.md中有一条记录，关联了本次代码提交哈希与完成的维基页面更新列表。FAIL条件：代码已提交，但wiki/log.md中无对应记录。”

看出区别了吗？协议是二元的、可审计的。AI要么遵守了（PASS），要么没遵守（FAIL），没有模糊的中间地带。人类维护者只需检查wiki/log.md这个“黑匣子”记录，就能知道AI是否尽职。

2.2 三层架构：清晰的权责分离

整个系统的架构非常清晰，分为三层，每层的读写权限和演化方式都不同：

原始资料层 (Raw Sources) -> 维基层 (Wiki Layer) -> 协议层 (Schema Layer) 只读 读写 共同演化

原始资料层：你的源代码（src/）、设计文档（docs/）、API蓝图、产品需求文档等。这一层对AI代理是只读的。AI不能直接修改这些“源文件”，它们是事实的最终来源。
维基层：即wiki/目录。这是AI代理的读写工作区。AI通过“编译”过程，将原始资料层的复杂信息，提炼、重组、链接后，存入这个维基。它是原始资料的一个经过优化的、面向AI的缓存视图。
协议层：包括CLAUDE.md（或AGENTS.md）中嵌入的规则，以及wiki/schema.md中定义的页面模板。这一层由人类和AI共同演化。当AI在维护维基时发现现有协议无法处理的新情况，它会提出修改建议，由人类审核后更新协议。

这个架构的精妙之处在于，它建立了一个正向循环：协议指导AI维护维基；维基的高质量使得AI工作效率提升；AI在工作中发现的新模式，又反过来完善协议。

3. 协议核心规则详解：7条军规与验证门禁

协议的核心是7条强制性的二进制规则。每一条都是为了堵住一个在实际生产中发生过的AI行为漏洞。

3.1 七条核心军规

编译触发规则：任何代码或文档的变更，都必须触发维基编译。没有“小到不需要更新”的变更。
- 实操要点：在你的CI/CD流程或Git钩子中，可以设置一个检查点，确保每次提交都伴随着wiki/log.md的更新。AI代理需要在执行编码任务前，就将“更新维基”作为子任务列入计划。
源文件只读规则：AI代理绝对不允许直接修改docs/等原始资料层下的任何文件。所有知识提炼和重组工作必须在wiki/目录下完成。
- 为什么：防止AI“污染”原始需求或设计文档，保持源头的纯洁性。维基是衍生品，可以随时从源头重新编译。
无占位符规则：禁止创建内容为“待补充”或“TODO”的维基页面。要么创建包含实质信息的完整页面，要么不创建。
- 踩坑实录：我们曾经允许占位符，结果维基里很快堆满了永远不会被填充的“僵尸页面”，严重损害了维基的可信度。这条规则强迫AI在编译时就必须深入理解，如果理解不了，就标记为“知识缺口”。
引用溯源规则：维基页面中的每一个重要陈述，都必须通过内联链接（wikilink）引用到wiki/内的其他页面，或者通过明确的注释（如）追溯到原始资料层的具体位置。
- 作用：这建立了信息的可追溯性。当源文件变更时，AI能快速定位哪些维基陈述可能失效。
矛盾处理规则：当AI在编译中发现原始资料间存在矛盾（例如，代码注释说A，而设计文档说B），它不得自行选择一方。
- 标准操作程序：
  1. 在相关维基页面中，创建一个“待决争议”章节。
  2. 客观陈述矛盾双方的观点和出处。
  3. 将页面状态标记为status: PENDING_REVIEW。
  4. 在wiki/log.md中记录此矛盾，并明确需要人工介入。
- 价值：将AI从它不擅长的“决策”中解放出来，转而发挥其“信息整理与呈现”的优势，把最终判断权留给人类。
索引与日志更新规则：任何维基页面的增、删、改，都必须同步更新wiki/index.md（总目录）和wiki/log.md（操作日志）。
- index.md是一个自动生成的目录页，包含所有页面的链接和简短描述，方便AI和人类快速浏览。
- log.md是一个仅追加的审计日志，记录每次编译操作的时间、触发原因、涉及的页面和哈希值。这是验证AI工作的主要依据。
模式演进规则：如果AI在维护中发现现有wiki/schema.md中的模板不足以清晰表达某一类信息，它应当提出模板修改或新增建议，并提交给人类审核。
- 例子：最初我们的entity模板只有“字段”列表。后来AI发现很多实体有复杂的生命周期状态转换，于是它建议增加一个“状态机”章节。我们审核后采纳，更新了schema.md。

3.2 验证门禁：8点检查清单

规则制定了，如何确保AI每次都能遵守？靠的是在每个任务结束时自动执行的“验证门禁”。

这个门禁是一个8点的检查清单，AI必须在任务完成后、输出最终答案前，自行运行并全部通过：

触发记录：本次任务是否触发了维基编译？如果是，log.md中是否有对应记录？
索引同步：index.md是否已更新，反映了所有页面的变化？
无占位符：是否没有创建任何新的空页面或占位符页面？
引用完整：所有新增或修改的内容，是否都有明确的内部链接或源引用？
矛盾标记：如果遇到矛盾，是否已标记为PENDING并记录在日志？
格式合规：所有页面是否遵循schema.md中定义的模板和Frontmatter格式？
链接有效：所有内部wikilinks是否都指向了存在的页面？（检查死链）
日志自洽：log.md中的记录是否清晰、完整，且与本次任务的实际改动相符？

我的实操心得：这个验证门禁是整套协议的灵魂。最初我们只是把规则写给AI，结果它还是会在忙乱中忘记一两条。加入了强制性的、任务结束前的自检门禁后，合规率达到了接近100%。你可以把这个检查清单直接以代码块的形式放在你的CLAUDE.md里，并要求AI：“在每个回答的最后，输出‘验证门禁结果：’并逐条核对这8点。”

4. 分阶段编译策略：如何从零搭建你的AI维基

一个常见的错误是，给AI一个指令：“请为我的项目创建完整的Karpathy维基。” AI会试图在一个会话内完成所有工作，结果往往是上下文耗尽，生成的内容虎头蛇尾，或者开始胡编乱造。

karpathy-wiki-protocol明确规定了8阶段编译法，每个阶段都有明确的输入、输出和停止边界，强制在多个人工智能会话中完成。

4.1 八个编译阶段详解

阶段	名称	核心任务	产出物	停止边界
1	脚手架	创建`wiki/`目录结构，初始化`index.md`,`log.md`,`schema.md`。	空的维基骨架。	目录和基础元文件创建完毕。
2	领域识别	扫描代码库，识别主要的功能领域（如`user_management`,`payment`,`notification`），在`wiki/domains/`下为每个领域创建页面框架。	一组领域页面，包含初步描述和已知的实体、端点列表。	所有顶层功能模块都已对应一个领域页面。
3	实体提取	深入数据库模型、ORM定义、API响应体，提取核心业务实体（如`User`,`Order`,`Product`），在`wiki/entities/`下创建详细页面。	实体页面，包含字段定义、关系、核心方法。	所有重要的数据模型都已覆盖。
4	端点映射	梳理API路由、控制器，将端点按照所属领域归类到`wiki/endpoints/`。描述其输入、输出、错误码。	结构化的API端点文档。	所有公开和内部API端点都已记录。
5	交叉关切	处理横跨多个领域的通用逻辑，如认证(`auth.md`)、错误处理(`errors.md`)、国际化(`i18n.md`)，放入`wiki/cross-cuts/`。	跨领域关切页面。	常见的共享模块和中间件已文档化。
6	决策记录	将代码中隐含的或文档中记载的重要架构决策，整理成架构决策记录，存入`wiki/decisions/`。	一系列ADR文件，解释“为什么这么做”。	主要的技术选型和架构权衡已记录。
7	链接编织	在所有页面间建立双向链接。确保实体页面链接到使用它的领域和端点，端点页面链接到相关的实体和领域。	一个高度互联的维基网络。	`index.md`中的链接完整性检查通过。
8	缺口审计	系统性地检查维基，识别缺失的信息、模糊的表述、未解决的矛盾，在`wiki/gaps/`下创建问题跟踪页面。	一个待办清单，指导后续的维基完善工作。	生成初始的缺口报告，并链接到相关页面。

4.2 如何执行分阶段编译

你不需要一次性给AI所有指令。正确做法是：

会话1：将协议文件放入项目，给AI指令：“请阅读WIKI_PROTOCOL.md第10节（多会话编译）。现在，执行阶段1：脚手架。完成后，请输出‘阶段1完成’并停止。”
会话2：启动新会话。AI会先读取已创建的维基骨架。你给指令：“继续执行阶段2：领域识别。基于src/目录结构进行分析。完成后停止。”
会话3及以后：依此类推，每个阶段都使用新的会话。这样做的好处是，每个阶段AI都有充足的上下文（主要是上一阶段的产出和当前阶段的有限目标），不会因为信息过载而崩溃。

一个重要技巧：在wiki/log.md中，让AI记录每个阶段的开始和结束。这样你就能清晰地看到编译进度，也方便在中断后继续。

5. 无缝集成到你的AI工作流

这套协议不是要推翻你现有的工具链，而是无缝嵌入进去。

5.1 集成到 Claude Code / Cursor

对于Claude Code或Cursor，最佳实践是将协议的压缩版本（约250个token）直接嵌入到你的项目根目录下的CLAUDE.md或.claude/目录的指令文件中。

步骤：

从项目的WIKI_PROTOCOL.md文件中，找到第12节“压缩版本”。
将那一整段代码块复制。
粘贴到你项目的CLAUDE.md文件末尾，可以放在一个名为“## Wiki维护协议”的章节里。
现在，每次你在这个项目中打开新的Claude Code会话，AI都会自动加载这些规则。

5.2 集成到其他AI代理或脚本

如果你使用其他AI代理框架（如LangChain、AutoGPT自定义代理等），你可以：

将WIKI_PROTOCOL.md作为系统提示词的一部分，在代理初始化时加载。
或者，更精细地控制：让代理在启动后，首先读取wiki/schema.md和wiki/log.md来获取上下文，然后根据当前任务，动态加载协议中的相关章节（如“验证门禁”章节）。

5.3 与版本控制（Git）的协作

维基目录wiki/应该被纳入版本控制（如Git）。这带来了几个好处：

历史追溯：你可以看到维基是如何随着代码演进的。
协作：团队成员可以查看AI对维基的修改。
回滚：如果AI某次编译出错，你可以轻松回退到上一个正确的版本。

在.gitignore中要注意：通常你不需要忽略wiki/里的任何东西。但wiki/log.md文件可能会频繁变更，如果你觉得它产生的噪音太大，可以考虑忽略，但这会牺牲一部分可审计性。我的建议是保留它，因为它的变更历史本身就是有价值的元信息。

6. 避坑指南与常见问题排查

在实际推行这套协议的过程中，我们踩过不少坑。以下是其中最典型的几个问题及其解决方案。

6.1 问题：AI“忘记”执行验证门禁

现象：代码修改了，维基却没更新，检查log.md也没有记录。
根因：AI在复杂任务中专注于主要目标（如修复bug），将“更新维基”视为次要任务，最终遗漏。
解决方案：
1. 强化提示词：在给AI的任务描述开头就强调：“本任务分为两部分：1. 主要编码任务；2. 根据协议更新维基。你必须在最终答复中包含两部分的结果。”
2. 使用“清单”格式：要求AI在思考过程中，显式地列出“待办事项”，其中必须包含“更新维基”。
3. 后置检查：在团队工作流中，引入一个简单的检查步骤。例如，代码审查时，顺便检查本次提交关联的log.md记录。

6.2 问题：维基页面内容过于冗长或琐碎

现象：AI把源代码的每一行注释都搬到了维基里，导致页面臃肿，失去了“编译提炼”的意义。
根因：协议中“引用溯源”的规则被过度执行，AI误以为需要复制所有细节。
解决方案：
1. 在schema.md中明确“抽象层级”：在模板里说明，维基页面应该提供的是概念模型和关键关系，而非实现细节。细节应该通过引用链接到源文件。
2. 举例说明：在协议中增加正面和反面例子。例如，实体页面应该列出字段的业务含义和约束，而不是把数据库迁移文件的SQL列定义照搬过来。
3. 人工审核与反馈：在初期，定期浏览AI生成的页面。如果发现过于冗长，直接指出并告诉AI：“这个页面太细了，请提炼到概念层面。” AI会从反馈中学习。

6.3 问题：内部链接（Wikilinks）断裂

现象：wiki/index.md中显示有链接，但点击（或AI尝试引用）时发现目标页面不存在。
根因：页面被重命名或删除后，没有同步更新所有引用它的地方。
解决方案：
1. 让AI运行链接检查脚本：可以在验证门禁中增加一条：“运行一个简单的脚本，检查wiki/目录下所有.md文件中的[[PageName]]链接，确认wiki/PageName.md文件存在。” AI可以自己生成并运行这个Python或Bash脚本。
2. 使用唯一标识符：考虑使用更稳定的标识符，如实体ID，而不是易变的文件名作为链接。但这会增加复杂度。对于大多数项目，定期（如每周）让AI执行一次全量链接审计就足够了。

6.4 问题：多AI代理协作冲突

现象：如果团队中多个成员同时使用AI代理在同一个项目上工作，可能会发生对同一个维基页面的并发修改冲突。
根因：维基文件是纯文本，Git在合并时可能会产生冲突。
解决方案：
1. 领域分区：在项目初期就划分清晰，不同的AI代理（或同一代理的不同会话）负责不同的功能领域。这自然减少了编辑冲突。
2. 基于Git的工作流：教导AI遵循一个简单的Git分支策略。例如，每个功能分支上的维基更新，只在合并回主分支时才整合。AI需要能处理简单的Git合并冲突（或至少识别并报告冲突）。
3. 最终，人类仲裁：将AI代理视为高级助手。当发生编辑冲突时，由人类来执行最终的合并和决策。协议的作用是确保冲突被清晰地标记出来（在log.md中），而不是被静默覆盖。

7. 进阶技巧：从维护到演进

当你的AI维基稳定运行一段时间后，你可以利用这个高质量的知识层，做一些更酷的事情。

7.1 将维基作为AI代理的“长期记忆”

许多AI代理框架有“记忆”功能，但通常是向量数据库，存储的是对话片段，缺乏结构。你的wiki/目录本身就是一个完美的、结构化的长期记忆体。

新会话初始化：新AI代理启动时，不再扫描整个代码库，而是先读取wiki/index.md和几个核心领域页面，在几十个token内就能建立项目全景图。
上下文切换：当AI在处理一个具体任务（如修改支付模块）时，它可以快速加载wiki/domains/payment.md和相关的实体页面，获得精准的上下文，无需在浩如烟海的源代码中搜索。

7.2 生成项目分析报告

由于维基是结构化的，你可以很容易地让AI基于维基内容生成各种报告。

架构健康度报告：分析wiki/gaps/目录，生成待解决的知识缺口清单和优先级。
新成员入职指南：让AI综合wiki/domains/下的核心领域页面，生成一份针对新员工的、高度定制化的项目介绍。
技术债评估：结合wiki/decisions/中的ADR和当前代码状态，AI可以分析哪些过去的决策与当前实践产生了偏离，这可能意味着潜在的技术债。

7.3 驱动代码生成与重构

这是最激动人心的部分。一个实时更新的、精确的维基，可以让AI进行更安全和更大胆的代码操作。

安全的重构：当AI需要重构User实体时，它可以先查看wiki/entities/user.md，了解所有依赖它的端点（wiki/endpoints/中的链接）和领域（wiki/domains/中的引用），从而评估改动的影响范围。
精准的代码生成：当你要求AI“添加一个忘记密码的功能”时，它可以：
1. 查阅wiki/domains/auth.md了解现有的认证流程。
2. 查看wiki/entities/user.md确认用户实体结构。
3. 参考wiki/cross-cuts/email.md了解邮件发送服务。
4. 然后，生成一个符合现有架构的、端到端的代码方案，并同时更新所有相关的维基页面。

这套karpathy-wiki-protocol不仅仅是一份规则清单，它代表了一种与AI协作的新范式：将AI从一名临时工，转变为一名拥有“机构记忆”和明确操作规程的正式员工。它需要你前期投入一些时间设置规则和模板，但一旦运转起来，它为你节省的上下文理解时间、减少的沟通误解、提升的代码质量，将是巨大的。最关键是，它让你的项目知识活了起来，并且随着每一次代码提交，自动生长，永不腐烂。