同事惊呆了：AGENTS.md 写了 2000 行，是当 Prompt 还是当 Readme？
AGENTS.md 到底是什么？为什么突然火遍开源圈
最近在程序员圈子里流传着一句调侃：“别人还在写 README，你已经把 AGENTS.md 写到 2000 行了，是把它当 Prompt 喂 AI，还是当 Readme 给人看？”
这个看似搞笑的问题，背后其实反映了 AI 编程时代最核心的变化：项目文档正在从“给人看”转向“同时给人和 AI 看”。
而 AGENTS.md，正是这场转变中最受关注的开放标准。
AGENTS.md vs CLAUDE.md：一个开放，一个私有
很多用过 Claude Code 的开发者第一反应是：这不就是 CLAUDE.md 吗？
其实两者有本质区别：
- CLAUDE.md 是 Claude Code 的私有指令文件，只有 Claude 自己认。
- AGENTS.md 是一个由 Linux 基金会旗下的 Agentic AI Foundation 维护的开放标准。
目前 AGENTS.md 已经被全球超过 6 万个开源项目采用，支持包括 OpenAI Codex、Google Jules、GitHub Copilot、Cursor、Aider、Zed、JetBrains Junie 等 25+ 主流 AI 编程工具。
一份文件，多个 Agent 通用。这才是它真正厉害的地方。
当然，Claude Code 也可以很好地支持 AGENTS.md。最常见的做法是在 CLAUDE.md 中加一行 @AGENTS.md，直接把内容导入进来，实现“两边都不耽误”。
AGENTS.md 和 README.md 到底有什么区别？
很多人把 AGENTS.md 当成 README 的“AI 版本”，但它们的目标用户完全不同：
- README.md 是写给人看的，侧重项目介绍、快速上手、架构说明。
- AGENTS.md 是写给 AI Agent 看的，侧重约束、规范、偏好、工作方式、安全边界和交付标准。
简单来说：
README.md 告诉你“这个项目是什么”，
AGENTS.md 告诉 AI Agent “在这个项目里应该怎么干活，不能怎么干”。
为什么越来越多开发者要把 AGENTS.md 写到上千行？
因为 AI Agent 越聪明，越需要明确的“人格设定”和“行为边界”。
我在实际项目中发现，当 AGENTS.md 写得足够具体时，AI 犯低级错误的概率会大幅下降。常见的写入内容包括：
- 项目技术栈和架构分层原则
- 命名规范和代码风格要求
- 明确禁止的事项（比如禁止批量删除、禁止引入新框架、禁止全局重构）
- 任务完成标准（必须通过类型检查、必须更新对应测试、必须说明修改文件）
- 安全和隐私边界（绝不触碰 .env、绝不操作生产数据）
- 多 Agent 协作时的职责划分和通信协议
这些内容写得越清晰，AI 就越“懂事”，真正实现“一个人带多个 Agent 高效协作”。
实战建议：如何正确编写 AGENTS.md
根据 Codex 官方推荐和大量开源项目实践，以下是一个高质量 AGENTS.md 的推荐结构：
AGENTS.md
项目概览
- 项目类型：全栈 AI 教育平台
- 主要语言：TypeScript + Go
- 关键目录结构说明
常用命令
- 安装依赖、启动开发、运行测试、类型检查、代码格式化等
代码规范与偏好
- 必须遵循现有代码风格
- 禁止无关重构
- 新功能必须补充或更新测试
- 前端统一使用 TailwindCSS
- 接口文件禁止随意改动
安全边界
- 绝不读取或提交 .env 和任何密钥
- 禁止执行可能删除生产数据的命令
- 修改数据库前必须说明影响范围
交付要求
- 每次必须说明修改的文件列表
- 必须提供验证命令和执行结果
- 必须说明未验证项和剩余风险
把这些内容固化到 AGENTS.md 后，你就不用每次和 AI 重复交代“老规矩”了。它会像一个真正懂你团队文化的资深同事一样工作。
AGENTS.md 正在成为 AI 原生项目的“标配”
从目前趋势来看，AGENTS.md 已经不再是一个可选项，而是 AI 时代项目的基础设施之一。
它既是 Prompt（给 AI 的系统指令），也是 Readme（给新 Agent 的项目文化手册），更是一套可以跨工具、跨团队复用的开放协作协议。
当你的 AGENTS.md 从 200 行写到 2000 行时，同事惊呆的可能不是行数，而是：
“原来 AI 真的可以被调教得这么听话。”
你的项目里，AGENTS.md 写了吗？欢迎在评论区分享你的模板和使用心得。