跳到主要内容

AGENTS.md 作为通用标准

· 阅读需 12 分钟
José Villaseñor Montfort
Strange Days Tech

项目的第一份 AIDEC —— "AI 智能体是同一个技术受众" —— 与把它落地的开放标准之间相隔四个月。AGENTS.md 放在仓库根目录，被十五个不同厂商的 CLI 读取，替代了 CLAUDE.md / GEMINI.md / .cursorrules 以及十几个其他文件的扩散。

1. 直觉与标准之间的四个月​

2026 年 5 月 15 日，UTC 时间 19:05，PR #155 以 fw-4.15.0 / cli-3.13.2 的形式合入框架。它带来的是一个新文件，加入了 CLI 注入的指令列表：AGENTS.md，位于采用者仓库的根目录，与已有的文件并列（CLAUDE.md、GEMINI.md、.github/copilot-instructions.md、.cursorrules、.cursor/rules/straymark.md）。

这本来可以是一件微不足道的事，但恰好在四个月前的 2026 年 1 月 27 日，项目的第一份 AIDEC —— 第 2 篇文章中以"年份笔误"为切入点讲述的那份 —— 曾宣示：

"AI 智能体（Claude、Gemini、Copilot、Cursor）能同等流畅地处理任何语言的指令，因此翻译它们的配置文件不会带来功能上的收益。"

这句话写于项目初始提交六小时后，包含着框架此后不断付诸实践的一个直觉：智能体是同一个技术受众。配置文件（CLAUDE.md 等）保持英文（而人类文档被翻译成三种语言），原因在于"AI 智能体"这一受众并不从翻译中获益。若要把这个直觉彻底落地，所缺的只是给它一个单一的指向——而无需为每个不同厂商各复制一遍文件。

本文正是围绕这件事展开：AGENTS.md —— 一个于 2025 年 12 月捐赠给 Agentic AI Foundation 的开放标准 —— 如何在四个月后完成了第一份 AIDEC 于 1 月所开启的那个决策。

2. AGENTS.md 所解决的碎片化问题​

2024 年至 2026 年间，随着 AI 智能体 CLI 的大量涌现，每家厂商都另起炉灶，发明了自己的指令文件格式：

  • Anthropic 随第一版 Claude Code 发布了 CLAUDE.md。
  • Google 为 Gemini CLI 采用了 GEMINI.md。
  • GitHub 为 Copilot CLI 确立了 .github/copilot-instructions.md。
  • Cursor 以 .cursorrules 起步，后来迁移到 .cursor/rules/*.md。
  • OpenAI 的 Codex CLI 使用另一套路径；Aider、Devin、Continue、Roo Code、Factory Droids、Sourcegraph Amp、Zed AI、Windsurf、Amazon Q 各有各的方式。

一个同时使用两三个 CLI 的 StrayMark 采用者，不得不维护两三份内容相同的副本，靠手工同步，祈祷它们不要彼此偏离。在 fw-4.14.x 之前，框架的 straymark init 命令承认了这种碎片化现实：它向最常见的五个特定于厂商的文件注入内容。但其余十到十五个 CLI 则被排除在外，采用者只能靠手工复制内容来处理它们。

2025 年底，生产智能体 CLI 的开源项目社区做出了碎片化代价高昂时常见的选择：就标准达成一致。AGENTS.md 置于仓库根目录，所有人都读取它。将其捐赠给 Agentic AI Foundation（Linux Foundation，2025 年 12 月）赋予了它机构层面的治理。规范刻意保持极简：一个 Markdown 文件，不强制任何模式，位置可预测。每个 CLI 如何处理这个文件是其自己的事；那个核心问题——"这个仓库的智能体配置在哪里？"——现在有了唯一的答案。

到 2026 年 5 月，读取 AGENTS.md 的 CLI 列表包括（直接引用 PR #155 正文）：

"Claude Code、OpenAI Codex CLI、Cursor、Aider、Devin、Sourcegraph Amp、Google Jules、Zed AI、Continue、Roo Code、Factory Droids、GitHub Copilot、Gemini CLI、Windsurf、Amazon Q 及其他。"

十五个 CLI。其中一些出于历史兼容性仍然同时读取各自特定于厂商的文件。但全部十五个都知道优先查找 AGENTS.md。

3. 采纳，而不消灭自己的格式​

fw-4.15.0 最有趣的决策不是采纳 AGENTS.md；一旦标准达到临界质量，那是必然之举。有趣的是如何采纳。PR 正文毫无含糊地表述了这一点：

"与 CLAUDE.md / GEMINI.md 并列：标记块指向 STRAYMARK.md，其下附有最小可行正文，供无法跟随相对链接的读者使用。"

三个关键词：并列、标记块、最小可行正文。

并列意味着 AGENTS.md 不替换特定于厂商的文件，而是共存。框架仍然注入 CLAUDE.md、GEMINI.md、.cursorrules 等文件。理由很务实：某些 CLI（尤其是旧版 Cursor）要求将完整内容内嵌，而非通过相对链接指向。保留兄弟文件维持了这种兼容性，无需每个采用者为自己特定的 CLI 单独费心。

标记块是框架在其他特定于厂商的文件中已使用的惯例：一个 HTML 注释块，夹在 <!-- straymark:begin --> 与 <!-- straymark:end --> 之间，将 STRAYMARK.md 指向为真实来源。每次 straymark update-framework 只替换标记之间的内容。采用者在标记之外写入的内容——例如项目专属指令——保持完整。框架尊重采用者的文件；它只治理自己的那一节。

最小可行正文是对不跟随相对链接的 CLI 的妥协。标记块之下，AGENTS.md 携带一段简短正文，包含要素：智能体身份、审查要求、提交前检查清单、监管前置元数据片段、NIST AI 600-1 风险分类、可观测性规则、命名规范。对于无法读取 STRAYMARK.md 的智能体而言，这已足以正常运作；但它不足以替代规范文档。这种不对称是刻意为之的：我们希望智能体主动去打开 STRAYMARK.md。

CLI 的防御性细节（cli/src/commands/remove.rs:13）封堵了操作层面的漏洞：AGENTS.md 被加入了 LEGACY_DIRECTIVE_TARGETS。如果采用者丢失了 .straymark/dist-manifest.yml 并运行 straymark remove，旧版回退逻辑也会清理 AGENTS.md，而不是留下孤立文件。这是枯燥的日常维护，但正是这种差别决定了一个框架能否彻底卸载，还是留下残骸。

4. 没有 ADR​

有一个缺席值得点名。采纳 AGENTS.md 的决策没有获得自己的 ADR。

这与第 6 篇文章中 StrayMark 品牌重塑形成刻意对比——那次有公开的 ADR-2026-05-08-001，包含三个评估过的替代方案和列举的后果。它也与第 12 篇文章中 Phase 2 的情形不同，那次有一份包含架构论证的详尽 CHANGELOG 条目。fw-4.15.0 的文档论证只有 PR 正文——一篇好的正文，论点清晰，但不是 ADR。

为什么？操作层面的答案：这个决策被认为是附加性的，而非结构性的。采纳一个与现有格式共存的开放标准，并不改变框架的模型，只是扩展了它。没有哪个被否定的替代方案需要正式论证：不采纳 AGENTS.md 意味着出于审美偏好将十五个 CLI 排除在外，而没有人持有这个论点。

但这里有一个值得记录的教训。博客已经见过这种模式——Phase 2 关闭了一个经验闭环，品牌重塑改变了身份，第 10 篇文章的元模式命名了已然存在的东西——每次那个问题*"这值得写一份 ADR 吗？"*的答案都不同。框架似乎在不明言的情况下采纳了这样一条操作规则：当决策关闭了代价高昂的替代方案、并留下了那些未被选择之方案的记录时，ADR 才是必要的。fw-4.15.0 并未关闭代价高昂的替代方案——它只是增加了一个层次。所以 PR 已经足够。

我在这里将其记录在案，因为值得承认：并非每项变更都值得一份 ADR，也并非每个 PR 都是历史文献。存档纪律有其自身的标准。

5. 智能体可见性的两个层次​

fw-4.15.0 发布十天前的 5 月 9 日，Issue #113 被关闭——第 5 篇文章将这段插曲记录为*"对智能体不可见的 Charter"*。当时，操作者与一个能力出众、专注认真的智能体合作了六小时，规范的入门装置已全部加载，但智能体从未提议使用 Charter。那篇文章的结论：结构性可见性是框架的责任，而非智能体的属性。

fw-4.15.0 涵盖了同一问题的另一面。

第 5 篇文章关注的是内部结构可见性：如何确保已在读取我们仓库的智能体发现框架的核心概念。PR #122（第 5 篇）的答案是在 Charter 作为概念出现的内部表面上做乘法：STRAYMARK.md §15、CLAUDE.md/GEMINI.md 指令、/straymark-* 技能、status 输出、模板、通往 SpecKit 的桥接。九个内部表面。

本文关注的是外部结构可见性：如何确保任何进入仓库的智能体——无论其厂商——都能找到框架的装置。fw-4.15.0 的答案是采纳社区选定的规范接入点。一个外部表面，被十五个厂商读取。

两个层次共享同一概念轴——一个技术制品只有在表面命名它时才对智能体存在——但各有不同的作用域。内部可见性保证智能体在读取 STRAYMARK.md 时看到 Charter。外部可见性保证智能体进入仓库时看到 STRAYMARK.md，无论是哪个 CLI 在编排它。缺少任何一个层次都是不完整的。

6. 运行 update-framework 时采用者的操作​

发布的操作部分，直接引用 CHANGELOG：

"straymark update-framework 会带来新模板并在项目根目录注入 AGENTS.md。注入遵循与所有其他指令目标相同的规则：若文件不存在则创建，后续运行时替换标记块；若文件已存在但没有 StrayMark 标记则安全追加（这在 2026 年非常普遍——许多采用者已经手工维护着自己的 AGENTS.md）。"

三种重要行为：

  1. 若文件不存在，CLI 使用规范模板创建它。
  2. 若文件已存在且带有 StrayMark 标记，CLI 只替换标记之间的内容。
  3. 若文件已存在但没有标记——2026 年非常普遍，因为许多采用者已经在手工编写自己的 AGENTS.md——CLI 会在文件末尾追加其标记，不触碰采用者已写入的内容。

这与博客在第 3 和第 6 篇中记录的存档尊重原则相同：框架治理它自己的那一节，而非整个文件。如果采用者想在其 AGENTS.md 中编写项目专属指令——内部政策、命名规范、特定代码库的专属指令——这些指令在每次 update 时都保持完整。StrayMark 块存在于它那个小小的标记边界之内，更新也在那个边界之内进行。

CHANGELOG 说明以一条值得记录的小操作警告作结："如果你的 .gitignore 排除了 AGENTS.md，请在运行 update-framework 之前调整，以确保注入内容能进入版本控制。" 这是对框架自身无法解决的边界情况的坦诚——采用者选择忽略该文件是其主权，而非错误。

7. 结语​

我从这个过程中提炼出四点：

  1. 直觉与落地之间四个月的周期，正是把一个闭环做好所需要的时间。 1 月的 AIDEC 携带着直觉——"智能体是同一个受众"。fw-4.15.0 用一个开放标准将其关闭。两者之间，框架在特定于厂商的原型上持续迭代，直到通用替代方案出现。早期的直觉是对的；时间线是生态系统成熟所必需的。

  2. 采纳开放标准不需要放弃自己的格式。 AGENTS.md 与 CLAUDE.md、GEMINI.md、.cursorrules 共存。这个决策不是"一个替换其他"，而是"当它有所贡献时，一个加入其他"。框架获得了外部可见性，同时保留了对需要特定格式的 CLI 的兼容性。

  3. 并非每项变更都值得一份 ADR。 StrayMark 品牌重塑关闭了代价高昂的替代方案，并留下了被舍弃方案的正式记录。fw-4.15.0 只是增加了一个通用层：任何 ADR 都不会丰富这个决策。存档纪律有其操作标准，而非教条。

  4. 智能体的可见性在两个层次上运作。 内部层次（第 5 篇，fw-4.12.0）确保智能体在读取仓库时看到框架的概念。外部层次（fw-4.15.0）确保智能体无论由哪个 CLI 编排，都能从正确的门进入仓库。缺少其中任何一个，要么是有能力的智能体在沉默中读取，要么是迷失方向的智能体找不到入口。

参考锚点：PR #155 — fw-4.15.0 / cli-3.13.2（合并于 2026-05-15 19:05 UTC）。原始 AIDEC（第 2 篇）：.chronicle/07-ai-audit/decisions/AIDEC-2025-01-27-001-i18n-strategy.md（提交 7b7193e，含年份笔误的 ID）。注入模板：dist/dist-templates/directives/AGENTS.md。标准规范：agents.md —— 捐赠给 Agentic AI Foundation（Linux Foundation），2025 年 12 月。

本文档在生成式 AI 工具（Claude 4.7）的协助下撰写；内容的全部责任由人类作者承担。