长期以来，README.md 一直是项目的标准“说明书”：项目简介、安装步骤、目录结构、贡献指南……几乎所有信息都往里面塞。

但问题是，随着 AI 在开发中的参与度越来越高，README 逐渐显得力不从心。于是，一个新的文件规范正在兴起 —— AGENTS.md。

README vs AGENTS.md

最直观的不同：

• README.md 写给人类开发者看；
• AGENTS.md 写给 AI 助手和自动化工具看。

换句话说：

• 人类新人可以通过 README 快速了解项目；
• AI 助手可以根据 AGENTS.md 理解规则、执行命令，减少“瞎猜”。

这样一来，文档既保留了对人的友好，又能让 AI 高效融入协作。

什么是 AGENTS.md？

AGENTS.md 是 OpenAI 提出的一个开放文件规范，目前已经被数万个开源项目采用。它并不是为了替代 README.md，而是弥补后者在 AI 时代的不足。

Github：https://github.com/openai/agents.md

一个简单的 AGENTS.md 例子：

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

一个 AGENTS.md 可以跨多个代理运行：

AGENTS.md 的特点如下：

• 结构化：采用清晰的机器可读格式，方便 AI 直接解析。
• 可执行性：里面的指令是可以直接被 AI 执行的。
• 精炼高效：只包含对 AI 有用的关键信息，例如：
• 构建/启动命令：安装依赖、运行 dev server、build、测试；
• 代码风格规范：单双引号、分号、缩进、Prettier/Lint 配置；
• CI/CD 流程：测试跑法、构建流程、质量检查；
• PR 要求：提交信息规范、review 流程；
• Monorepo 指南：多包目录的构建、测试方法。

对开发者来说，这些东西大多数时候只是偶尔会查；但对 AI 助手来说，它们是每天都要依赖的工作说明。

为什么前端项目尤其需要 AGENTS.md？

前端开发的复杂度，几乎是 AGENTS.md 的“天然适配场景”：

• 脚手架多样：Vite、Next.js、Monorepo，命令五花八门；
• 规范繁琐：ESLint、Prettier、Commitlint，每个团队要求都不同；
• 自动化频繁：Lint 检查、单元测试、CI 构建，每天都要执行。

这些规则写在 README 里，既容易让文档臃肿，又不方便 AI 使用。集中到 AGENTS.md，就能把人和机器的需求分开处理：

• 开发者：用 README 快速上手；
• AI 助手：用 AGENTS.md 严格遵循项目规范。

好处有三点：

• 保持代码一致性：AI 生成的代码不再风格混乱；
• 提高效率：AI 有了明确指令，能快速写样板、改 Bug；
• 减少沟通成本：人和 AI 遵循同一份规范，团队协作更顺畅。

未来的开发流程可能是这样的：

• 新人加入团队，先读 README，快速了解项目；
• AI 助手则自动读取 AGENTS.md，明白该如何写代码、跑测试；
• 人和 AI 分工明确，各自高效协作。

写在最后

README 和 AGENTS.md 并不是替代关系，而是互补关系：

• README.md：写给人看，负责介绍和指引；
• AGENTS.md：写给机器看，负责规则和执行。

如果你正在使用 AI 辅助开发，不妨试试为项目加一份 AGENTS.md。这不仅是文档的升级，也是前端团队迎接智能开发的一步。