📌 项目地址：agentsmd/agents.md | ⭐ 21,814 颗星 | 🔧 TypeScript | 📜 MIT
AGENTS.md是什么
一个放在项目根目录的Markdown文件，专门给AI编码代理看的”操作手册”。
传统README面向人——解释项目是什么、怎么用、为什么这么设计。AGENTS.md只给AI读，内容是”这个项目怎么操作”：用什么包管理器、测试怎么跑、代码规范是什么、PR提交有什么格式要求。
项目地址：agentsmd/agents.md，21814个Star，TypeScript写的，MIT许可。
它解决什么问题
AI编码代理的问题不是”不会写代码”，而是”不知道你项目的潜规则”。
你用pnpm workspace，它猜你用npm；你的测试用vitest而不是jest；你的monorepo里每个包的构建有特定顺序。这些信息每次都在prompt里重复，漏写一次AI就跑偏。
AGENTS.md提供了一个固定位置（项目根目录），让AI第一次接触仓库就能读到这些规则。不需要装插件，不需要修改IDE配置，就是一个文件加几行命令。
官方示例拆解：三条规则类型
项目README里附了一个示例AGENTS.md，不是模板，是演示格式用的。
1. 开发环境操作
- Use `pnpm dlx turbo run <target>` to jump to a package
- Run `pnpm install --filter <package>` to add the package to your workspace
- Use `pnpm create vite@latest <package-name> -- --template react-ts` to spin up a new React + Vite package
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.每条都给全了命令和参数格式。<package>和<target>是占位符，AI能从上下文中自动替换成真实的值。
2. 测试流程
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <package>` to run every check defined for that package.
- From the package root you can just call `pnpm test`.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<pattern>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <package>`.
- Add or update tests for the code you change, even if nobody asked.重要的一点：规则不仅告诉AI”跑测试”，还给了排查问题的顺序——先看CI配置、然后按包粒度执行、出问题用特定模式跑子步骤、改文件后自动检查lint。
3. PR规范
- Title format: `[<scope>] <description>`
- Always run `pnpm lint` and `pnpm test` before committing.命令和格式绑定。AI生成PR时会自动套用[scope]描述这个标题模板。
为什么AI能执行这些规则
三条特征决定了AGENTS.md不是摆着好看的：
- 直接对应bash命令。AI看到
pnpm vitest run -t "<pattern>"就知道在shell里调什么，不存在歧义。 - 动作和检查绑定。”改完文件后运行lint”这种写法是序列化指令，AI会自动在编辑操作完成后触发。
- 占位符有明确语义。
<package>、<target>、<pattern>这些标记，AI对话上下文中通常能找到值。
示例里没有”注意代码质量”、”提高可维护性”这种废话。每一条都能在一行终端里执行。
我试了下：10分钟解决重复沟通
我有一个pnpm workspaces + turborepo的旧项目，之前用Claude Code的时候，每次开始对话都要手动说明”包管理器用pnpm，构建用turbo，测试用vitest”。
花了十分钟写了个AGENTS.md：
# AGENTS.md
## Dev environment
- Use `pnpm install` to install dependencies
- Use `pnpm dlx turbo run build --filter <package>` to build a package
- Run `pnpm dev` from root to start dev server
## Testing
- Run `pnpm test` from root for all packages
- Use `pnpm vitest run -t "<test-name>"` from package root for single test
## Commit rules
- Title: `[package-name] short description`
- Run `pnpm lint` before commit效果很直接：Claude Code不再问”你用什么包管理器”，读文件后直接跑pnpm dlx turbo run build --filter @my/package。之前每次对话开头要强调的东西，现在不存在了。
两个关键点
规则必须来自真实工作流。如果你实际用yarn + jest + lerna，写pnpm + vitest + turbo就废了。AI执行错的命令比不执行更麻烦。
AGENTS.md不是README的替代。README给开发者和使用者看，讲项目是什么、架构怎么设计、API怎么调用。AGENTS.md只给AI看，讲操作规则。两个文件互补，不要合并。
如果你想体验AGENTS.md项目本身
它附带一个Next.js网站，本地这样跑：
pnpm install
pnpm run dev打开http://localhost:3000看官网介绍。项目的根目录就放了自己的AGENTS.md，AI操作网站代码时会按那里的规则执行。
简评
21814个Star背后是一类很明确的需求：AI编码代理越来越多，但”告诉AI你的项目怎么干活”这件事一直没标准化。一个纯文本文件把这个标准固定下来，低成本，效果好。