为什么 AI 编程项目开始需要 AGENTS.md？

当 AI 编程 Agent 进入一个真实仓库，它面对的通常不是“写一个函数”这么简单。它还需要知道项目用什么命令启动、测试在哪里、哪些目录不能改、代码风格是什么、提交前必须通过哪些检查。

这些信息如果只存在于人的记忆里，Agent 每次都要重新猜；如果全部塞进 README，又会让面向人的文档变得臃肿。加载链接预览… 的目标，就是给代码 Agent 提供一个稳定、可预测的项目上下文文件。

先给结论：加载链接预览… 是给 Agent 看的项目协作说明

加载链接预览… 官方网站把它比作“给 Agent 的 README”：它可以记录构建命令、测试方式、代码约定、安全注意事项和部署流程，同时不必把所有细节混进面向人类贡献者的 README。AGENTS.md 官方说明

它不是新的编程语言，也不是一个需要注册的服务。它就是 Markdown 文件，但文件名和位置让不同的编码 Agent 可以用一致方式发现它。

一个最小版本可以这样写：

文件名：AGENTS.md

## 项目概览

这是一个使用 TypeScript 和 Vite 的前端项目。

## 常用命令

- 安装依赖：pnpm install
- 启动开发环境：pnpm dev
- 运行测试：pnpm test
- 运行检查：pnpm lint

## 修改约束

- 不要直接编辑生成目录。
- 修改 API 时同步更新测试。
- 提交前运行相关测试和类型检查。

为什么 README 不够

README 通常服务第一次接触项目的人，内容重点是项目是什么、怎么安装、如何快速运行。Agent 需要的上下文更偏向执行：

• 哪个命令才是真正的测试入口；
• monorepo 中应该进入哪个 package；
• 哪些文件由代码生成器维护；
• 修改某个模块后必须运行哪些专项检查；
• 项目里有哪些看起来合理、实际上不能触碰的兼容逻辑。

这些信息对人类也有价值，但不一定适合全部放在 README 首页。加载链接预览… 提供了一个专门位置，让 Agent 有机会在开始修改前主动读取。

嵌套文件让大型仓库拥有局部规则

一个仓库可以在根目录放一份通用规则，也可以在子目录里放更具体的 加载链接预览…：

repo/
├── AGENTS.md
├── apps/
│   ├── AGENTS.md
│   └── web/
│       └── AGENTS.md
└── packages/
    └── api/
        └── AGENTS.md

当 Agent 修改 apps/web/ 下的文件时，它需要同时理解根目录和更近的局部规则。加载链接预览… 官方说明建议使用“离目标文件最近的文件优先”的方式处理范围和冲突；用户在当前对话中的明确要求仍然应该拥有更高优先级。层级与优先级说明

这很像作用域：根文件定义整个项目的公共约束，子目录文件补充某个模块的特殊要求。它比“一份几千行全局说明”更容易维护，也更接近代码真正的边界。

高质量的 加载链接预览… 应该写什么

可以把内容分成四层：

1. 让 Agent 快速定位

说明项目结构、关键目录和入口。不要只写“这是一个前端项目”，而要告诉它页面、服务端、测试和生成文件分别在哪里。

2. 让 Agent 能运行

列出安装、开发、测试、构建和 lint 命令。命令要尽可能是仓库真实使用的命令，不要复制一份已经过期的脚本名。

3. 让 Agent 知道怎么改

写清代码风格、命名方式、错误处理、测试要求和 API 变更规则。比起“保持代码整洁”，更有用的是“新增服务函数时必须同时添加对应的单元测试”。

4. 让 Agent 知道什么时候停下来问

如果改动会涉及数据库迁移、凭据、生产环境、删除数据或破坏兼容性，文件应该明确要求先确认。Agent 的效率不应来自跳过风险控制。

常见失败写法

规则太抽象

“写高质量代码”“遵循最佳实践”几乎不能帮助 Agent 做决定。规则应该连接到文件、命令或可验证结果。

命令已经失效

过期的测试命令会让 Agent 得出错误结论。加载链接预览… 不是一次性配置，而是随项目变化的活文档。

把所有事情都禁止

如果每条规则都是“不要做”，Agent 会变得过度保守，也会忽略真正重要的约束。应当同时写“可以做什么”和“遇到什么情况需要确认”。

把秘密写进去

加载链接预览… 会进入版本库，不能放 Token、密码、内部地址或任何不应公开的凭据。需要秘密时，说明变量名称和获取方式即可。

加载链接预览…、Skill 和 Prompt 的边界

三者可以配合，但职责不一样：

例如，“修复登录 Bug”是当前 Prompt；“修改认证模块后必须运行安全测试”是 加载链接预览…；“如何做一轮完整安全审计”则可以做成 Skill。

最后用一个问题检查它

把 加载链接预览… 交给一个刚加入项目的人，问他能不能回答：从哪里开始、怎么验证、哪些地方不能碰、什么时候要停下来确认。如果不能，问题通常不是文件不够长，而是缺少可执行的上下文。

一句话总结：加载链接预览… 不会让模型突然变聪明，但会让它少走很多本来不该走的弯路。

来源

• AGENTS.md 官方说明
• OpenAI Codex：Custom instructions with AGENTS.md