Appearance
AGENTS.md 是什么？怎么写给 AI agent 看？
你会学到：AGENTS.md 不是给人看的项目介绍，而是写给 Codex 这类 AI agent 的项目协作说明。
先做这个
如果你不知道该写什么，先在项目根目录放一份最小版本：
text
# Agent 协作说明
## 默认规则
- 先阅读相关文件，再提出计划，不要直接改。
- 每次只做一个小任务，优先改文档或低风险文件。
- 改动前说明会碰哪些文件。
- 改完后说明改了什么、怎么验证、还有什么风险。
## 禁止事项
- 不要写入或展示 API Key、Cookie、token、账号、客户资料。
- 不要修改生产配置、付款、部署、DNS、权限设置，除非我明确要求。
- 不要删除文件或批量改目录，除非我明确确认。
## 验收方式
- 文档任务：检查链接、标题、错别字和页面是否能打开。
- 代码任务：说明改动文件，运行项目已有测试或最小检查。这就够了。新手第一版不要超过 20 行。
它到底解决什么问题？
你每次和 AI agent 协作，都会重复说这些话：
- 先看文件，别上来就改。
- 不要碰密钥。
- 不要改生产配置。
- 改完告诉我怎么验证。
- 这个项目用什么风格。
AGENTS.md 的作用就是把这些固定规则提前写下来。以后 agent 进项目时，先读这份说明，再决定怎么行动。
它和 README 有什么区别？
| 文件 | 主要读者 | 写什么 |
|---|---|---|
| README.md | 人 | 项目是什么、怎么安装、怎么运行 |
| AGENTS.md | AI agent | 怎么协作、哪些能改、哪些不能改、怎么验收 |
一句话：
text
README 告诉人怎么理解项目；AGENTS.md 告诉 agent 怎么在项目里做事。新手应该写哪几类内容？
只写 5 类。
1. 项目边界
告诉 agent 这个项目是什么，不要让它猜。
text
这个项目是一个 VitePress 教程站，主要内容是 Markdown 页面。
优先修改 `guide/`、`questions/`、`practice/`、`reference/` 下的文档。2. 默认工作方式
告诉 agent 先做什么、后做什么。
text
默认先读相关文件和配置，再说明计划。
不确定时先问；能小改就不要大改。3. 禁止或高风险事项
这是最重要的部分。
text
不要提交密钥、Cookie、token、账号信息、个人身份信息。
不要自动发布第三方平台内容。
不要修改 DNS、付款、备案、仓库公开状态。4. 验证方式
不要只说“改好了”，要告诉 agent 怎么证明改好了。
text
文档改动后运行 `npm run qa`。
前端页面改动后检查移动端和桌面端。
上线后检查页面 200、sitemap、IndexNow。5. 输出格式
让 agent 汇报得稳定一点。
text
完成后汇报：改了什么、验证结果、线上状态、剩余风险。写给 AI 的版本应该更直接
给人看的文章可以解释背景。给 AI agent 的文件要更像规则清单。
好的写法：
text
- 修改前先运行 `git status --short --branch`。
- 不要清理 `验证文件/`。
- 只改和当前任务相关的文件。
- 改完运行 `npm run qa`。不好的写法：
text
我们希望你充分理解项目精神，并在必要的时候灵活发挥。原因：AI agent 更需要明确边界、动作顺序和完成标准。
最小模板
复制这一份即可开始：
text
# AGENTS.md
## 项目
这是一个文档/教程项目。优先保持内容清晰、链接可用、读者能照做。
## 默认流程
1. 先读相关文件和配置。
2. 说明计划。
3. 小范围修改。
4. 运行对应检查。
5. 汇报改动、验证结果和剩余风险。
## 安全边界
- 不要写入密钥、Cookie、token、账号、个人隐私。
- 不要修改付款、DNS、备案、仓库权限、第三方发布状态。
- 不要删除文件或批量改目录，除非用户明确确认。
## 验证
- 文档：检查链接、标题、错别字、页面是否能打开。
- 代码：运行项目已有测试或最小 QA。
- 前端：检查移动端和桌面端。常见坑
- 把
AGENTS.md写成项目说明书，里面没有任何协作规则。 - 写了很多价值观，但没有“哪些不能改”。
- 把密钥、账号、内部路径、客户信息写进去。
- 一上来写几十条复杂规则，agent 反而抓不住重点。
- 每个项目复制同一份，不写项目自己的验证方式。
完成标准
- 你知道
AGENTS.md是写给 AI agent 的协作说明。 - 你能写出一份 20 行以内的最小版本。
- 你知道必须写清楚安全边界和验收方式。
- 你知道下一步可以读 06 AGENTS.md 或继续学 配置、Skills、MCP。
来源与复核
- 官方复核：Codex AGENTS.md 指南 与 openai/codex GitHub 仓库。
- 本站建议：新手先写短规则，先保护安全边界，再逐步补项目风格和验证方式。
- 复核日期：2026-06-08。