5 个增长最快的开源项目,都多写了一份文档——给 AI 看的那一份

两个人在同一个项目上干活，各自的 AI 编程助手给出了两种做法。一个照着项目里的甲文件来，一个照着乙文件来。两份文件都还在，只是有一份忘了跟着改。谁都没觉得自己做错，最后是同一句指令、两种结果，得靠人去吵出到底以哪份为准。

说了算的不是助手，是文件。这个被忽略很久的问题，2026 年 8 月底被一条推文捅到台面上：一位创始人说，他在考虑把自家在用的 Claude Code 禁掉，因为它只认一个文件名。那条推文 72.5 万人看过。

吵来吵去，绕开的其实是一件更基础的事。现在打开你项目的，已经不只人了。

一个项目，两个读者

8 月底还有一份公开的方法论文章，作者拆了五个增长很快的开源项目——PostHog、Supabase、n8n、Postiz、Resend，想看它们做对了什么，能让 agent 在自己仓库里干活。

他排在第一位的，是文档，而且是专门写给 agent 的那一份。

做法不复杂。仓库根目录放一个 AGENTS.md，或者 CLAUDE.md，写清楚这个项目怎么组织、重要代码在哪、怎么改、怎么测、有哪些约定和不能碰的边界。关键信息写在最前面，因为 agent 读文档不像人，它不会往后翻着找。

PostHog 和 n8n 用 AGENTS.md。Postiz 用 CLAUDE.md。Supabase 更碎一点，把给 agent 的说明分散在好几个仓库里。

这几家的共同点，是把"项目怎么用"从人脑子里的默认，搬成了仓库里的一等公民。以前这些知识靠老员工带、靠口口相传，现在得写在明面上，因为来干活的那个，没人可问。

两份说明打架的时候

麻烦就出在这。

同时维护 AGENTS.md 和 CLAUDE.md 的项目，这两份绝不能互相矛盾。今天 Claude Code 找的是 CLAUDE.md，不是 AGENTS.md，所以很多人两份都留——可只要一份改了、另一份忘了同步，agent 就在两套说法之间摇摆。报错，白烧 token，最麻烦的是它开始不信任这个仓库里写的任何东西。

那位创始人把这种状态叫 split brain，脑子裂成两半。同一个团队里，两个人用着不同的工具，各自读到自己那份说明，对同一个项目做出两种做法，谁也说不清哪种才算对。

这跟模型多聪明没关系。同一个模型，说明书写一致，它稳；两处打架，它就飘。

反过来说也成立：你不需要一个更强的模型，你需要一份不打架的说明。这一步不花钱。

文档只解决"看得懂"

接下来是"用得动"。

那份文章给 agent 设计入口排了四层：能直接调的 API，能发现和调用工具的标准接口 MCP，能用终端命令控制的 CLI，能拿去做集成的 SDK，再配一批示例和模板。

其中一个判断值得记下来。有了 MCP，你的产品就不只是"agent 能替代的东西"，而是"agent 依赖的基础设施"。前者的命运是被重写掉，后者是别人绕不开你。

示例和模板还兼职干另一件事：它们是 agent 会照抄的范本。你给一个能跑通的最小例子，它大概率照着这个去集成；你不给，它就自己猜，猜出来的东西你收尾时得一条条砍。

还有个容易漏的角落，robots.txt 和 llms.txt。robots.txt 管的是爬虫能进哪些页面，写错、或者干脆没有，爬虫就进不来，你的产品根本不会出现在 ChatGPT、Claude 这类助手的回答里。llms.txt 是个还在成形的新约定，给语言模型指一份站点地图。

这两件事没做，不是没人用你，是 agent 找不到你。

开源之前，先翻一遍 Git 历史

这是原文里最实在的一句提醒，也最容易吃亏。

把一个原本私有的仓库开放出去之前，先查 Git 历史。旧的提交里可能留着早就删掉的 API key、内部地址、客户信息，还有你从没打算公开的文件。只审最新那一版文件不够——删掉的东西都还在历史里躺着，一条命令就能翻出来。

清理 Git 历史，是开源这件事的一部分，不是可选项。你以为删了，历史里没删。

换到设备上，问的是同一句话

一份接口定义，两处各写各的，现场就是对不上。一条指令有没有稳定的入口，断开重连之后认不认编号接着走。这台机器现在到底在跑什么，报的"正常"是查出来的还是猜的。系统交出去之前，有没有把不该露的东西清干净。

agent 在你仓库里迷路，和一台设备接上总线不说话，是同一种病，都是给执行者的那份说明，写得不清楚，或者写了两个版本。

把系统讲透，比把系统讲大更有用。

你们项目里那些给机器看的说明——配置文件、接口定义、给助手的提示，现在是只有一份，还是已经悄悄裂成两份了？

以上事实与数字，来自 2026 年 8 月底一份公开的开源方法论文章及其引用的公开讨论，不涉及任何具体项目。