Codex
AGENTS.md 入门:给 AI 编程代理写一份项目说明书
AGENTS.md 是放在仓库根目录的纯 Markdown 文件,用来告诉 Codex、Cursor、Gemini CLI 等 AI 编程代理项目的构建、测试和代码规范。文章讲清了它的格式、嵌套规则、Codex 的读取细节,以及它只是指令不是强制锁的边界。
今天就能做
- 今天就在仓库根目录建一个 AGENTS.md,先写上测试命令和提交前检查
- 检查你的 Codex 项目文档总量是否接近 32 KiB 上限,太长会被截断
- 把「必须禁止」的操作从 AGENTS.md 挪到工具的权限配置里,别指望文字约束
AGENTS.md 是什么
- agents.md 官方把它称为「给代理看的 README」:README 写给人看,AGENTS.md 存放会弄乱 README 的细节,如构建测试命令、代码风格、PR 规则
- 开放格式,不绑定任何厂商,超过 6 万个开源项目在用,由 Linux Foundation 旗下的 Agentic AI Foundation 维护
- 典型场景:新开发者让代理直接上手,代理不知道测试怎么跑,猜错命令白折腾十几分钟——文件里一行说明就能避免
格式与写法
- 纯 Markdown,没有必填字段和规定标题,关键是每条指令要具体到能验证是否被执行
- 官方建议先写测试命令:写进文件后,代理会在宣布任务完成前主动跑测试并修复失败
- 示例结构分四块:Setup(composer install、npm install)、Tests(每次提交前跑 php artisan test)、Code style(PHP 4 空格、Vue 2 空格)、Pull requests(标题格式、禁改 config/payments)
- 不要写公司介绍或「写干净代码」这类空话——代理能自己看代码,文件只写它从代码里学不到的东西
存放位置与嵌套规则
- 主文件放仓库根目录;大仓库可在每个子应用目录再放一份,离被编辑代码最近的文件优先级更高
- 聊天中的直接指令优先于任何文件
- Codex 的细节:全局文件在 ~/.codex/AGENTS.md;可用 AGENTS.override.md 覆盖;从仓库根到当前目录逐层合并,越近的越后读
- Codex 总量上限 32 KiB(可用 project_doc_max_bytes 调整),每个目录只取一个文件,超限后不再加载——文件要短
- 可在 ~/.codex/config.toml 里用 project_doc_fallback_filenames 指定其他文件名(如 TEAM_GUIDE.md)也算指令
哪些工具支持
- 官方列表包括 Codex、Google 的 Jules 和 Gemini CLI、Cursor、Windsurf、Devin、Aider、Zed、Warp、VS Code、JetBrains 的 Junie、GitHub Copilot coding agent 等
- Aider 需在 .aider.conf.yml 加一行 read: AGENTS.md;Gemini CLI 需在 .gemini/settings.json 里设为 context 文件
- Claude Code 不在官方列表,但 Anthropic 文档说明从 2.1.277 版起,项目没有 CLAUDE.md 时会自动读取 AGENTS.md
它是指令,不是锁
- Anthropic 明确说 Claude 把这类文件当上下文而非强制配置,「不许碰支付文件」这种话拦不住执意要改的代理
- 真正要禁止的操作应放进具体工具的权限设置里
- 文件进仓库后所有有权限的人都能看到,密码、API key、内网地址绝不能写进去
- 起步用四段式就够了,之后每次代理重复犯同一个错,就补一句规则
原文:What is AGENTS.md and how to write one
来源:bondsoft.pl · 2026-11-10
查看原文本文由 AI 阅读原文后整理,未经人工逐字核对,内容以原文为准。
登录后可以点赞、查看和发表评论