OpenWiki有一个更好的模式
你添加到CLAUDE.md的每一个有用的东西都会让文件变得不那么有用。架构注释、命令、约定、边缘情况——指令文件不断增长，直到每次智能体运行都必须携带一本大部分不需要的手册。LangChain的新OpenWiki认为问题不在于文档本身，而在于你把它放在哪里。
LangChain在7月1日发布了这个工具，整个论点都在其发布文章的一行中：像AGENTS.md和CLAUDE.md这样的指令文件"不是存储数百页仓库文档的正确位置。它们应该将智能体指向正确的上下文，然后让智能体检索它需要的内容"（LangChain）。
这是一个小句子，里面有一个大主张。常见的失败模式恰恰相反：把智能体可能需要的所有东西都堆进CLAUDE.md，看着它膨胀，并希望模型能读到底部。OpenWiki说别这么做了。生成一个合适的wiki，在指令文件中留下一个简短的指针，让智能体在需要时获取它需要的页面。检索，不要堆砌。
我认为这个论点是对的。我也认为提出这个论点的仓库才刚出生一天，没有发布版本，实际上也没有运营历史。这两件事都是真的，所以我按顺序来谈。
1、为什么容器很重要
当智能体理解仓库时，它能写出更好的代码。这一点没有争议。问题是如何让模型理解这些内容，大多数实际选项介于两个极端之间。
一个极端：全部预加载。关于代码库的所有内容都生活在指令文件中，每次智能体运行都读取整个文件，无论它是否需要认证模块的文档。在一个大型仓库中，这个文件增长到数百页，模型浪费令牌读取它不会使用的上下文，而在每次拉取请求后手动更新它是没人做的苦差事，所以它会腐烂。
另一个极端：将知识保存在结构化的地方，在指令文件中放一个地图。智能体读取简短的地图，弄清楚它需要关于队列工作者如何连接的页面，然后检索那一页。这就是新工程师使用真实wiki的方式。你不会在第一天阅读整个Confluence空间。你阅读索引并打开你面前任务要求的内容。
用一条具体的线来划分会更容易理解。在CLAUDE.md中保留命令、行为规则和路由指令——每次运行真正需要的东西。将架构解释、子系统关系和详细的仓库知识移入wiki，智能体可以在任务需要时去获取它们。指令文件变得更短，知识变得更深入，同时发生。
OpenWiki是对第二个极端的押注，它不仅仅是一个风格偏好的原因是成本和陈旧。臃肿的指令文件在每次运行中都很昂贵，而且很难保持最新。指针加选择性检索可以减少每次运行加载的上下文，特别是当替代方案是一个经常变化的大文件时，它将更新问题局部化到实际更改的页面。LangChain公开承认了这个谱系——DeepWiki、Factory的AutoWiki和Andrej Karpathy的LLM-wiki概念都推动了同样的想法。Karpathy的版本值得单独说一分钟，因为它精确地命名了OpenWiki正在自动化的东西。
2、底层模式：Karpathy的LLM wiki
四月份，Karpathy发布了一个描述他所谓的LLM wiki的要点，他的框架从通常替代方案的问题开始。标准RAG在查询时从原始文档检索相关块，这有效，但正如他所说，"LLM在每个问题上都从头重新发现知识。没有积累。"每一个跨越五个文件的微妙问题每次都从碎片中拼凑出来，什么都没有建立起来。
wiki模式将这项工作移到写入时间。LLM增量构建和维护一组持久的相互链接的markdown页面，位于读者和原始源之间。三层：原始源，不可变且永远不被模型编辑；wiki，完全由模型拥有；以及一个模式文件，告诉模型wiki的结构以及如何维护它。三个操作使其保持活跃：摄入读取新材料并更新它触及的每个页面；查询通过中央索引导航wiki，而不是对原始文档分块；lint定期扫描矛盾、孤立页面和较新源已超越的主张。
让我坐起来的细节是：在Karpathy的描述中，模式层字面上就是一个CLAUDE.md或AGENTS.md文件。指令文件是知识的操作地图，而不是知识本身。OpenWiki采用这个模式并将其指向代码库。对于仓库，代码和git历史扮演着与Karpathy的原始源和摄入层相似的角色，lint和更新循环变成一个计划的CI作业。Karpathy的版本是一个人和一个智能体手动维护个人知识库。OpenWiki的赌注是，对于仓库，维护者可以是一个定时作业。
3、OpenWiki如何实际工作
这个工具是一个CLI，你可以用npm安装并针对仓库运行。
npm install -g openwiki
openwiki --init
--init命令询问模型提供商和API密钥，然后将初始文档生成到你仓库中的openwiki/目录中。运行普通的openwiki你会得到一个交互式会话；运行openwiki --update它会刷新现有文档。配置和密钥存储在你机器上的~/.openwiki/.env中。
两个设计选择值得研究，因为它们是可重用的想法，即使你永远不安装这个东西。
它为你写指针。生成wiki后，OpenWiki向你的AGENTS.md和CLAUDE.md追加提示（如果不存在则创建），告诉你的编码智能体在搜索上下文时参考wiki。你不需要手动连接引用。工具插入"当你需要仓库上下文时，看这里"的指令，这样你已经在使用的智能体就能在不改变工作流的情况下获取它。
它通过git差异保持自己最新。这部分将OpenWiki与"运行一次文档生成器然后忘记它"区分开来。在初始化或更新运行后，OpenWiki记录git head和时间戳，反映其文档。下一次--update运行读取该记录，并向git询问自上次以来确切落地的内容：发布时，源代码显示它运行git log <last-head>..HEAD --name-status并将该证据提供给智能体，因此更新范围限定在已更改的文件，而不是完全重新生成。仓库附带的示例GitHub Action将其连接到每日计划，无头运行openwiki --update --print，并打开一个包含文档更改的拉取请求。设计意图是稳定的部分：输出是PR，而不是直接提交，这意味着人类仍然控制下游智能体将视为什么的真相。
在表面之下，它基于LangChain的DeepAgents框架构建，如果你提供密钥，可以将运行追溯到LangSmith，所以你可以检查智能体在编写文档时确切做了什么。它是模型无关的：支持OpenRouter、Fireworks、Baseten、OpenAI和Anthropic，默认通过OpenRouter使用开放模型。许可证是MIT。
4、实践中
你可以在大约十分钟内开始在临时分支上测试这个，你应该这样做，因为我最关心的失败模式只有在你阅读它生成的内容时才会出现。
在任何运行之前进行一次预检。从干净的工作树开始，扫描仓库中的凭证、数据转储、客户记录和其他你不会有意发送给模型提供商的东西，因为OpenWiki读取仓库来编写文档。临时分支保护你的文件；它不是一个隐私边界。选择一个你公司实际允许用于源代码的数据处理提供商，并知道大型仓库上的第一次生成会花费真实的API费用。退出是便宜的，值得一提的是：删除openwiki/，恢复指令文件差异，删除Action。
- 选择一个你了解的仓库，在新的分支上。不是你最重要的那个。你需要一个你能立即判断生成文档是否正确的代码库，因为判断准确性是这次试验的全部意义。
- 安装并初始化。
npm install -g openwiki，然后openwiki --init。当它询问提供商时，使用一个你接受其数据处理的代码（在限制中有更多说明）。让它生成到openwiki/中。 - 对照现实阅读生成的页面。打开三四个关于你深刻理解的系统部分的页面。问唯一重要的问题：这个描述是真的吗，遵循它的智能体会做出正确的更改吗？具体来说：组件和依赖关系命名正确吗，智能体能定位每个声明指向的代码吗，页面解释了架构还是只是用散文重述了代码？一个90%正确但另外10%自信错误的wiki是危险的结果，因为智能体无法分辨哪10%是错的。
- 检查它写入指令文件的内容。查看
AGENTS.md和CLAUDE.md的差异。决定你是否希望那个指针那样措辞并指向它指向的地方。这是你的智能体的常驻指令，所以把它当作代码对待，而不是你浏览的生成制品。 - 只有在那时才添加Action。将示例工作流复制到
.github/workflows/openwiki-update.yml，让每日PR运行一周。像审查任何其他PR一样审查每个更新PR。价值在于这些PR在代码移动时是否保持准确，你只有在观察几个之后才会知道。
十分钟的胜利是步骤一到三。如果生成的页面在你知道的代码上是准确的，工具就在做它的工作。如果它们读起来合理但偏离了真相，你在将其接入任何永久性的东西之前就学到了最重要的东西。
5、诚实的限制
势头和仓库之间的差距是真实的，假装不是那样恰恰是这个品牌存在以避免的炒作。
它是全新的。将OpenWiki放在我雷达上的简报在发布一天内就将其推到了Trendshift每日榜单的顶部。但该项目仍处于公开生活的第一天，没有发布版本，实际上也没有运营历史（GitHub）。趋势榜速度是关注度，不是采用率。一家知名公司购买的是一个项目的关注，不是裁决。
生成的知识使错误持久化。这是更深层次的结构性风险——称之为内建幻觉，这是将工作从查询时间移到写入时间的代价。在普通RAG中，误解你代码的模型通常产生一个错误答案，错误随聊天消失，因为下一个查询回到源。wiki模式使合成的解释持久化和可重用，这提高了它的价值和错误的爆炸半径：误读作为文档写入磁盘，每个读取该页面的下游智能体都将其作为事实继承。一个错误记录的认证流程不是一个坏答案；它是一个常驻指令，在有人发现之前错误地路由每次运行。差异范围更新和PR门控正是为了缩小和捕获这些错误，但这只有在审查实际发生时才有效——这就是为什么我一直说要阅读页面。
计划的刷新仍然留下陈旧窗口。不同步的wiki比没有wiki更糟，因为智能体会遵循对已不存在的代码的自信描述，并针对旧形状做出更改。OpenWiki的答案是每日更新，但"一天一次"也是差距的大小。具有大量PR流量的仓库可能在代码已移动但wiki未移动的窗口中花费数小时，该窗口中的每次智能体运行都在信任过时的地图。该工具缩小了陈旧问题；它没有关闭它。
私有代码和大型monorepo需要额外审查。OpenWiki将仓库内容发送给你配置的任何模型提供商——对每个托管选项都是如此，而不仅仅是OpenRouter默认。在将其指向私有代码之前，检查你选择的提供商的路由、保留和训练策略，以及你的公司是否允许向其发送源代码。规模是另一个限制：整个技巧取决于智能体首先读取中央索引并打开它需要的少数几个页面，Karpathy自己的描述说索引优先导航"在中等规模下效果惊人地好"，他将其定在大约一百个源和数百个页面。一个庞大的monorepo会超过这个限制，此时索引本身成为臃肿的指令文件，问题已经移动，而不是消失。对于大多数仓库，这不会咬人；对于最大的仓库，这是要测试的第一件事。
一个值得明确说明的边界：文档不是执行。wiki可以告诉智能体架构如何契合以及约定是什么。它不能使这些成为真的。安全边界、数据库不变性、格式、权限和部署策略属于可执行检查：测试、lint、模式、CI。智能体可能阅读的散文比失败的检查更弱的保证，所以将wiki视为执行之上的解释层，永远不要将其视为替代品。
谁现在应该跳过它：任何今天需要生产稳定性的人，在一个错误的智能体编辑代价高昂的仓库上，并且无法腾出审查时间来检查生成的页面和每个更新PR。这个想法已经准备好。版本号还没有。
6、这实际上在测试什么
剥去具体工具，OpenWiki是关于智能体持久知识应该生活在哪里的提案。不是在模型的权重中，不是塞进一个指令文件中，而是在一个结构化的、可检索的存储中，指令文件只是指向它。LangChain说这个模式超越代码泛化，到任何智能体需要上下文而不是携带的工作流。这是值得观察的部分，无论这个特定的CLI是否是获胜的那个。
所以这是我向你提出的开放问题。如果指令文件变成地图而不是手册，地图现在是你拥有的最重要的东西，因为错误的指针会错误路由每次运行。你信任一个计划的智能体来保持那个地图诚实，还是地图是你仍然希望人类手写的那件制品？在一个分支上安装它，阅读它关于你知道的代码生成的内容，让你自己的仓库而不是星标数来回答这个问题。
原文链接：Stop Stuffing Your Repo Into CLAUDE.md. OpenWiki Has a Better Pattern
汇智网翻译整理，转载请标明出处