Agent

最近想要输出一些通过 VibeCoding 方式来构建软件过程中，需要关注的一些知识点，以及我自己的一些开发感受。今天迈出第一步来聊聊 Agent.md。

在软件项目里，如果说 README.md 是给人看的话，那 AGENT.md 就是给用来实现编码任务的 AI Agent 看的。

AGENTS.md 规范在 2025 年 7 月出现，由 Sourcegraph 的 Amp 团队创建，目标是解决一个真实痛点：开发者要为每个 AI 工具维护独立的配置文件（.cursorrules、.windsurfrules、CLAUDE.md 等），承诺"一个文件，适配所有 agent"。现在知名的AI 软件开发工具，比如 CodeX/Cursor/Gemini 都实现了对 AGENTS.md 的支持。

AGENT.md 有对应自己的官方地址 https://agents.md/。要注意 Claude Code 目前是不支持 AGENT.md，它用的是自己的 Claude.md。本质上这两个文件作用都是一样的，都是给 AI coding agent 的指令文件。这也就是为什么很多开源项目里的 Claude.md 的内容是「See AGENTS.md.」

我在用 AI 生成项目的时候，一般会在项目框架生成之后，开始实现业务逻辑之前，完成 AGENT.md 的创建。 创建过程也很简单，直接对你的 AI 编码软件 CodeX/Cursor 之类的应用说，帮我创建 AGENT.md 文件就好了，AI 会问一些问题，最后帮你生成 AGENT.md 文件创建和内容填充。

AGENT.md 一般都有什么内容？这个当然要看 AGENT.md 服务的对象是谁，是编码 AGENT。所以 AGENT.md 里面的内容就需要让 AGENT 能够理解你的项目，同时完成你设计的编码规范。项目刚开始的时候 AGENT.md 不必很多，随着引入的业务逻辑、规范越来越多，我们就需要动态的不断更新 AGENT.md 文件的内容，而不是写完一次之后就再也不管了，更新 AGENT.md 也很简单，直接和 AI 说：「帮我在 @AGENT.md 文件中增加一条规则，所有产品内展示的文案都为英文」，让 AI 自己去分析应该把这条规则更新到 AGENT.md 中的什么位置。

这样说还是有一些抽象，可以看看知名项目 OpenClaw 开源仓库中的 AGENT.md 内的主要模块，基本上就是对项目架构的描述、里面各个业务模块儿的职责说明、一些指导开发和测试的规则、还有就是对命名和代码风格的约束等等... 这些都能用来指导 AGENT 的开发

## Project Structure & Module Organization
## Architecture Boundaries
## Docs i18n (generated publish locales)
## Build, Test, and Development Commands
## Coding Style & Naming Conventions
## Release / Advisory Workflows
## Testing Guidelines
## Commit & Pull Request Guidelines
## Local Runtime / Platform Notes
....

我一个人开发项目的时候，都是自己在维护项目的 AGENTS.md，现在加入了一个大一点的团队，项目的 AGENTS.md 是要统一，团队内会约定一些代码规范的 MD 文件，然后在AGENTS.md 里面直接去引用 MD 文件来规范大家的 AGENTS 的编码习惯，这样方便统一整个团队的编码规范。

之前看到推上有人讨论是不是要把 AGENTS.md 放到团队代码仓库统一管理，我自己认为是有必要同意管理 AGENTS.md 的，理由的话，上面已经说过了，方便统一团队成员的编码规范。

如果个人有一些小癖好的话，完全可以在全局的 AGENTS.md 里面设置自己的编码规范，配置目录如下

//CodeX
`~/.codex/AGENTS.md`
//ClaudeCode
`~/.claude/CLAUDE.md`

甚至 CodeX 还支持 AGENTS.override.md 规范，也就是尽管代码仓库里有统一的 AGENTS.md ，但你还是可以重新创建 AGENTS.override.md 文件来覆盖原有的 AGENTS.md 中的一些规则。不过我自己感觉没必要，真有这种需求理论上放到全局 ~/.codex/AGENTS.md 下会更好。

有一些开发者不知道怎么创建 AGENTS.md，我的一些思路是 - 如果是项目刚开始，自己还没有想好怎么架构，可以边写项目边更新 AGENTS.md 规则，也就是让 AGENTS.md 和项目一起成长。更新 AGENTS.md 的方式其实就很简单，直接跟 AI 说，帮我在 AGENTS.md 里面增加XX 规则就好了，具体怎么加，相信 AI 比你更加擅长。 - 如果项目已经有雏形了，可以直接让 AI 理解项目后产出一份 AGENTS.md 文件，AGENTS.md 里面就会有项目的架构之类的信息，之后也是慢慢家规则。

一个原则就是 AGENTS.md 一定是很贴合你的项目的，如果你在网上看到一份觉得写的很好的 AGENTS.md 直接拷过来用，大概率效果不会太好，至少也要让 AI 根据当前项目重构 AGENTS.md 来适配当前项目，如果编码 AGENT 都不理解项目，编码从何谈起呢？

总而言之，在 VibeCoding 的工作流里，AGENTS.md 绝对不是一个“写完就吃灰”的配置文件，而是我们和 AI 结对编程时的“共同记忆”与“协作契约”。它需要像你的代码一样，随着业务逻辑的复杂化，经历从无到有、从粗糙到精细的演进过程。