本文的实证引用经过三轮分级验证。第一、二轮:35 组承重论断各投 3 票做转述保真核查(逐字核对一手原文、复算口径;105 票 0 组推翻、30 余处修正,含揪出"CLAUDE.md 一万词以内"这条官方文档中不存在的伪引用)。第三轮针对 6 组单源实证增设两个席位:反证搜索席(检索独立团队、独立数据的矛盾/证实测量)与方法学审计席(敌意审稿,有否决权)。第三轮改变了本文多处结论:2 组承重数字被审计否决(AGENTbench 的方向性成功率增减系假精度;"2,303 文件普查"的百分比分母有误)、成本方向被独立测量直接矛盾、3 组升级为多源证实。正文标签:【多源证实】=独立团队独立数据的测量同向;【单源已核】=仅此一次测量,转述保真且通过方法学审计;【方向存争】=独立测量互相矛盾;【已核】=对官方文档/源码逐字核验的机制性事实(工具行为、规范条文);【厂商口径】【现场核验】【未验证,来源】如字面。转述保真 ≠ 事实为真——单源论断的验证天花板是前者,这正是分级存在的原因。文末附来源索引。
2025 到 2026 年,几乎每一家 coding agent 厂商都在告诉你同一件事:给你的代码库写一个"给 agent 看的 README"——AGENTS.md、CLAUDE.md、.cursor/rules、copilot-instructions.md,名字不同,道理相同:agent 每次进入你的仓库都要从零探索,把构建命令、目录地图、团队规矩预先写好,它就能少走弯路。这个道理听起来显然正确,以至于"你的 repo 还没有 AGENTS.md?"已经成了一种新的技术羞辱。
但对抗验证挖出了三个不配合的事实:
第一,对照证据刚出现就互相打架。ETH Zurich 团队的多 agent 评测声称:上下文文件总体不提升成功率,推理成本反涨 20%+;另一团队对 Codex 的配对实验测得带文件时中位耗时 -28.64%、输出 token -16.58%;第三个团队测得 LLM 生成的指导文件把解决率提升 2.8-7.5 个百分点。三项全是 preprint;更要紧的是(见第 4 章),没有一项的成功率方向性数字能不掉级地通过本文的方法学审计。【方向存争】
第二,"文件要短、重要指令放开头"这类怎么写的民间智慧,第一次接受随机对照检验就全体翻车。1,650 次 Claude Code 会话的因子实验里,文件大小、指令位置、单文件还是嵌套、相邻文件有没有矛盾——四个结构变量对 agent 遵从率全部没有可检测的效应。【单源已核】
第三,同类叙事里声量最大的 llms.txt,实测消费为零的比例是 97%。Ahrefs 对 13.7 万个域名的服务器日志分析发现,发布了 llms.txt 的站点里 97% 在 2026 年 5 月一个请求都没收到——且至少四项独立测量同向。【多源证实】
这三个事实不意味着"上下文文件没用"——后文会给出目前唯一带统计检验的收益(效率),以及生产环境里经得起逐字核验的写法。但它们意味着:这个领域的最佳实践几乎全部是厂商口径,独立实证刚刚起步,起步的几篇不但与厂商叙事不同向,互相之间也不同向。本站《当代码变得便宜》的老话在这里同样适用:凡是没有对照组的数字,先问口径再引用。
正文给每条承重结论标注证据等级:
四条通用限定:(1) 本领域变化极快,所有结论以 2026-07-15 为基准;(2) 对照研究互相之间不可直接换算——各自的任务集、agent、度量都不同;(3) 两个厂商利益声明:Chroma(context rot 报告作者)是向量数据库公司,"精简上下文优于长上下文"与其产品叙事同向;AGENTbench 论文的共同作者来自商业 agent 评测公司 LogicStar.ai;(4) 本文说的"上下文文件"指 repo 内给 coding agent 的指令文件,llms.txt(面向网站/爬虫)单独一章处理,两者常被混为一谈。
规范本体简单到几乎没有内容:纯 Markdown、无必填字段、无 schema,官方定位是"README for agents"。它由 OpenAI 主导发起、多家参与(Codex、Amp、Google Jules、Cursor、Factory),2025 年 12 月起交给 Linux Foundation 旗下新成立的 Agentic AI Foundation 中立托管,与 MCP、goose 并列为创始项目。【已核】"跨厂商"是官方叙事,独立报道的版本是"OpenAI 主导后捐赠"——两种说法都对,取决于你问的是章程还是提交记录。
采用量有一个可复跑但偏松的口径。官网宣称"60k+ 开源项目使用",并附上可以自己点开复跑的 GitHub 检索式;验证者复跑后确认查询可执行,但发现两处水分:该查询做路径子串匹配(名为 agents.md/ 的目录内文件也会被计入),且计的是文件数而非项目数。作为对照,2025 年 8 月 InfoQ 报道时的口径是 2 万仓库。【已核】增长趋势是真的,精确数字当传播口径读。
嵌套规则是这个标准最有内容的部分:离被编辑文件最近的 AGENTS.md 获胜,用户在对话里的显式指令覆盖一切。monorepo 建议每个 package 放一份,官网引用"OpenAI 主仓库有 88 个 AGENTS.md"作为例证(私有仓库自报数字,不可外部审计)。注意这条优先级规则写在官网 FAQ 里而非正式规范文本中,实际行为取决于各家实现——并非所有工具都自动加载嵌套文件。【已核】
互认现状是不对称的,symlink 仍是最可靠的兼容方案。逐家核验(文档+源码):
chat.useAgentsMdFile 控制。【已核】.cursorrules 官方宣布将弃用。【已核】AGENTS.override.md 和 AGENTS.md 两个文件名;要让它读 CLAUDE.md 需要用户级配置 project_doc_fallback_filenames——这个配置不随 repo 走,意味着你不能替你的用户配好。【已核】官方推荐的迁移法就是重命名加软链:mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md;Aider、Gemini CLI 靠各自配置项兼容。【已核】收敛趋势明确,但"一个文件走天下"要靠文件系统技巧,不靠标准互认。
把 Anthropic、OpenAI、GitHub、Cursor 四家的官方最佳实践并排放,共识惊人地整齐——整齐到值得警惕,因为四家没有一家给出对照实验。
共识一:短。四家的表述和执法力度不同:Anthropic 最激烈,官方文档原句"Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"(臃肿的 CLAUDE.md 会导致 Claude 忽略你的真正指令),并建议对每一行自问"删掉会不会导致出错";官方尺寸口径在 memory 页:"target under 200 lines per CLAUDE.md file"——网上流传的"一万词以内"在官方文档中并不存在。OpenAI Codex 用机制执法:所有项目文档合计默认上限 32 KiB(源码常量 DEFAULT_PROJECT_DOC_MAX_BYTES = 32 * 1024),超出部分静默截断,有真实 issue 佐证踩坑。GitHub 的自动生成 prompt 硬性要求"不超过 2 页"。Cursor 建议单条规则 500 行以内。【已核】
共识二:可执行命令优先。GitHub 官方分析了公开仓库中 2,500 多个 agents.md 文件,总结出六个核心区域——commands、testing、project structure、code style、git workflow、boundaries——并强调把带完整 flags 的可执行命令放在文件靠前章节,而不是只写工具名;边界规则用 always do / ask first / never do 三档表述。注意这是目前样本量最大的模式分析,但 GitHub 未公布方法学与数据集,且文章语境部分围绕 Copilot custom agents,证据等级是厂商模式归纳而非受控评测。GitHub 自动生成 copilot-instructions 的官方 prompt 另有一条好要求:每条 build/test/lint 命令都必须实际运行验证过才能写进去。【已核】
共识三:monorepo 分层嵌套、最近文件优先。四家语义一致(见上章),Anthropic 的版本是:启动时加载工作目录及所有父目录的 CLAUDE.md,子目录文件在读到该目录代码时按需加载;大仓库推荐"根文件放全局约定 + 子目录文件放局部约定"的两层结构,并明确警告单个根文件"要么膨胀到覆盖每个子系统、浪费上下文,要么泛泛而谈、毫无用处"。【已核】
分歧在机制层:Cursor 的 rules 带 glob/always-apply 元数据而 AGENTS.md 无 schema;Copilot 区分三类文件(repo 级、路径级、AGENTS.md);Codex 用字节上限强制精简而其他家靠劝;Anthropic 独有一条出口——规模大了之后把约定从"每次都加载的 CLAUDE.md"迁去按需加载的 skills/plugins,官方自己承认分层文件"约定会漂移、文件会过期、没人认领根文件"。【已核】
Anthropic 的内容取舍清单值得单独记录(它回答"写什么"而不只是"写多短"):该写的是 agent 猜不到的东西——bash 命令、非默认代码风格、测试指令、repo 礼仪、项目特有架构决策;不该写的是能从代码推断的内容、详细 API 文档、频繁变化的信息。可以用 IMPORTANT/YOU MUST 等强调词调节遵从度——这条同样没有引用任何实证数据。【厂商口径,已核】
2026 年上半年出现了三篇正面回答"写了有没有用"的对照研究。它们不但结论不一致,而且经过本文第三轮的方法学审计与反证搜索之后,能站住的东西比第一眼看到的少得多。逐项过堂:
其一:AGENTbench 对照(arXiv 2602.11988,ETH Zurich + LogicStar.ai,2026-02)——名气最大,数字最弱。研究者组合了两个基准:SWE-bench Lite(300 个任务、11 个知名 Python repo,配 LLM 生成的上下文文件)和自建的 AGENTbench(138 个真实 PR 任务、12 个小众 Python repo,全部带开发者手写文件,从 5,694 个 PR 筛出;与 2023 年清华的同名基准无关)。三个 agent、四种模型配置。其声称:LLM 生成的文件普遍降解决率(SWE-bench Lite -0.5pp、AGENTbench -2pp),开发者手写的仅 +4%(且对 Claude Code 无效),成本推高约 20%;删除 README 后 LLM 生成文件转为 +2.7%。
本文的方法学审计否决了其中所有方向性成功率数字作为证据,理由有五:全文没有任何推断统计(无置信区间、无显著性检验,逐字检索确认);每个实例只采样一次,而 n=138 的二值结局下最小可检差异约 8-10 个百分点,±2-4pp 的"方向"是假精度;138 个实例聚在 12 个仓库里,"手写文件"命题的有效样本量是 12 不是 138;基准由被评测的 Codex/GPT-5.2 参与构建(筛任务、改描述、从标准补丁生成测试——循环);"有用"只被操作化为一次通过率+成本,而上下文文件宣称的收益(风格遵从、约定合规、可维护性)完全没测。它可靠支撑的只剩一句弱结论:在该设置下没有观察到大的成功率效应。【方向存争;方向性数字经审计否决】
其二:Codex 配对实验(arXiv 2601.20404,Lulla 等,JAWs@ICSE 2026)——数字最窄,但唯一带统计检验。10 个仓库、124 个真实 PR 任务,同一任务各跑两遍(带/不带开发者手写的 AGENTS.md):中位完成时间 98.57 秒 → 70.34 秒(-28.64%),中位输出 token 2,925 → 2,440(-16.58%),Wilcoxon 配对检验 p<0.05,任务完成行为不变。二次分析显示均值口径的节省集中在少数原本会"来回打转"的高成本运行上——文件更像防最坏情况的护栏,而非均匀加速器。审计裁定:real-but-weak,窄范围内成立。【单源已核】限定:单 agent(gpt-5.2-codex)、小 PR(<100 行、≤5 文件)、仅根级单文件、作者自己用"关联"措辞。
其三:Probe-and-Refine(arXiv 2606.20512,Shepard & Albrecht,Williams College,2026-06)——直接跟第一篇唱反调。在文档完整的 SWE-bench Verified 上,LLM 生成的指导文件(tree-sitter 仓库地图 + 一次性通用指导)把平均解决率从 25.5% 提到 28.3%(+2.8pp),迭代精炼后到 33.0%(+7.5pp,4 次独立试验,精炼版 vs 无指导 p<0.001)。这与"LLM 生成文件降成功率"是方向相反的直接测量(注意:其指导文件含结构化仓库地图,与典型 /init 产物不同)。【单源已核】
成本方向也在打架:ETH 说带文件成本 +20-23%,Lulla 测得 token -16.58%、耗时 -28.64%。两者任务型态(基准 issue 修复 vs 真实小 PR)、文件来源(LLM 生成 vs 开发者手写)、agent 都不同,目前无法裁决谁对——有综述文章明确把这两篇标记为"结论相反"。【方向存争】
三篇拼起来的诚实读法:
关于"文件该怎么写",厂商与社区有一整套folk wisdom:要短、重要的放开头、别拆太多文件、别有矛盾指令。2026 年 5 月的一项因子实验(arXiv 2605.10039,Damon McMillan,单作者 preprint)第一次把这些变量摆上手术台:1,650 次 Claude Code CLI 会话、16,050 个函数级观测、两个 TypeScript 代码库、五种任务,主力模型 Sonnet 4.6,测量 agent 对一条简单标注指令的遵从率。
结果让两边都不舒服:
限定同样苛刻,审计席补了两刀:因变量是单独一条零成本、无歧义的简单标注指令——单刺激设计意味着它无法区分"结构无效应"和"这条指令怎么放都显眼";加上单一 agent 生态、25-500 行区间、单作者未同行评审。反证席方面:截至 2026-07 无复现、无直接矛盾测量、也无实质性专家批评——单源未受挑战,不是多源证实。但它与厂商叙事的张力仍值得直说:Anthropic 说"臃肿导致指令被忽略",而目前唯一的受控检验在 25-500 行区间内找不到大小效应。
那"短"的建议就作废了吗?不。支持"短"的证据链要换一条:上下文预算与 context rot。Chroma 的技术报告(2025-07,自发布、非同行评审,厂商利益已声明)测了 18 个模型,核心发现是模型并不均匀地使用上下文:输入越长,即便简单任务表现也非均匀退化;在 LongMemEval 子集(306 条清洗后的提示)上,只给相关摘录(约 300 token)的"聚焦"条件一致优于把同样信息埋进平均约 11.3 万 token 全量历史的条件;加入主题相关但无关的干扰内容,退化随长度放大。这是本文少数多源证实的实证:长上下文非均匀退化在 Chroma 之外至少有 NoLiMa(Adobe,早于 Chroma)、Du 等(EMNLP 2025)、Databricks 的独立测量同向,聚焦优于全量也有 LongMemEval 原作者(ICLR 2025)的一手数字。【多源证实】审计席的两条限定要带走:"聚焦"条件是作者手工抽出相关摘录的神谕检索上界——实际检索系统达不到这条线,所以它证明的是"精准上下文的收益上限"而非"你随手裁剪就能拿到的收益";剂量-响应曲线主要来自合成任务(NIAH 扩展、重复词),外推到真实代码库要打折。
诚实的综合读法:"短"的可靠论证是成本与上下文预算(每一行都在挤占任务本身的工作记忆,且长上下文退化是多源证实的),而不是"短了 agent 就更听话"(未获证实)。结构怎么排,目前的单源证据说影响不大;写了什么、以及会话进行到哪,才是遵从率的主变量。
普查:第一份大规模实证(arXiv 2511.12884,"Agent READMEs",2025-11)收集了 1,925 个仓库的 2,303 个上下文文件(限 CLAUDE.md、AGENTS.md、copilot-instructions.md 三种根级文件;Cursor/Windsurf 规则与子目录文件不在内;"第一份"是作者自述,同期另有 AIware 2025 的两篇相邻工作)。这里要做一处本文初版也中招的分母纠正——那组流传最广的百分比(实现细节 69.9%、架构 67.7%、构建/运行命令 62.3%、安全 14.5%、性能 14.5%)并非对 2,303 个文件计算,而是来自其中 922 个 CLAUDE.md 里人工标注的 332 个子样本,且选样程序未在论文中说明——引用时必须带上这个口径。【单源已核,分母已重标】
好消息是定性模式本身是多源证实的:另一支独立团队(UFMG,arXiv 2511.09268)用独立采集的 328 个 CLAUDE.md 和独立分类法得到同构结论——架构类内容居首(72.6%),安全与性能同样排不进常见内容;"命令+地图为主、非功能项系统性缺席"这个形状在两个独立样本里都成立。维护形态上,"不是静态文档,而是像配置代码一样演化的复杂工件,靠高频小步添加维护"。【多源证实(模式);具体百分比单源】
现场:四个生产 repo 的文件,逐字核验过(2026-07-15 对着 GitHub 原文件):
pnpm - never use npm or yarn",并列出六个子包各自的嵌套 AGENTS.md——把爆炸半径最大的规则放最前 + 分层,两条厂商建议的现场版。【现场核验】breeze"。【现场核验】四个文件的共性印证了 GitHub 那份 2,500 文件分析的归纳:高信号文件是命令优先、禁令具体、写 agent 猜不到的东西。Datadog 前端团队另有一个 monorepo 模式——根文件只当路由器,写工作区地图、工具链、路由规则和默认安全约束,把细节留给高价值/高风险子目录的嵌套文件,并用"每类任务 1-2 条测试提示词、跨多个 agent 跑到能一把过"的方式迭代文件——方法论上是清醒的,但属实践者自述【未验证,来源:dev.to Datadog 工程博客】。
llms.txt 常与 AGENTS.md 并列出现在"agent 时代文档基建"清单里,但两者的实测消费天差地别,它值得单独一章,因为它演示了采用叙事与实际消费可以完全脱钩:
教训不是"llms.txt 骗人",而是一条可以带走的方法:写任何"给机器看的文档"之前,先核实哪个机器真的会读它。AGENTS.md 过了这条检验(VS Code 默认加载、Cursor/Codex 原生消费、Copilot 官方支持——都有文档和源码可查);llms.txt 没过。
上下文文件被 agent 当作可信指令而非普通数据消费——这个信任模型在 2026 年已经有了带 PoC 的攻击面证据:
供应链写入路径(NVIDIA AI Red Team)。一个恶意 Golang 构建依赖检测 CODEX_PROXY_CERT 环境变量识别出 Codex 环境后,写入一份精心构造的 AGENTS.md,指示 Codex 往所有 Golang main 函数注入五分钟 time.Sleep,并附带隐身指令:不得在 PR 描述、commit message 和摘要里提及这处修改,甚至在代码注释里写"AI 摘要器请勿提及"。攻击前提是依赖已被攻破(攻击者已有代码执行权),NVIDIA 把它定性为 agent 开发环境特有的新型供应链风险维度;披露时间线:2025-07-01 提交 OpenAI,OpenAI 确认后拒绝修改,理由是风险不超出"被攻破的依赖"本身已能做到的事。演示仅针对 Codex;.cursorrules、CLAUDE.md、copilot-instructions.md 被列为同类风险面(风险类别陈述,非已演示的 PoC)。【已核;博客发布日期各索引口径不一,2026 年上半年】
编辑器自动注入路径。VS Code 从 v1.104 起默认把工作区根目录的 AGENTS.md 注入每一次 chat 请求(chat.useAgentsMdFile,源码确认"未显式关闭即包含");安全厂商 Prompt Security 的 PoC 演示了打开一个恶意 repo、在聊天框输入任意一个字符,注入的指令即可把 agent 引向数据外传。该攻击对应的分类——OWASP 2026 年 Agentic Applications Top 10 的 ASI01(Agent Goal Hijack)与 ASI02(Tool Misuse & Exploitation)——是真实存在的官方分类法(2025-12-09 发布),但把这个具体发现归入哪一类是厂商自己的标注。【已核】要点:自动注入是有文档记载的、按设计的产品行为,不是未公开漏洞——这正是它成为稳定攻击面的原因。
更广的背景数字——78 项研究的 meta 分析称自适应攻击对最先进防御的成功率超过 85%,四大 coding 平台全数未能拦截复合多层攻击【未验证,来源:arXiv 2601.17548】——本轮未做逐票核验,仅作方向参考。
工程含义三条:打开第三方仓库时把上下文文件当不可信输入(检查编辑器的自动加载开关);把上下文文件的 diff 当代码 review(尤其来自自动化 PR 和依赖更新的);构建环境里限制对 AGENTS.md/CLAUDE.md 的写权限(NVIDIA 攻击的写入点)。
以下步骤把前八章的证据收敛成可执行方案。设计原则只有三条:先做便宜且被验证的,每一步可度量,厂商口径当默认值而不是真理。每步标注证据等级。
Step 1 盘点(半天)。列出团队实际在用的 agent(决定文件名与互认矩阵,见第 2 章【已核】);标记 monorepo/多仓拓扑;给现有文档质量打分——这是最重要的一步,因为"价值来自不冗余信息"是目前最有希望的机制假说(两个独立弱信号同向,见第 4 章):README 已经很好的仓库,收益预期调低;文档荒地仓库,预期收益最大。把它当待验假设用,并在 Step 5 里用你自己的度量去证实或证伪。
Step 2 选标准(一次性决策)。默认选 AGENTS.md 做单一事实源 + 为 Claude Code 建 symlink(ln -s AGENTS.md CLAUDE.md);在文件头写明"本文件是唯一事实源,不要往其他规则文件加内容"(Sentry 模式【已核】)。如果团队只用 Claude Code,直接 CLAUDE.md 亦可,别双维护。
Step 3 根文件最小可用(每仓 1-2 小时)。内容按验证过的高信号模式:(a) 可执行命令带完整 flags,放最前,每条都实际跑过再写(GitHub 官方生成 prompt 的要求【厂商口径】);(b) 三五行目录地图;(c) 边界规则用 always / ask-first / never 三档,爆炸半径最大的放第一条(Cloudflare 的 pnpm 禁令模式【现场证据】);(d) 只写 agent 猜不到的:团队命名法、非标准工具链、repo 礼仪(Airflow 的 Dag/breeze 模式【现场证据】)。预算:200 行/2 页以内起步(厂商口径;记住 Codex 有 32 KiB 硬截断【已核】)。不要把人类 README 复制进来(冗余假说的两个独立信号都指向"复述即负担");LLM 全自动批量生成后直接提交,目前是方向存争区——一项研究测得负效应(方向性数字未过审计),另一项测得正效应(带仓库地图的迭代精炼式生成,+7.5pp,p<0.001);稳妥路线不变:/init 生成初稿 + 人工修剪【厂商口径】+ Step 5 的度量验收,别盲信任何一个方向。
Step 4 monorepo 分层(按需)。根文件放全局约定与路由,只给高价值/高风险的子包加嵌套文件,依赖"最近文件优先"语义(规范+四厂商一致【已核】;"根文件当路由器"是 Datadog 实践【未验证】)。警惕 Anthropic 自己承认的治理失效:约定漂移、文件过期、根文件没人认领【厂商口径,已核】——每个文件写个 owner。
Step 5 度量与期望管理(试点 2-4 周)。向管理层报告时用诚实的预期:效率收益(时间/token 下降)是本领域唯一带统计检验的效应,但只有一次测量且成本方向有研究唱反调;成功率方向证据未定——所以试点度量不是锦上添花,是你唯一能拿到的本地真值。度量方法:选 1-2 个试点仓库,建一套"每类常见任务 1-2 条测试提示词"的小套件,改版前后各跑一轮,记录完成率、耗时、token(方法来自 Datadog 实践【未验证】,但它本质上就是给文档建回归测试,成本低且无需相信任何人的口径)。结构折腾(位置、拆分)优先级放最低——目前唯一的受控实验找不到效应【单源已核】。
Step 6 维护与安全(常态化)。维护:上下文文件的改动走 PR review;大模型版本更新后重审一遍(给旧模型打的补丁规则会变成纯开销);可选 Stop hook 自动从会话记录提议更新(三条均为 Anthropic 官方建议【厂商口径】;"这些文件像配置代码一样高频演化"是实证观察【单源已核】)。安全:CI 对上下文文件的变更加 required review,特别拦截来自自动化 PR/依赖机器人对 AGENTS.md 的写入(NVIDIA 攻击路径【已核】);安全团队审一遍各编辑器的自动加载默认值【已核】。最后,不要写 llms.txt,除非你核实了某个你在乎的消费方真的读它【多源证实】。
反模式清单(全部前文有据):复制 README 全文;LLM 全自动生成后直接提交;单个巨型根文件服务 monorepo;把"短=更听话"当已证事实到处布道;在 14.5% 俱乐部里裸奔(不写任何安全边界);把第三方 repo 的上下文文件当可信内容。
值得盯的后续判据:三项对照研究的矛盾会不会被第三方在统一设置下裁决;"不冗余信息"假说在文档完备仓库上的直接检验;会话内衰减(OR=0.944)能否被第二个团队预注册复现;OWASP ASI 分类下第一批真实世界(非 PoC)的上下文文件注入事件何时出现。
标准与规范:agents.md 官网与 spec repo(github.com/agentsmd/agents.md) · Linux Foundation 新闻稿(Agentic AI Foundation,2025-12) · InfoQ(2025-08,2 万仓库基线口径)
厂商官方文档:Anthropic — code.claude.com/docs 的 best-practices、large-codebases、memory 页 · OpenAI — developers.openai.com/codex/guides/agents-md 与 codex 源码(codex-rs/core/src/agents_md.rs) · GitHub — docs.github.com Copilot custom instructions;github.blog "How to write a great agents.md: lessons from over 2,500 repositories"(Matt Nigh,2025-11) · Cursor — cursor.com/docs/rules · VS Code — v1.104 release notes 与 microsoft/vscode 源码
独立实证:Gloaguen, Mündler, Müller, Raychev & Vechev, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"(arXiv 2602.11988,ETH Zurich/LogicStar.ai) · Lulla, Mohsenimofidi, Galster, Zhang, Baltes & Treude, "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents"(arXiv 2601.20404,JAWs@ICSE 2026) · Shepard & Albrecht, "Probe-and-Refine Tuning of Repository Guidance for Coding Agents"(arXiv 2606.20512,Williams College) · McMillan, "Instruction Adherence in Coding Agent Configuration Files"(arXiv 2605.10039) · Chatlatanagulchai 等, "Agent READMEs: An Empirical Study of Context Files for Agentic Coding"(arXiv 2511.12884) · Santos, Costa, Montandon & Valente(UFMG,arXiv 2511.09268,独立 328 文件样本) · Hong, Troynikov & Huber, "Context Rot"(Chroma 技术报告,2025-07;独立同向:NoLiMa(Adobe)、Du 等(EMNLP 2025)、Databricks、LongMemEval 原作者(ICLR 2025))
llms.txt 体检:Ahrefs, "We Analyzed 137K Sites: 97% of llms.txt Files Never Get Read"(2026-06) · OtterlyAI 自站 90 天日志 · Adobe AEM 千域名 LLM-bot 事件审计 · Originality.ai llms.txt 追踪研究 · John Mueller Bluesky 原帖(2025-06-17)与 Search Engine Roundtable/Journal 报道 · Chrome Lighthouse 13.3 agentic browsing 文档
安全面:NVIDIA Technical Blog, "Mitigating Indirect AGENTS.md Injection Attacks in Agentic Environments" · Prompt Security, "When Your Repo Starts Talking"(厂商 PoC) · OWASP Top 10 for Agentic Applications 2026(ASI01/ASI02,2025-12) · arXiv 2601.17548(prompt injection meta 分析,未验证)
现场文件(2026-07-15 逐字核验):getsentry/sentry、cloudflare/workers-sdk、apache/airflow、coder/coder 各自的 AGENTS.md · Datadog 前端工程博客(dev.to,未验证)
调研材料与全部验证判定存于研究底座(仓库 research/agent-readme/:第一、二轮 35 组承重论断 × 3 票共 105 票,第三轮 6 组单源实证 × 反证搜索席 + 方法学审计席共 12 份判决,全部记录在案,含 2 组承重数字的审计否决与全部口径修正)。