最近半年我在好几个仓库里都加入了AGENTS.md效果比我预想中直接AI 编码代理终于不再一边改代码一边反复问我“这个项目怎么跑起来”“测试命令是哪个”这类基础问题。如果你也在用 Claude Code、Codex 这类工具现在确实该把AGENTS.md当成项目的基础设施来对待而不是可有可无的说明文件。这篇文章是我从零开始写AGENTS.md的完整思路包括内容结构、语法细节、工具兼容验证和踩坑总结适合正在管理多个仓库、又想让 AI 代理稳定干活的开发者参考。先说结论AGENTS.md不是又一个 README它是专门写给 AI 代理看的“仓库入职手册”。过去几个月我在不同项目里测试了不同写法发现真正有效的文件通常都很短、很具体并且命令必须能被无脑执行。下面我会按自己实际使用的顺序把这份文件的写法拆开讲清楚。1. 为什么项目里要放一个给 AI 看的说明书很多团队现在都让代理直接进仓库改 bug、补测试、做小重构。但代理和人类新人一样进到一个完全陌生的仓库时面临的第一问题不是“怎么写代码”而是“这个仓库到底怎么跑起来、有什么约定、什么不能碰”。没有一份说明代理就只能在代码里猜猜多了自然就会翻车。1.1 从 CLAUDE.md 到 AGENTS.md配置文件为什么需要统一最早大家流行的是CLAUDE.md因为 Claude Code 用户多工具也默认读取这个文件。后来 OpenAI 的 Codex、其他一些代理工具也入场每个工具都有自己的规则文件比如.cursorrules、CODEOWNERS相关的说明等等。问题是一个仓库不可能给十个工具各准备一份规则文件维护成本会失控。AGENTS.md的优势在于它跟具体厂商解耦。名字里的 AGENTS 是“智能体/代理”的意思不管你的代理是哪个工具它到这个仓库里都能先去找统一入口。当前大家讨论“还能使用的项目 agents.md”本质上是在说这个约定已经沉淀下来了不是某个工具的一时噱头。我自己的判断是只要你的项目希望被多个 AI 代理稳定访问就值得在根目录放一份AGENTS.md。从落地角度看这个文件不需要任何插件、不需要注册账号就是一个纯文本约定。该写哪些信息、怎么写下面几节我会给出可以直接抄的版本。1.2 没有 AGENTS.md 时 AI 代理最常见的四类“翻车现场”我在没有配置AGENTS.md的仓库里反复见过四类问题你可以对号入座跑错命令代理可能用npm test去跑一个实际用pnpm vitest的项目报错后它还会自己尝试修结果越改越乱。动错范围你只想让它修一个登录 bug它顺手“优化”了旁边三个模块提交信息还写得牛头不对马嘴。风格不一致仓库里函数命名用snake_case代理却按自己的偏好写成了camelCasecode review 阶段看得人脑壳疼。破坏不可逆操作代理自作主张执行了数据库迁移、删除了临时目录、或者是推送了镜像这些操作在本地开发环境可能没事在共享环境就是事故。这些问题不是代理能力不行而是它缺少最基本的“项目上下文”。人类新人入职第一天你会告诉他测试跑哪个命令、代码放哪个目录、发布流程是什么AGENTS.md就是把这件事制度化改由文件来传递。1.3 把它当成“代理的入职手册”而不是又一份文档写这份文件最大的心态转变是它不是给人通读的文档而是给代理“快速建立心智模型”的操作手册。人的文档可以长篇大论代理每次处理任务时能读取的上下文却是有限的所以你写的内容必须有优先级先是什么、再是什么、禁止什么。我习惯用一个类比你带新人第一天通常不会把 500 页的技术文档甩给他而是会先说“这个项目主要做什么、你第一次提交代码要跑这三条命令、有问题先问”。AGENTS.md也是这样越靠近文件开头的内容越应该重要代理在生成代码时往往会更重视前面几段规则所以把最重要的约束放在前面比放在文件末尾有效得多。2. 动手之前先梳理项目自检清单在写任何 Markdown 之前建议先拿一张纸把项目过一遍。很多人一上来就打开编辑器开始写“欢迎使用本项目”结果写出来的东西都是废话。与其那样不如先回答下面三个问题。2.1 第一件事说清这个仓库是干什么的用一两句话讲清楚项目职责不要用产品经理视角写“为用户提供高效服务”要用工程师视角写“这个仓库是用户订单支付服务处理下单、库存扣减、支付回调不负责用户注册和商品管理”。这个边界信息对于代理特别重要。因为代理在仓库里搜索代码时如果不知道边界很容易在user-service的仓库里“顺手”改了订单相关的逻辑最后引发耦合问题。我在实际项目中把这一条放在了最顶部后来代理越权的次数明显变少。2.2 第二件事把“代理必须知道”和“人必须知道”分开AGENTS.md不需要替代README或CONTRIBUTING。人的开发文档可以包含背景、架构演进、会议记录代理需要的是可以执行的事实。所以我通常建议在自检时问自己如果代理不知道这条信息它会不会犯错如果不会犯错那这条就不用写。比如“团队每周三开例会”这种信息对代理毫无意义“提交 PR 前必须跑pnpm lint”就值得写。把两类信息分开有个额外好处减少AGENTS.md的体积代理读取和遵循规则的效率会更高。我自己见过把架构图、会议纪要和部署手册全部塞进AGENTS.md的仓库结果代理在长上下文里迷失重点甚至开始忽略后面的约束这就像给新人一本密密麻麻的手册他反而不知道该信哪一条。2.3 第三件事列出不可逆操作和安全红线代理执行任务时最让人担心的不是它写不好代码而是它执行了不该执行的操作。所以在写AGENTS.md之前必须把项目的“红线”列清楚不允许直接操作生产环境数据库。不允许执行数据库迁移除非人类明确批准。不允许删除migrations/目录下的任何文件。不允许生成或打印密钥、Token。不允许推送 Docker 镜像到生产仓库。列红线的时候我给每条都加一句“为什么”因为代理在决策时如果只知道“不能做”不知道“为什么不能做”可能在相似场景下换一种方式犯错。比如“不要执行prisma migrate deploy因为这会影响共享测试库只能由维护者手动执行”这比干巴巴的禁止更有效。3. 一份可复用的 AGENTS.md 骨架与写法拆解当你完成自检就可以开始写文件了。下面这套骨架是我目前在多个项目里使用的版本兼顾了通用性和可维护性。注意里面的命令和目录都要替换成你项目真实的路径模板只是示范。3.1 头部信息名称、简介、技术栈怎么写得一眼懂AGENTS.md本身可以直接从# AGENTS.md开始但如果你的工具支持 frontmatter我建议在文件最顶部放一小段元信息。frontmatter 不是必需的但它能帮助一些工具快速提取“仓库角色”尤其是当代理需要同时索引多个仓库时。示范如下--- name: payment-service description: 用户订单支付服务处理下单、库存扣减、支付回调不负责用户注册和商品管理。 tech_stack: - Python 3.12 - FastAPI - PostgreSQL 16 - Redis - Celery ---你可能会问这些信息不是已经写在 README 里了吗为什么还要在AGENTS.md里重复因为代理读取AGENTS.md时通常不会先去翻 README这段 frontmatter 是给代理的“电梯陈述”。尤其是description我建议尽量写清楚“做”和“不做”两个方面边界越明确代理后续行为越可预测。3.2 命令约定构建、测试、Lint 命令一定要可复制这是AGENTS.md里最核心的部分。代理每次改完代码都要自行验证如果你的测试命令还需要依赖某些 shell 别名代理就完全没法执行。我一般按下面的格式来写## 常用命令 - 安装依赖poetry install - 启动本地服务uvicorn app.main:app --reload - 跑全部测试pytest tests/ -v - 跑单个测试pytest tests/test_order.py::test_create_order -v - 代码检查ruff check app/ tests/ - 类型检查mypy app/ - 格式化ruff format app/ tests/ 注意 - 所有命令都必须在项目根目录执行。 - 如果测试命令需要外部依赖如本地 Redis先启动 docker compose up -d redis。这里我要强调一个容易被忽略的细节每个命令都要写完整参数不要写“跑测试”就完了最好连目录、文件路径都写出来。因为代理处理上下文时会优先选用具体、明确的命令而不是去猜。还有命令一定要是可退出、非交互式的如果命令会进入vim或打开交互式提示符代理就直接卡住了。3.3 代码规则命名、目录、提交信息怎么写代码规则部分要区分“一定要做”和“一定不要做”不要用模糊的“尽量”“建议”这类词。示范## 代码规则 - 所有业务逻辑必须放在 app/services/ 目录下不要在路由处理函数里写 SQL。 - 新建模块必须附带单元测试测试文件命名格式test_模块名.py。 - 函数命名使用 snake_case类名使用 PascalCase。 - 禁止在代码中硬编码密钥统一从环境变量读取。 - 提交信息格式type(scope): description例如 fix(order): correct stock deduction logic。 - 不要在 git commit 信息中提及内部工单链接。为什么要把这些写进去因为代理在生成代码时会倾向于模仿仓库里已有代码的风格但如果仓库里新旧风格混杂代理就可能随机模仿一种。明确写清楚“这个仓库现在采用什么风格”代理的表现就会稳定很多。如果有可能你可以直接在规则后面附一个“参考文件路径”比如“参考app/services/order_service.py的实现风格”代理会更快理解。3.4 工具边界允许代理做什么、禁止代理做什么我习惯用“允许、禁止、询问”三层来定义边界这比单纯的列表更实用## 工具边界 允许 - 修改 src/ 和 tests/ 下的代码。 - 新增补丁对应的测试用例。 - 执行构建、测试、Lint 相关命令。 - 创建新文件但必须遵循现有目录结构。 禁止 - 修改 migrations/ 目录下的文件。 - 删除 data/ 目录中的任何数据。 - 执行任何数据库写操作。 - 修改 CI/CD 配置文件如 .github/workflows/。 遇到以下情况必须停下来询问人类 - 需要安装新的第三方依赖。 - 需要修改数据库表结构。 - 需要改动启动脚本或部署配置。这里有个很实际的好处代理一旦遇到规则里没有覆盖的情况它能按照“询问”策略停下来而不是自作主张。我在项目中加入“必须停下来询问”这条规则后误操作的次数基本归零因为代理在不确定时会主动把问题抛回给你。3.5 自检清单让代理提交前逐条打勾最后一段我会放一个提交前自检清单。它的作用是让代理在完成一个任务之后、准备收尾之前逐项检查自己的成果## 提交前自检 - [ ] 所有测试通过pytest tests/ -v - [ ] 代码检查通过ruff check app/ tests/ - [ ] 没有在路由处理函数中直接写业务 SQL。 - [ ] 新增公开函数有 docstring。 - [ ] 没有修改任何 migrations/ 文件。 - [ ] 没有在代码中新增硬编码密钥。 - [ ] 提交信息符合规范type(scope): description这个清单不用长但要保证每一项都是可检查的。代理在提交之前会把这些条件当成“校验逻辑”逐条执行如果某一条失败它就自己修正而不是带着问题提交。这比你在 review 阶段手工检查高效得多。4. 工具兼容性与“当前还能用”的判断方法写完AGENTS.md接下来要关心的是我的工具真的会读它吗不同工具对“当前还能使用的项目 agents.md”的理解有差异这很正常关键是你要掌握一套验证方法而不是盲信文档。4.1 当前主流工具对 AGENTS.md 的读取方式根据我的使用经验至少在 2025 年这个时间点多数主流的 AI 编码代理工具已经把AGENTS.md当作一个通用入口来支持。不过它们的优先级仍有区别我整理了一张对照表供你排查工具常见配置文件对 AGENTS.md 的支持我的使用建议Claude CodeCLAUDE.md新版本开始兼容读取但CLAUDE.md仍是首选两处内容保持一致避免冲突OpenAI CodexAGENTS.md明确支持属于通用约定直接使用AGENTS.mdCline 等 VS Code 插件AGENTS.md/.cursorrules通常支持但需要看插件版本用通用 Markdown 格式最稳Cursor.cursorrules不一定读根目录AGENTS.md可以手动配置把关键信息同步进项目规则这份表不是精确到每个版本的说明因为工具更新太快。我真正想强调的是不要因为某个工具暂时不支持就放弃 AGENTS.md。它作为仓库统一约定即使某一天你换了工具文件依然有效。用一个通用格式写出来保证任何工具都能读才是正道。4.2 兼容性写法避免依赖某个工具的私有字段写AGENTS.md时要尽可能“克制”不要使用某个工具特有的扩展语法。比如不要为了某个插件写“agent标签”之类的特殊指令也不要依赖 MCP 配置里的字段。最通用的写法就是普通 Markdown 标题加无序列表最多加一段最简单的 frontmatter。原因很简单一旦你在AGENTS.md里用了私有语法换成另一个工具时这些语法不但可能无效还可能因为解析失败导致整个文件被忽略。我见过一个项目为了配合某个工具的特性在文件里塞了大量 XML 标签结果代理读出来全是乱码最后还得重写。通用写法虽然朴素但最稳妥。4.3 怎么验证你的 AGENTS.md 真的被读到这个是我认为最容易被忽略的一步。很多人写完文件就以为代理会自动遵守实际上代理可能根本没读或者读了但没按优先级执行。我建议用“暗号法”来验证非常简单在AGENTS.md的“常用命令”里故意把一条命令的注释改成独特文案比如“pytest tests/ -v # 黄瓜测试专用”。让代理执行一个会触发该测试命令的任务比如“修复test_order.py里失败的测试”。如果代理在回复中提到“黄瓜测试专用”或有类似的复述行为说明它确实读到了这段内容。另外你也可以在会话一开始直接问代理“请先阅读项目根目录的AGENTS.md然后告诉我你计划怎么处理这个任务。”它如果能在计划里引用文件中的规则就说明文件被正确识别了。这个方法我每换一个新仓库都会跑一遍能省掉不少排查时间。5. 我在真实项目中踩过的坑与验证经验最后这部分我想把实际项目里踩过的几个坑和对应的调整方式写下来希望能帮你少走点弯路。这些经验不是从文档里抄来的是我真刀真枪改文件改出来的。5.1 写得太厚代理开始无视规则的原因我第一次给一个中大型仓库写AGENTS.md花了两天写了三百多行把模块划分、历史背景、常见陷阱全部写了进去。结果实际跑下来代理的表现反而更差经常忽略文件后半部分的规则。后面我才意识到代理能处理的上下文是有限的文件太长时它会产生“选择困难”。后来我把AGENTS.md压缩到 60 行以内只保留命令、边界、自检清单把架构演进和历史背景全部删掉。效果立竿见影代理的完成度和规则遵守率都明显上升。如果你确实有很多背景信息要表达可以拆成多份文件比如AGENTS.md只做总纲再在docs/agents/下放一份architecture.md按需引用。5.2 命令不校验上下文越多错误越隐蔽另一个坑是命令写得很“想当然”。比如我一开始在AGENTS.md里写“启动服务python app/main.py”但实际项目用的是uvicorn需要加载 ASGI 应用。代理照着这个错误命令跑了一个小时反复报错最后才因为某个报错信息回溯到入口文件才猜对。从那以后我给自己定了一条规矩所有写入 AGENTS.md 的命令必须先在干净环境里手动执行一遍确认它能跑通。特别是测试命令最好在临时分支上模拟一次代理的完整流程安装依赖、跑测试、跑 lint、提交每一步都用文件里的原始命令不用任何 shell 别名。5.3 规则和 README 互相矛盾让代理无所适从项目里最常见的问题是README.md说“安装依赖用npm install”而AGENTS.md里写的是“安装依赖用pnpm install”。两个文件相互矛盾时代理可能随机选择其中一个也可能反复切换最后导致依赖环境被搞乱。我的做法是在AGENTS.md里不重复 README 的内容而是在顶部加一行“项目背景和架构说明见 README本文档只规定代理执行规则”。这样一来命令类信息以AGENTS.md为准其他背景信息去 README 查不会互相覆盖。如果你不想让两个文件割裂也可以在 README 里专门加一小节“AI 代理请阅读 AGENTS.md”把链路串起来。5.4 版本管理AGENTS.md 也要评审和 review最后一条经验可能最容易被忽略AGENTS.md不是一次性文件它需要跟着项目一起演进。每次新增目录、更换测试框架、调整代码规范时都要同步更新它。我建议把AGENTS.md纳入和普通代码一样的 PR 审查流程任何改动都要有 diff、有人 review。实际操作中我会在每个 PR 的描述里加一句“如果本 PR 涉及目录结构或命令变更请同步更新 AGENTS.md”确保文件不会慢慢腐化。我自己的默认做法是新建仓库时第一个 PR 就带上最简版AGENTS.md哪怕只有十行至少让代理从第一天起就有规则可循。等到项目长大了再回头补成本会高很多。这套方法我用了小半年最大的感受是代理不是靠“提醒”来靠谱的而是靠“上下文”来靠谱的。你喂给它什么样的规则它就表现成什么样。把AGENTS.md当项目基础设施认真对待它会成为你团队里最安静的“自动值守同事”。