单文件 Agent 指令天花板：AGENTS.md 模式优缺点深度分析

Fabrice Sanglard 的「我的 agent.md 改善 LLM 辅助代码质量」周末登上了 Hacker News 首页：325 个点赞、138 条评论，以及一整串工程师交流规则文件的帖子，像在分享食谱。隔壁标签页，GitHub 趋势榜属于 andrej-karpathy-skills，这是一个围绕单文件 CLAUDE.md 构建的仓库，萃取了 Andrej Karpathy 关于 LLM 编码陷阱的公开观察；目前约 206,000 颗星，而 Karpathy 本人并未编写它（详见下文）。如果你想证明单文件 agent 指令模式占据了当前讨论的热度，那就是这周了。

简言之：仓库根目录下一个 markdown 文件，是教编码 agent 你的规范最便宜、最便携的方式，而本周的 325 点赞帖子和 206k 星仓库表明市场对它的需求有多大。但这个模式有结构性天花板：约定变化时文件会腐化，矛盾被任意消解，静态文本无法描述一个运转中的系统。用这个文件存稳定规则，其余一切运行时检索。

为什么大家都在交付一个指令文件？

因为所有厂商终于同意读取一个了。AGENTS.md，这个现在由 Linux Foundation 的 Agentic AI Foundation 托管的开放格式，被 OpenAI Codex、Cursor、GitHub Copilot、Google Jules、Zed、Aider 以及众多其他工具所读取，超过 60,000 个开源项目已经携带这个文件。Copilot 在你仓库任意位置都能找到它，根目录再加 CLAUDE.md 或 GEMINI.md。Claude Code 读取 CLAUDE.md 并文档化了一行 @AGENTS.md 导入，让两个工具共享同一来源。我们在 CLAUDE.md vs AGENTS.md vs Cursor 规则中梳理了格式差异。

需求侧同样强烈。Sanglard 精确描述了这种痛点：他不断在每个会话中输入相同的纠正（"不要用魔法数字"、"函数名要简短"），直到他把它们写下来一次。Karpathy 衍生仓库的星标增长速度同样说明问题——这个仓库把开发者从 Karpathy 一月推文中萃取的四个行为原则打包在一起（Karpathy 与该仓库无任何关联）；四个原则（编码前思考、简洁优先、精准改动、目标驱动执行）仅用 65 行，恰好说明了重点：这种模式的卖点就是 65 行精挑细选的内容胜过任何数量的脚手架。

这种模式真正做对了什么？

比批评者承认的要多。单一 agent 指令文件可在工具间便携、与代码版本同步、可在 pull request 中审查，且无需任何基础设施。最后这点 quietly radical：你的 agent 的操作指南获得了与它所管辖代码相同的 diff 和审查待遇，而不是存在于聊天记录和部落知识中。

有证据表明它有用，尽管比星标数暗示的要薄。2026 年 2 月一篇 arXiv 研究跨四个 agent-model 组合发现，开发者编写的上下文文件将任务成功率平均提升了约 2.4%，这个提升未达到统计显著性，但它确认了 agent 紧密遵循文件内的指令。作者自己的结论落地在实践者所在的地方：这些文件通过指定非标准实践来发挥作用，而不是提升原始性能。注意 Sanglard 的规则和 Karpathy 原则的共同点：它们是稳定的偏好。"始终使用大括号"、"提取魔法数字"、"做精准改动"下个季度同样为真。这就是最佳区间。Sanglard 自己的演进路线很有启发性：他 2025 年中尝试 LLM 辅助工作产生的代码无法编译，而到 2026 年模型可以实现有索引的二叉堆并精确定位一个冷门 bug，但仍会发出他所谓的意大利面条式代码——直到规则文件约束了风格。他的判决恰如其分且不动感情："LLM 不断产生幻觉，无法被信任。"文件解决不了这个。它只是通过让输出可预测来降低审查成本。

工艺指导也在收敛。Claude 文档建议保持在 200 行以内，Copilot 文档建议指令不超过两页，Codex 默认将合并大小上限设为 32 KiB，Cursor 建议规则保持在 500 行以内。简短文件会被遵循；冗长的会被略读。如果你的已经膨胀了，这是审计和修复臃肿 CLAUDE.md 的方法。

单文件在什么地方触及天花板？

与所有静态产物相同的地方：现实开始移动的那一刻。你的团队迁移测试框架、重命名服务、或推翻架构决策，而文件继续自信地陈述旧世界。没人会因为它漂移而被呼叫。我们在规则文件腐化和保持 agent 指令更新中追踪了这种失败模式。

矛盾更糟糕，因为它们静默失败。Claude 自己的内存文档直白地说："如果两条规则相互矛盾，Claude 可能任意选择其一。"Copilot 文档同样警告"相互冲突的指令集"。你的规则没有编译器、没有错误、没有 lint。你发现错误的时候，是 agent 令人信服地做错了事。

然后是规模问题。每个仓库一个文件，乘以五十个仓库，乘以三种格式，是一个伪装成文档模式同步问题；我们已经覆盖了保持 CLAUDE.md、AGENTS.md 和 .cursorrules 同步。同样的 arXiv 研究发现 LLM 生成的指令文件在大多数测试设置中让 agent 稍微变差，而每种上下文文件平均将推理成本膨胀了 20% 以上。Sanglard 帖子的评论者进一步指出：大量这些文件是对不再存在的模型行为的化石式 workaround。讨论中还有两条怀疑路线值得借鉴。第一，任何 linter 可以强制执行的应该住在 linter 里，因为合规是确定性的而非概率性的；文件应该只承载工具无法检查的内容。第二，前沿模型比它们 2024 年的祖先需要少得多的程序性指导，所以一条在两个模型代际前合理的规则现在可能只是纯粹的上下文税。两条论点指向同一方向：文件诚实的范围在不断缩小，缩小到只有你的团队能做出的判断。

什么适合放在文件里，什么在运行时检索？

按变化频率分割。稳定且仓库范围的值得进入文件：

构建、测试和 lint 命令，以及运行它们的顺序

你的工具无法强制执行的命名约定、分层规则和风格判断

always/never 清单：审批工作流、禁止目录、部署规则

指向更深层文档的指针，agent 在触碰敏感区域前应该先读这些

每周都会变化的一切都排除在外。昨天发版了什么、邻近分支正在推进什么、工单实际在问什么、那个 Slack 线程在下午 4 点决定了什么：这些都不能存在于静态文件中，因为文件在提交时是真的，而工作正在当下发生。这是这种模式没有任何 markdown 模板能解决的部分，这就是为什么停在文件层面的团队会继续看着他们的 agent 做出自信、格式良好的错误。

后半部分是上下文引擎的用途。Unblocked 连接你的仓库、问题追踪器、Slack 和文档，让 agent 查询当前的机构上下文而不是信任一个快照；规则文件与上下文引擎的对比文章涵盖了架构，以及为什么不只是 Claude Code 讲内置内存止步的地方。这是给你的 agent 一张过胶卡片和给它一个可以提问的人之间的区别。

这是实践中它的样子，来自 Clio 的一位工程师：

"我构建了一个叫 'enrich' 的步骤，在任何代码被写之前运行。agent 向 Unblocked 请求所有内容——工单、Slack 上下文、相关仓库中已经完成的工作——然后才开始实现。它对跨仓库工作特别强大，否则你得自己做所有那些考古工作。"

——Arthur Rodolfo，Clio 软件工程师

文件告诉 agent 你的团队如何写代码。检索告诉它实际正在发生什么，这是机构记忆和共享团队记忆中枢的工作，不是 markdown 快照。

常见问题

我应该写 AGENTS.md 还是 CLAUDE.md？

写 AGENTS.md 并从这里桥接。它是供应商中立的格式，拥有最广泛的支持，而偏好自己文件名的工具可以消费它：Claude Code 文档化了一行 @AGENTS.md 导入（或一个普通符号链接），Copilot 原生读取共享文件。维护平行的手动编辑副本正是指令文件分道扬镳的方式，所以选一个规范文件并生成或导入其余的。单体仓库免费获得嵌套：Codex 从 git 根目录向下走，让更近的文件覆盖更早的指导，Cursor 组合嵌套文件，更具体的指令优先，所以每个服务的规则可以住在服务旁边。

agent 指令文件应该多长？

比你现有的那个短。供应商在这里异常一致：200 行以内（Claude）、两页（Copilot）、32 KiB 合并（Codex）、500 行以内（Cursor）。遵循度随长度下降，因为指令与你的实际任务竞争注意力。一个有用的习惯：每次你加一条规则，删除或验证一条。把文件当作 API 表面，而不是无限追加的日志。

这些文件可衡量地改善 agent 输出吗？

几乎不能，而且只在人类编写时才行。arXiv 评估发现开发者编写的文件带来 2.4% 平均提升，未达到统计显著性，LLM 生成的文件有小幅负面效应，且各模型间差异很大；Claude Sonnet 4.5 实际上带它们得分略差，而一个较小的开源模型提升了近八点。研究的标题更直白：上下文文件通常不改善成功率，且增加超过 20% 的推理成本。基准测试不能捕捉一切（一致性、审查负担、避免返工），但数据支持写一个小而精的文件，而不是生成一个大文件。

你仍然应该写的那个文件

写这个文件。保持在几百行以内，限制在上季度为真、下季度仍为真的规则，版本化它，并按计划修剪它。把矛盾当作 bug，因为你的 agent 会通过抛硬币来消解它们，把每条 linter 可以强制的规则当作属于 linter 的规则。这种模式当之无愧地登上了首页：便宜、便携、可审查的指导胜过永远把纠正输入聊天框，而研究与这个缩窄版卖点一致——一个编码你非标准实践的文件，即使不会移动基准测试。

只是不要让一个 markdown 文件充当你团队的记忆。它是双层系统的稳定层，而动态层——你的 agent 在任务中途需要的工单、线程和跨仓库历史——属于从一个在团队更新时同步更新的真实来源检索。一文件统治你的 agent 的风格。一个上下文引擎处理文件无法知晓的一切。