同一个仓库，换一个 AI 助手，产出质量天差地别——多半不是模型的问题，而是这个仓库「对新 AI 的友好度」不同。模型在 2026 年已经足够强，但它在你的仓库里永远是个第一天入职的新同事：不知道构建命令，不知道团队规范，不知道哪些文件碰不得。AGENTS.md 就是写给它的入职手册，也是我认为 Vibe Coding 里投入产出比最高的一件事。

应该写什么：新同事第一天需要的

我的模板通常不超过 60 行，四个板块：

# 项目速览
- .NET 10 / ASP.NET Core Minimal API + EF Core (PostgreSQL)
- 前端为 Razor Pages，无独立 SPA

# 常用命令
- 构建：dotnet build
- 测试：dotnet test
- 本地运行：dotnet run --project src/Api
- 数据库迁移：dotnet ef migrations add <Name> -p src/Infrastructure

# 代码规范
- 所有公共 API 必须有 XML 注释
- 异步方法一律携带并向下传递 CancellationToken
- 业务逻辑写在 Application 层，Controller 只做参数绑定
- 提交信息使用 Conventional Commits 格式

# 禁区
- 不要修改 Migrations/ 下已应用的迁移文件
- appsettings.Production.json 只读
- 不要引入新的第三方依赖，除非我明确要求

不该写什么：三类常见冗余

  • 别抄 Wiki。AGENTS.md 不是文档搬家，五页纸的规则等于没有规则；
  • 别写 AI 自己能看出来的事。「本项目使用 C#」这种信息模型看一眼代码就知道，写了纯属浪费上下文；
  • 别写愿望。写了「必须 100% 测试覆盖」但团队自己都做不到，AI 只会被矛盾的指令搞糊涂。写真实执行的规则。

经验值：控制在 100 行以内。文件越长，模型实际「读进去」的比例越低。

怎么维护：把 AI 犯的每个错变成一条规则

AGENTS.md 不是一次写完的，它靠事故驱动迭代：AI 每犯了让你不爽的错，就沉淀一条对应的规则。几个我文件里真实存在的例子：

  • AI 两次直接改了已应用的迁移文件 → 有了禁区的第一条；
  • AI 偏爱用 builder.Services.AddSingleton 注册 DbContext 相关服务 → 有了「数据访问一律 Scoped」这条；
  • AI 生成了漂亮的 README 但构建命令是错的 → 有了「文档中的命令必须实际验证」。

坚持两三个月，这个文件会变成团队里最诚实的工程规范文档——因为它记录的全是真金白银换来的教训，而且人和 AI 都在读。

进阶：分层放置

仓库大了以后，根目录放全局规范，各子目录可以再放各自的 AGENTS.md：src/Api/ 下写路由与鉴权约定，tests/ 下写测试规范。AI 助手处理某个子目录的任务时，离它最近的规则文件优先级最高。

工具会更替，模型会升级，但「让协作者快速理解项目」这件事的价值只增不减。花一个下午写好它，是你在 Vibe Coding 上最划算的一笔投资。