AGENTS.md 是什么简单说它是给 AI 编码代理看的“项目说明文件”。很多人第一次听到这个名字会误以为它只是 README 的另一个名字但其实目标完全不同README 面向人类开发者讲的是项目是什么、怎么用AGENTS.md 面向 AI讲的是这个仓库怎么构建、怎么测试、哪些文件不能动、遇到什么情况应该怎么处理。最近 Hacker News 上有一个问题很值得关注“有没有人试过最小化的 AGENTS.md让它随着你的仓库一起成长”这个问题的核心不是教你怎么写一份完美的规范而是给出一个更务实的思路不要一上来就写几百行的约束文件而是从最小可用版本开始跑出问题再补让 AGENTS.md 跟着仓库的真实需求一起长大。这个思路对长期维护仓库的人来说非常实用。AI 编码代理的上下文长度是有限的如果 AGENTS.md 一开始就塞满抽象规则AI 很容易抓不住重点反而忽略了真正影响构建和测试的命令。更常见的情况是项目刚起步时你根本不知道哪些规则值得写进去只有踩过坑才知道。所以“最小化起步 渐进式补充”不是偷懒而是让 AGENTS.md 保持可执行、高信噪比的一种工程策略。这篇文章会从 AGENTS.md 是什么开始讲清楚最小文件怎么写、怎么接入仓库、怎么验证 AI 是否真的读到并遵守了、怎么在批量任务和多 Agent 场景下复用同一套规范最后给出常见的坑和排查方法。先给结论AGENTS.md 值得写而且应该从小写起。它能解决的问题非常明确——让 AI 编码代理少犯方向性错误、少改不该改的文件、少在构建和测试上反复猜它本身没有任何硬件要求就是一个 Markdown 文件成本极低。下面我们就按照“先最小化、再演进”的思路把 AGENTS.md 的落地方法完整过一遍。1. 什么是 AGENTS.md为什么 AI 编码代理需要它AGENTS.md 是放在仓库根目录或关键子目录下的一个 Markdown 文件专门给 AI 编码代理读取。它里面的内容不是“项目介绍”而是“在这里工作的规则”。例如这个项目用什么命令装依赖、用什么命令跑测试、代码风格有没有硬性要求、有没有绝对不能改的自动生成文件、新增一个功能时应该按什么流程来。这些信息如果放在 README 里AI 也能看到但 README 往往太长、太面向用户AI 很难快速提取出“当前任务相关的约束”。从实际效果看AI 编码代理的常见问题不是不会写代码而是不了解上下文。它读到一段代码往往不知道这个函数是手写的还是生成的不知道测试框架是 pytest 还是 unittest不知道改动某个文件会不会影响其他模块。如果没有一份明确的规则文件AI 通常会给出“看似合理但方向错误”的方案。AGENTS.md 的作用就是把人类项目维护者脑子里那些默认知识显式化让 AI 在动手前先对齐约束。为什么需要“最小化”因为 AI 编码代理在读取文件时会把 AGENTS.md 的内容当作上下文。文件越长越容易稀释关键信息。很多团队第一次写 AGENTS.md 时容易用力过猛把所有团队规范、编码风格、历史决策都塞进去结果 AI 读完还是一头雾水。最小化的意思是只保留“当前仓库环境下AI 必须知道才能正确做事”的信息。等 AI 真的犯错、或者人类发现它反复漏掉某个约束时再往 AGENTS.md 里补一条规则。这样文件始终和真实问题绑定不会变成没人维护的僵尸文档。一句话总结AGENTS.md 是给 AI 的“岗位手册”最小化是让这份手册始终有重点。2. AGENTS.md 核心能力速览在开始写之前先用一张表把 AGENTS.md 的关键特征说清楚。这张表适合任何一个准备在仓库里引入 AGENTS.md 的团队。能力项说明文件类型Markdown一般放在仓库根目录也可按目录拆分目标读者AI 编码代理如 Copilot、ChatGPT、Claude 等工具侧的代码代理和 README 的区别README 面向人类用户AGENTS.md 面向 AI 编码代理核心价值减少 AI 在构建、测试、文件约束、任务流程上的猜测最小起步成本一个 20 到 50 行的 MD 文件不需要额外工具维护方式根据真实踩坑记录渐进式补充是否需要硬件不需要纯文本文件是否支持批量任务可以作为多 Agent / 批量修复任务统一规范是否有 API 接口本身不是服务但可以作为 AI Agent 的输入上下文适用场景中大型代码仓库、多人协作、AI 辅助开发频率高的项目不适合场景一次性脚本、纯文档项目、没有 AI 工具的仓库从这张表能看出AGENTS.md 的核心不在“格式”而在“可执行性”。它不要求你懂什么框架也不需要维护单独的服务端你只需要把它当成一份不断更新的工作约定放进仓库即可。很多团队在第一次尝试时会问“AGENTS.md 怎么写才算标准”其实没有统一标准真正有效的方法是让它跟着项目痛点走。3. 最小化 AGENTS.md 的起点先写什么不写什么3.1 最小文件示例先给一个可以直接复制的最小化模板。这个模板的核心思想是只包含 AI 在仓库里完成任务时必须知道的三类信息——项目是干什么的、常用命令是什么、有什么硬性规则。# AGENTS.md ## 项目简介 这是一个订单处理 API 服务使用 FastAPI 框架。 ## 常用命令 - 安装依赖pip install -r requirements.txt - 运行单元测试pytest tests/ - 启动开发服务python app.py ## 硬性规则 - 不要修改 database/migrations/ 下的自动生成文件。 - 新增接口时必须补充鉴权逻辑。 - 提交代码前必须通过 pytest tests/。这份文件大约 20 行但已经覆盖了 AI 最常出错的三个场景依赖装不对、测试跑错、改了不该改的文件。对于一个刚开始接入 AI 编码代理的仓库这个量级足够了。3.2 先写什么写“AI 不知道就容易犯错”的信息优先级从高到低是构建和安装命令。AI 如果不知道依赖怎么装可能使用错误的包管理器。测试命令。AI 如果不知道测试框架和入口可能拿 README 里的示例当验证方式。文件禁区。哪些文件是生成文件、哪些目录承载核心业务逻辑、哪些文件改动风险极高必须写清楚。编码约束中“硬性”的部分。比如必须使用类型标注、必须写测试、接口必须做参数校验。当前任务的工作流。如果仓库有固定的开发流程比如“先加测试再改代码”可以写进去。3.3 不写什么最小化阶段以下内容尽量不要写不适合写泛泛的团队价值观比如“代码质量要高”“命名要清晰”AI 无法执行只会占上下文。不适合写已经由 lint 规则或 CI 检查强制保证的格式规范除非这些规则需要 AI 在生成代码时提前遵守。不适合写与当前仓库无关的通用编程建议AI 已经知道了。不适合写大型设计文档AGENTS.md 不是来替代 architecture docs 的。记住一个判断标准如果 AI 不看这句话就会犯错那就写如果 AI 不看也不会影响输出那就删掉。4. 把 AGENTS.md 接入现有仓库的正确姿势4.1 新建文件接入方式非常简单在仓库根目录新建一个名为AGENTS.md的文件把上面的最小模板复制进去根据实际情况修改 “常用命令” 和 “硬性规则”。# 在仓库根目录创建文件 touch AGENTS.md编辑完成后提交到仓库。文件命名需要注意目前大多数 AI 编码代理工具优先读取根目录的AGENTS.md也有些工具支持AGENTS.md在子目录中作为局部规则。如果你的工具不识别可以换用项目文档中约定的其他文件名。这一点需要在具体工具的能力范围内确认不要假设所有工具都自动加载。4.2 和现有文档的关系AGENTS.md 不应该替代 README也不应该和 CONTRIBUTING.md 重复。建议的职责划分是README面向使用者讲项目功能、安装方式、调用示例。CONTRIBUTING.md面向贡献者讲 PR 流程、分支规范、代码评审要求。AGENTS.md面向 AI 编码代理讲构建命令、测试命令、不可改动的文件、任务完成标准。如果同一规则在 CONTRIBUTING.md 里已经有可以在 AGENTS.md 里写一句“贡献规范见 CONTRIBUTING.md尤其是第 2 节”避免把整份内容复制过来。4.3 版本管理和团队评审AGENTS.md 和代码一样需要走版本管理。每一次补充规则都应该能追溯原因。推荐的做法是当你在代码评审中发现 AI 反复犯同一个错误时去补充一条规则并在 commit message 里写清楚是“针对什么问题新增”。例如docs(agents): 新增禁止修改 schema 迁移文件的规则这样后续维护者能知道这条规则的来源也可以在规则不再适用时及时清理。5. 让 AGENTS.md 随仓库成长的演进方法“最小化 AGENTS.md”并不是说它永远只有 20 行而是指它应该像代码一样根据真实需求增长。如果项目复杂度上升、AI 编码代理开始频繁出现在多个目录、或者在代码评审中发现了更复杂的坑就可以考虑扩充分块。5.1 按目录拆分仓库很大时根目录的 AGENTS.md 不要所有细节都管。常见做法是在关键子目录放一个局部 AGENTS.md。比如repo-root/ ├── AGENTS.md ├── backend/ │ ├── AGENTS.md │ └── app.py └── frontend/ ├── AGENTS.md └── src/根目录 AGENTS.md 只写全局命令和通用规则子目录 AGENTS.md 写这个目录特有的内容。这样做的好处是 AI 在进入特定目录时能读到更贴近上下文的规则不会因为根目录文件太长而忽略。5.2 基于真实踩坑记录补充规则最有效的演进方式是从“AI 的错误”中学习。比如你发现 AI 在修复一个 bug 时直接格式化了整个文件导致 diff 里出现大量无关改动。这时就可以在 AGENTS.md 里加一条- 修复 bug 时只修改与本次问题相关的代码不要格式化整个文件。再比如 AI 总在提交时漏掉新增加的配置文件可以加- 提交前检查是否有新增的配置文件需要纳入版本管理。这种规则虽然看起来简单但比“请保持代码整洁”有用得多因为它是和具体错误绑定的AI 能明确执行。5.3 定期清理AGENTS.md 也会过期。项目换框架了、迁移脚本不再自动生成、某个硬性规则已经变成 CI 检查的一部分这些内容就应该从 AGENTS.md 里移除。建议每季度做一次“文件瘦身”把超过 10 行且和当前任务无关的段落删掉或者移到更合适的文档里。一个好的信号是如果 AGENTS.md 里某条规则超过一个月没有被任何代码评审提到你就要思考它是否真的重要。如果只是“看起来对”但没有实际效果删除它不会造成损失。6. 功能测试与效果验证怎么确认 AI 真的读了 AGENTS.md写完 AGENTS.md 之后必须验证它到底有没有用。很多团队写完后发现 AI 依然我行我素原因往往是文件没有被 AI 读取或者文件内容太模糊导致 AI 没有执行。下面给出一套通用验证流程。6.1 让 AI 复述规则最简单的测试在聊天窗口中把 AGENTS.md 内容粘贴给 AI或者直接让 AI 阅读仓库中的 AGENTS.md然后提问请阅读仓库根目录的 AGENTS.md总结出 3 条你在修改代码时必须遵守的规则。如果 AI 能准确复述出构建命令、测试命令和禁区文件说明文件被读取了如果回答很泛说明文件内容写得太模糊需要调整。6.2 构造验证任务让 AI 完成一个包含“禁区文件”的小任务。比如在最小化模板中写了“不要修改 database/migrations/ 下的文件”可以给 AI 一个任务“修复某个业务逻辑 bug”然后在方案里故意诱导它去改动迁移文件。正确的行为应该是 AI 自己识别出禁区并拒绝修改或者至少给出警告。如果 AI 直接改了说明 AGENTS.md 里的规则没有起到作用。任务订单状态更新后数据库表结构需要调整。请修复这个 bug。如果 AI 的回答中包含修改 migration 文件说明规则被忽视了。这时候需要检查文件的措辞把规则写得更明确比如“数据库迁移目录下的所有文件都是自动生成的任何情况下都不要手动修改”。6.3 观察 AI 提交代码时的行为让 AI 生成一个 PR 或 patch然后看它的 diff 是否符合 AGENTS.md 中的约束。重点观察是否修改了禁区文件。是否补充了测试。是否运行了指定的测试命令。如果 AI 经常不遵守规则可以增加一条“完成标准”## 完成标准 - 所有新增功能必须有对应测试。 - 修改完代码后运行 pytest tests/ 并确保通过。这段内容放在 AGENTS.md 里比口头提醒有效得多因为 AI 会在每个任务结束时重新读一遍。6.4 记录验证结果建议维护一个简单的验证清单每次给 AGENTS.md 增加新规则时都跑一次上面的测试。验证结果可以记在 commit message 里也可以单独用一个 checkbox 列表- [ ] AI 能复述最新规则 - [ ] AI 不违反新增禁区 - [ ] 新增规则在真实任务中有效只要验证通过规则才保留否则继续调整措辞。7. 多 Agent 与批量任务场景统一规范怎么落地AGENTS.md 不只是单个 AI 对话框的说明书在多 Agent、批量代码审查、批量修复 bug 的场景下它是保证一致性的关键。7.1 多 Agent 并行开发当多个 AI Agent 同时修改同一个仓库时如果没有统一规范很可能出现一个 Agent 改了公共函数签名另一个 Agent 还在用旧签名最终产生大量冲突。AGENTS.md 里的“硬性规则”此时就是并行的前提。可以在根目录 AGENTS.md 里增加一块“公共模块变更规则”## 公共模块变更规则 - 修改 utils/ 下的公共函数时必须同步更新所有调用方。 - 新增公共函数时必须添加单元测试。这样每个 Agent 在发起修改前都会先读到相同约束减少相互之间的无意识破坏。7.2 批量代码审查与批量修复批量任务的典型场景是用 AI 扫描整个仓库找出所有潜在 bug 并生成修复建议。如果没有 AGENTS.mdAI 输出的修复方案风格会非常不稳定可能有的修复直接跳过测试有的修复擅自重构。此时 AGENTS.md 里的“完成标准”和“提交约束”会直接作用到批量任务上。可以单独维护一份AGENTS.tasks.md示例文件名用来描述批量修复的输入输出规范# AGENTS.tasks.md ## 任务输入 - 扫描目录src/ - 输出目录reports/ ## 修复要求 - 每个问题单独生成一个修复建议文件。 - 必须附上复现步骤和测试用例。 - 不允许修改 database/migrations/。在批量任务脚本中把这份文件作为上下文传给 AI Agent能让结果的一致性明显提升。7.3 多仓库统一规范如果团队有多个仓库建议维护一份“根规范”再通过符号链接或复制到每个仓库。根规范里只写通用规则各仓库再补充自己的特殊命令。例如根规范可以叫AGENTS.base.md# AGENTS.base.md ## 通用规则 - 所有代码提交前必须通过测试。 - 禁止将密钥写入代码仓库。 - 修改依赖前先更新 lock 文件。仓库根目录的 AGENTS.md 里写“继承 AGENTS.base.md”然后加本仓库特有内容。这种分层设计能避免在多个仓库里重复维护同一批规则。8. 信息密度与维护成本避免 AGENTS.md 变成第二个 READMEAGENTS.md 最大的风险不是没有而是写得太多、太宽泛最后变成一份没人看的“规范文档”。前面反复强调“最小化”其实是把它当成一种会持续消耗注意力的运行时配置来管理。在这个维度上它和代码的复杂度一样需要控制。观察维护成本主要有三个角度第一个角度是长度。一份超过 200 行的 AGENTS.mdAI 读取时必然会消耗更多上下文 token同时也会让关键规则被淹没。建议根目录文件控制在 80 行以内超出部分优先考虑拆分到子目录或单独的说明文档。第二个角度是规则的可验证性。好的 AGENTS.md 规则应该能回答“这条规则执行了吗”。比如“代码质量要高”不可验证而“提交前必须运行pytest tests/”可以验证。每次新增规则时都要问自己AI 完成任务后我能用一条命令或一个 diff 确认它遵守了吗如果不能这条规则大概率是无效的。第三个角度是变更频率。AGENTS.md 的每一次变更都代表一个真实的坑或者一个新的协作方式它不是写作文不需要频繁修改。如果它每两天就有大量改动说明项目本身的流程还未稳定此时应该先把稳定下来再逐步沉淀规则。真正的健康状态是文件偶尔增加一行但大部分内容长期不变。9. 常见问题与排查方法在实际落地时你会遇到一些很常见的问题下面用表格给出一套排查思路。问题现象可能原因排查方式解决方案AI 没有读取 AGENTS.md文件名不在工具支持列表里查看工具的文档确认读取规则改名或调整位置或把内容放到工具指定的配置文件中AI 读取了但行为没变化规则写得过于模糊AI 无法执行让 AI 复述规则观察能否具体化改成“可验证”的规则例如指定命令和文件路径AGENTS.md 越写越长AI 开始忽略信息过载关键规则被淹没统计规则被实际遵守的比例拆分到子目录清理过期规则同一个规则在不同任务中表现不一致规则在文件中的位置不统一确认规则是否被 AI 稳定读取把关键规则放在文件前 10 行并重复强调修改 AGENTS.md 后出现新的构建问题规则和当前项目状态脱节检查规则是否基于旧目录结构及时更新命令路径跑一遍完整命令AI 批量任务结果冲突多个 Agent 使用了不同的上下文检查每个 Agent 读到的 AGENTS.md 是否一致统一使用根目录规范避免局部文件覆盖全局规则团队没人愿意维护 AGENTS.md文件变成形式化产物检查是否有协作价值改成从实际踩坑中沉淀规则减少无效内容规则修改后无人知道缺少变更评审观察 commit message 和 PR 讨论让 AGENTS.md 的修改走代码评审流程这些问题大多不是技术上的难题而是习惯和流程问题。一旦把 AGENTS.md 当成“代码之外的运行时配置”它就会自然地进入评审、测试、更新、清理的循环。10. 最佳实践与团队协作建议最后总结几条可以直接上手的建议第一第一次不追求完整。先放一份 20 行的最小 AGENTS.md包含项目简介、常用命令、硬性规则就能覆盖大多数 AI 编码代理的常见错误。不要一开始就参考那些几百行的大规范那会导致维护成本陡增。第二把 AGENTS.md 的修改当成代码评审的一部分。任何对规则的修改都应该说明原因、影响范围、验证方式。这样能避免文件毫无控制地膨胀。第三用真实错误推动规则补充。每次发现 AI 犯了一个可重复的错误就让它成为一条新的规则。补充规则后马上验证一次看 AI 是否不再犯。如果有效保留如果无效继续改命令或措辞。第四保持根目录文件的短小。根目录 AGENTS.md 只负责全局约束其他细节放到子目录或独立文档。想让 AI 稳定执行就要让它能在最短时间内抓住重点。第五批量任务和多 Agent 场景下AGENTS.md 是统一规范的核心。在任务开始前先确认每个 Agent 都读取了同一份文件在任务结束后用 diff 和测试结果来检查规则是否被遵守。第六涉及隐私、安全、版权敏感信息时AGENTS.md 本身也要注意边界。不要把密钥、内网地址、敏感数据写进仓库文件涉及人脸、声音、版权素材的代码项目更要在规则中明确“未经授权不得处理”的边界。AI 编码代理的运行环境同样需要遵循这些合规要求。如果你准备在下一个仓库里试一下 AGENTS.md建议先只放一个最小版本跑一两周真实任务再决定要不要加内容。这样 AGENTS.md 才能真正成为仓库的一部分而不是一份无人阅读的文档。