8.0
热点
AI SCORE
编程提效2026-08-13 03:14
480个真实AGENTS.md分析：AI指令文件的实际写法
dev.to · AI#AI编程#Agent#开源
Editor brief · 编辑速览
分析了272个生产项目的AGENTS.md/CLAUDE.md文件，发现60%含禁止性指令，中位数仅60行；揭示了regex误匹配markdown表格的调试教训。
从 272 个生产仓库（React、Grafana、LangChain、Home Assistant 以及其他 268 个）中，逐一提取了真实的 AGENTS.md / CLAUDE.md 文件——这些是 Claude Code、Copilot 等编程 Agent 在操作仓库前会读取的指令文件。不是链接列表，而是实际文件，在许可证允许的范围内完整存储，可在一个目录树下搜索。
仓库地址：https://github.com/sattva2020/agents-md-in-the-wild
明确的禁止条款（"never"、"do not"）出现在 60% 的文件中，比构建指令（38%）更常见。
在赋予 AI Agent 仓库完整权限的文件中，只有 23% 提到了 secrets。
中位数文件只有 60 行，远短于大多数建议帖的暗示。
一次分析尝试检测字面的目录树图，即使用制表符或 ASCII 分支标记的那种。第一版很 naive：看一行中是否有树形字符，统计匹配数。在整个语料库上运行后，得到 69% 的文件"包含目录映射"。这感觉太高了——指令文件中的目录树是一个具体的、有意的东西，不是七成的项目都会写的。
原来正则表达式匹配了 markdown 表格。像 | src/ | entry point | 这样的行，左边有管道符号和路径形状的东西，而我的"行看起来像树分支"检查并不关心第一个斜杠后面是什么。修复：要求 3 行或更多连续的树形行，并在计数前明确拒绝解析为表格行的行。数字从 69% 降到了 17%，与手动抽查相符。
"提及 secrets"的启发式方法也遇到了同样的故事。第一版匹配裸的"token"，结果发现捕获到的是谈论 LLM context-window tokens 的文件，而不是 API tokens。不得不收紧模式，要求附近有"api"、"access"或类似的词。
教训，重复两次：一个对你来说看起来很具体的关键字或模式，一旦在真实文本上规模化运行，它很少像看起来那么具体。480 个文件足以暴露这两个 bug，我怀疑在我最初测试的 5-10 个例子中，这两个都不会出现。
存储按 SPDX 许可证分层：在约 26 个可重新分发的许可证（MIT、Apache-2.0、BSD 变体、GPL/LGPL/AGPL、CC0 等）的许可列表下的文件，完整存储并附带来源信息。其他所有内容，包括没有声明许可证的仓库，仅存储元数据：标题和结构，没有正文。默认是"保留所有权利"，除非许可证另有说明；未许可的文件仍计入结构分析，只是不会重新分发其文本。
它打算通过 GitHub Action 每周刷新，完整披露，目前卡在我的 GitHub 账户的计费问题上，所以在此之前请将"每周"视为努力目标。
真的很想知道遗漏了什么，或者是否有值得添加的模式信号。仓库地址：https://github.com/sattva2020/agents-md-in-the-wild