你的下一个代码贡献者很可能不会读 Wiki，也不会打开文档站里的贡献指南，更不会先问一句“这个 issue 我能做吗”。它是一台 AI 智能体，扫一眼仓库当前目录旁的 AGENTS.md，然后直接提交 pull request。听起来像未来，但 AutoGPT 维护者已经在处理这件事。真正麻烦的不是机器来了，而是它读取世界的方式跟人类完全不同。
文档没死，只是被放错了地方
智能体不会翻 Wiki，它只看脚下
AutoGPT 维护者最初以为文档不够完善。他们把贡献指南、架构说明、路线图写进 Wiki，用文档站整整齐齐发布出来。智能体照旧乱交 PR。后来他们发现，AI 智能体只读当前目录层级的指令文件。它不会像人类开发者那样四处点链接，也不会因为某份文档更权威就多看一眼。它只抓代码目录旁的 AGENTS.md 和技能文件。
这个事实让人有点难接受：文档写得再好，放错了地方，对机器贡献者来说等于不存在。不是内容问题，是入口问题。维护者后来不再往 Wiki 里堆说明，而是把指令直接放进代码旁边。位置变了，智能体的行为立刻出现变化。
发现机制比文档厚度更值得先解决
很多团队还在纠结给 AI 写文档要不要更细。AutoGPT 的经验是，先解决发现机制，再谈文档质量。智能体没有“找不到再搜一下”的耐心，读取路径非常窄。你给它一个入口，它才可能用；不给入口，它就直接凭上下文硬来。把 AGENTS.md 放在代码目录旁，这个动作简单得不起眼，却比继续完善 Wiki 有效得多。
这个判断很冷酷：如果你的指令没有被机器读到，那对 AI 贡献者来说，它约等于不存在。写作水平当然重要，但前提是文档必须出现在机器真正会扫过的地方。否则你只是在给空气讲道理。
技能文件负责“下一步”，不是讲来龙去脉
除 AGENTS.md 外，维护者还在代码目录旁放置技能文件。它们不是给人读的长篇背景，而是让智能体在具体任务里减少低级错误的短路径提示。可以理解成给新员工一张工位卡片，而不是塞一本公司文化手册。机器不需要知道项目全部历史，它需要知道当前目录下能做什么、不能做什么、下一步该检查什么。
没有门槛，机器就敢乱来
PR 模板先挡掉一批胡扯
早期智能体提交的 PR 经常缺关键信息：为什么改、改了什么、动了哪些模块。维护者引入强制 PR 模板以后，情况开始好转。模板不是摆设，而是一组必须填写的字段。智能体为了把表单提交出去，会逐项补齐说明。这不保证代码正确，但至少让维护者不用在完全没法审的垃圾提交里浪费时间。
一个机械动作，把 PR 从“不可用”拉到“可以审”。这个变化谈不上性感，但它显著降低了维护者的认知负担。对开源项目来说，审一个信息齐全的错误 PR，远比审一个语焉不详的错误 PR 省力。
测试计划和覆盖率门槛拦的是幻觉
第二步门控更硬：要求测试计划，并设置 CI 覆盖率门槛。智能体有时能写出看起来合理的代码，但一跑测试就露馅。维护者要求每个 PR 必须附带测试计划，并且通过覆盖率检查。对机器来说，这是明确可计算的约束；对维护者来说，这是把幻觉代码挡在合并前的闸门。
这里没有模糊空间。你不能只写“请确保质量”，那对智能体毫无意义。清晰的数字、可执行的流程、必须通过的检查，才能被机器理解并遵守。覆盖面越具体，机器越难蒙混过关。
CLA 签名意外成了人类探测器
最让人意外的是 CLA 签名。它本来是法律流程，要求贡献者签署贡献者许可协议。但因为需要浏览器和 OAuth 流程，许多智能体卡在这一步过不去。维护者发现，能顺利完成 CLA 签名的多半是人类。于是这个原本不起眼的步骤，被叫作“人类探测器”。
它不算精确，也不是有意设计。但一个需要跳转、登录、授权的操作，对自动化代理来说就是额外障碍。对人类只是多点几下鼠标，对智能体却可能意味着流程断裂。至少在当前阶段，这道障碍意外好用。
可用，但不代表有价值
机器能把事做对，却常常做错方向
门控机制把大量垃圾提交挡在门外，但维护者很快撞上新难题：智能体提交的 PR 确实可用了，却经常不符合项目路线图。它能把一件事做对，但做的不是项目眼下最需要的事。人类贡献者会看 issue 标签、里程碑、讨论里的优先级，智能体不会。它只看到任务和规则，看不到方向。
这让“好 PR”的判断标准得改一改。一个能跑、有测试、信息齐全但与路线图冲突的 PR，仍然是负担。维护者必须花时间理解它、回复它、拒绝它，而这些时间本可以投入更重要的工作。
路线图不写清楚，机器就自由发挥
想让 AI 提交的内容符合路线图，就得把路线图放进它读得到的地方。AGENTS.md 和技能文件可以承担这个角色。维护者需要在里面明确写出：当前不接受哪些模块改动、哪些方向冻结、哪些类型的 PR 必须关联已确认的 roadmap issue。没有这些约束，智能体会按照“看起来合理”行动，批量产出正确但无用的提交。
这很像管理初级开发者。你不说明边界，对方就按自己的理解干。区别在于机器干得更快，规模更大。错误方向上的高生产力，往往比低生产力更难处理。
与其事后拒绝，不如把筛选前置
一些维护者开始把路线图约束直接写进智能体的读取阶段。既然它只读 AGENTS.md，那就在里面写“现阶段不要碰登录模块”“新功能必须关联已确认的 roadmap issue”。这种前置筛选比事后拒绝省事得多。门控机制也从“挡住坏 PR”延伸到“减少不该出现的 PR”。
AutoGPT 的经历说明，继续接受 AI 贡献，就得调整维护方式。不是简单欢迎机器，而是给机器造好跑道、画清边界。人类探测器只是临时工具，真正重要的是让机器在正确边界内做事。
开源维护正在变成一场上下文工程
维护者不再只是审代码的人
当贡献者从人变成人和机器混杂，维护者的工作重点开始转移。过去大部分精力在 review 代码逻辑、判断架构影响。现在越来越多精力要花在设定规则、维护指令文件、设计流程约束上。维护者更像在管理一组半自动化的代理，而不是只看 diff。
这个转变不轻松，但躲不开。因为机器贡献者会持续存在，而且数量只会更多。把人类维护者的时间消耗在大量无意义提交上，不是办法。
人类探测器不会一直有效
CLA 签名作为人类探测器，是当前阶段的权宜之计。随着智能体操作浏览器、处理 OAuth 的能力增强，这道障碍迟早被绕过。把它当成长期安全边界不现实。真正能持久的，是清晰的入口、可执行的约束和前置筛选。人类探测器可以作为一个信号，但不能成为唯一防线。
开源项目如果只依赖“机器不会点浏览器”这类漏洞来维持秩序，很快就会被动。规则必须建立在机器能读懂、能执行、能验证的基础上。
接住 AI 贡献前，先建好入口和边界
对那些即将迎来 AI 贡献者的项目，AutoGPT 的经验已经给出答案：先把 AGENTS.md 放到代码旁边，把技能文件放到任务附近，再用 PR 模板、测试计划、覆盖率和 CLA 建立门控。最后，把路线图写进机器读得到的地方。顺序不能反。入口没建好，后面的一切都白搭。
开源世界过去几十年一直在优化人类协作。现在机器协作出现了，规则需要重新设计。这不是恐慌，也不是鼓吹。它是一种很实际的维护策略：理解机器怎么读代码库，然后按它的方式设置入口，让它别再把你的 issue 列表和 review 时间当成游乐场。
