AGENTS.md（智能体项目说明文件）
一句话定义
AGENTS.md（智能体项目说明文件）是放在项目里的长期规则文档，用来告诉 Coding Agent（智能体）这个项目怎么读、怎么改、哪些地方不能碰、怎样验证和怎样汇报。
通俗解释
README（项目说明文件）主要写给人看，AGENTS.md（智能体项目说明文件）主要写给编程智能体看。它的价值不是介绍项目多厉害，而是减少智能体乱猜、乱改、乱跑命令的概率。
你可以把它理解成“项目给智能体的工作手册”。当智能体进入一个项目时，它先读这类文件，就能知道：
- 这个项目当前阶段是什么。
- 目录分别负责什么。
- 哪些文件可以改，哪些文件不能改。
- 常用启动、测试、构建和检查命令是什么。
- 哪些操作必须先问人。
- 完成任务后必须提供哪些验证证据。
它和 README（项目说明文件）、Prompt（提示词）、Skill、MCP（模型上下文协议）的区别
| 对象 | 主要读者 | 解决什么问题 |
|---|---|---|
| README（项目说明文件） | 人类用户、开发者、面试官 | 这个项目是什么，怎么启动，怎么演示 |
| Prompt（提示词） | 当前这一轮模型任务 | 这一次要做什么 |
| AGENTS.md（智能体项目说明文件） | Coding Agent（智能体） | 这个项目长期有哪些规则 |
| Skill（技能） | 编程智能体平台或工具 | 同一类任务应该按什么流程做 |
| MCP（模型上下文协议） | 模型客户端和工具服务端 | 外部工具、资源和上下文怎么接入 |
最简单的区分方式是：Prompt（提示词）是“一次任务”，AGENTS.md（智能体项目说明文件）是“一个项目的规矩”，Skill（技能）是“一类任务的方法”，MCP（模型上下文协议）是“外部能力的连接方式”。
应该写哪些内容
新手不需要一开始写很复杂。一个实用的 AGENTS.md（智能体项目说明文件）至少包含下面 8 类信息。
| 模块 | 应该写什么 | 为什么重要 |
|---|---|---|
| Project Goal（项目目标） | 项目解决的问题、当前版本目标、不要做的方向 | 防止智能体把项目做偏 |
| Audience（读者或用户） | 谁会使用这个项目，谁会阅读文档 | 决定页面、文案和解释深度 |
| Directory Map（目录地图） | 主要目录和文件职责 | 帮智能体快速定位修改点 |
| Edit Boundary（修改边界） | 可改、慎改、禁止改的范围 | 防止误删、误重构、误覆盖 |
| Commands（常用命令） | 启动、检查、构建、测试、格式化命令 | 让智能体知道如何验证 |
| Quality Bar（质量标准） | 怎样算完成，必须留下什么证据 | 避免只说“完成了” |
| Safety（安全指南） Rules（安全规则） | 密钥、生产配置、部署、数据库、敏感资料规则 | 控制高风险动作 |
| Reporting Rule（汇报规则） | 最后如何说明修改、验证和剩余风险 | 方便人类复盘 |
和 Skill（技能）怎么配合
AGENTS.md（智能体项目说明文件）解决“这个项目的规矩”，Skill（技能）解决“这类任务怎么做”。两者可以同时存在。
举例：你让 Coding Agent（智能体）修一个页面问题。
| 信息来源 | 提供什么 |
|---|---|
| AGENTS.md（智能体项目说明文件） | 页面目录在哪、不能改哪些文件、验证命令是什么、最终汇报格式 |
| Bug（缺陷） Diagnosis Skill（缺陷诊断技能） | 先复现、再定位、再最小修复、最后验证 |
| Browser MCP（模型上下文协议） | 打开页面、截图、读取控制台错误 |
| Tool Calling（工具调用） | 执行读取文件、修改文件、运行检查等动作 |
这样智能体不是凭感觉做事，而是在项目规则和任务方法共同约束下工作。
常见误区
| 误区 | 正确理解 |
|---|---|
| AGENTS.md（智能体项目说明文件）就是另一个 README（项目说明文件） | 它重点写给智能体看，应该包含边界、命令、禁区和验收 |
| 写得越长越好 | 太长会让重点淹没，应该写稳定规则和高风险边界 |
| 有了 AGENTS.md（智能体项目说明文件）就不用提示词 | 它提供长期规则，具体任务仍然需要清晰 Prompt（提示词） |
| 可以把密钥写进去方便智能体部署 | 不能写密钥，敏感信息应该通过安全配置和人工授权处理 |
| 所有项目都必须完全一样 | 不同项目的目录、命令、风险和验收标准应该不同 |
面试官可能怎么追问
1. 为什么需要 AGENTS.md（智能体项目说明文件）？
考察点： 是否理解项目级上下文和临时提示词的差别。
参考回答： 临时 Prompt（提示词）只能说明这一次任务，AGENTS.md（智能体项目说明文件）保存项目长期规则，例如目录结构、修改边界、常用命令、安全禁区和验收标准。这样编程智能体每次进项目时都有稳定上下文，不会只靠猜。
容易扣分： 说“就是写给 AI（人工智能）看的 README（项目说明文件）”，但讲不出边界和验收。
2. AGENTS.md（智能体项目说明文件）和 Skill（技能）有什么区别？
考察点： 是否能分清项目规则和任务方法。
参考回答： AGENTS.md（智能体项目说明文件）绑定具体项目，告诉智能体这个项目怎么改；Skill（技能）绑定任务类型，例如代码审查、部署、文档生成或浏览器验收，告诉智能体这类任务怎么做。一个是项目规则，一个是通用方法。
容易扣分： 把二者都说成“提示词模板”。
3. AGENTS.md（智能体项目说明文件）里最不能写什么？
考察点： 是否有安全意识。
参考回答： 不能写 API Key（接口密钥）、服务器密码、生产数据库连接、客户隐私和不可公开的商业资料。它可以写如何通过安全方式读取配置、哪些操作需要人工确认，但不能把敏感凭据暴露给文档。
容易扣分： 为了“方便智能体自动化”把所有权限都写进去。
4. 怎么判断 AGENTS.md（智能体项目说明文件）写得好不好？
考察点： 是否能用效果衡量文档。
参考回答： 看它能不能帮助智能体减少误操作：是否能快速定位目录，是否知道哪些文件不能改，是否知道验证命令，是否能按统一格式汇报，是否能识别高风险动作。好的 AGENTS.md（智能体项目说明文件）会让任务更稳定、更可复盘。
容易扣分： 只追求格式漂亮，不关心智能体执行效果。