长期以来，README.md 一直是项目的标准“说明书”：项目简介、安装步骤、目录结构、贡献指南
随着 AI 在开发中的参与度越来越高，README 逐渐显得力不从心。于是，一个新的文件规范正在兴起 —— AGENTS.md。
什么是 AGENTS.md
AGENTS.md 是 OpenAI 提出的一个开放文件规范，目前已经被数万个开源项目采用。它并不是为了替代 README.md，而是弥补后者在 AI 时代的不足。
Github：github.com/openai/agen…
一个简单的 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 助手来说，它们是每天都要依赖的工作说明。
README.md vs AGENTS.md
- README.md 写给人类开发者看
- AGENTS.md 写给 AI 助手和自动化工具看
为什么前端项目尤其需要
前端开发的复杂度，几乎是 AGENTS.md 的“天然适配场景”：
- 脚手架多样：Vite、Next.js、Monorepo，命令五花八门；
- 规范繁琐：ESLint、Prettier、Commitlint，每个团队要求都不同；
- 自动化频繁：Lint 检查、单元测试、CI 构建，每天都要执行。
这些规则写在 README 里，既容易让文档臃肿，又不方便 AI 使用。集中到 AGENTS.md，就能把人和机器的需求分开处理：
- 开发者：用 README 快速上手
- AI 助手：用 AGENTS.md 严格遵循项目规范
好处有三点：
- 保持代码一致性：AI 生成的代码不再风格混乱[
- 提高效率：AI 有了明确指令，能快速写样板、改 Bug
- 减少沟通成本：人和 AI 遵循同一份规范，团队协作更顺畅
写在最后
如果你正在使用 AI 辅助开发，不妨试试为项目加一份 AGENTS.md。这不仅是文档的升级，也是前端团队迎接智能开发的一步。
