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/内的其他页面或者通过明确的注释如!-- src: path/to/source/file.md#L10-L20 --追溯到原始资料层的具体位置。作用这建立了信息的可追溯性。当源文件变更时AI能快速定位哪些维基陈述可能失效。矛盾处理规则当AI在编译中发现原始资料间存在矛盾例如代码注释说A而设计文档说B它不得自行选择一方。标准操作程序在相关维基页面中创建一个“待决争议”章节。客观陈述矛盾双方的观点和出处。将页面状态标记为status: PENDING_REVIEW。在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将“更新维基”视为次要任务最终遗漏。解决方案强化提示词在给AI的任务描述开头就强调“本任务分为两部分1. 主要编码任务2. 根据协议更新维基。你必须在最终答复中包含两部分的结果。”使用“清单”格式要求AI在思考过程中显式地列出“待办事项”其中必须包含“更新维基”。后置检查在团队工作流中引入一个简单的检查步骤。例如代码审查时顺便检查本次提交关联的log.md记录。6.2 问题维基页面内容过于冗长或琐碎现象AI把源代码的每一行注释都搬到了维基里导致页面臃肿失去了“编译提炼”的意义。根因协议中“引用溯源”的规则被过度执行AI误以为需要复制所有细节。解决方案在schema.md中明确“抽象层级”在模板里说明维基页面应该提供的是概念模型和关键关系而非实现细节。细节应该通过引用链接到源文件。举例说明在协议中增加正面和反面例子。例如实体页面应该列出字段的业务含义和约束而不是把数据库迁移文件的SQL列定义照搬过来。人工审核与反馈在初期定期浏览AI生成的页面。如果发现过于冗长直接指出并告诉AI“这个页面太细了请提炼到概念层面。” AI会从反馈中学习。6.3 问题内部链接Wikilinks断裂现象wiki/index.md中显示有链接但点击或AI尝试引用时发现目标页面不存在。根因页面被重命名或删除后没有同步更新所有引用它的地方。解决方案让AI运行链接检查脚本可以在验证门禁中增加一条“运行一个简单的脚本检查wiki/目录下所有.md文件中的[[PageName]]链接确认wiki/PageName.md文件存在。” AI可以自己生成并运行这个Python或Bash脚本。使用唯一标识符考虑使用更稳定的标识符如实体ID而不是易变的文件名作为链接。但这会增加复杂度。对于大多数项目定期如每周让AI执行一次全量链接审计就足够了。6.4 问题多AI代理协作冲突现象如果团队中多个成员同时使用AI代理在同一个项目上工作可能会发生对同一个维基页面的并发修改冲突。根因维基文件是纯文本Git在合并时可能会产生冲突。解决方案领域分区在项目初期就划分清晰不同的AI代理或同一代理的不同会话负责不同的功能领域。这自然减少了编辑冲突。基于Git的工作流教导AI遵循一个简单的Git分支策略。例如每个功能分支上的维基更新只在合并回主分支时才整合。AI需要能处理简单的Git合并冲突或至少识别并报告冲突。最终人类仲裁将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“添加一个忘记密码的功能”时它可以查阅wiki/domains/auth.md了解现有的认证流程。查看wiki/entities/user.md确认用户实体结构。参考wiki/cross-cuts/email.md了解邮件发送服务。然后生成一个符合现有架构的、端到端的代码方案并同时更新所有相关的维基页面。这套karpathy-wiki-protocol不仅仅是一份规则清单它代表了一种与AI协作的新范式将AI从一名临时工转变为一名拥有“机构记忆”和明确操作规程的正式员工。它需要你前期投入一些时间设置规则和模板但一旦运转起来它为你节省的上下文理解时间、减少的沟通误解、提升的代码质量将是巨大的。最关键是它让你的项目知识活了起来并且随着每一次代码提交自动生长永不腐烂。