24 August, 2025

AGENTS.md：统一编码助手指令文件的新标准

笔记

TL;DR

从此刻起，你的项目中除了 README.md 文件外，可能还会包含另一个 markdown 文件：AGENTS.md

README.md：为人类设计，通常提供如项目介绍、安装指南、使用示例等信息。
AGENTS.md：为 Coding Agents 设计，提供额外的详细信息，如环境搭建、构建步骤、测试方法、代码规范、安全注意事项等。

如果你经常在多种编程助手间来回切换，肯定会我将要说的问题深有体会。通常如果想要编程助手更好的工作、输出更高质量的代码，我们需要在项目中为其提供 instructions（指令 - 系统提示词）文件。比如 .cursor/rules、.clinerules、.github/copilot-instructions.md、claude.md、gemini.md。这些文件的内容通常类似，但各自的文件名和位置不同。即使类似 Cline、Roo Code、Kilo Code 这类同出一脉的编程助手，他们的目录名也各不相同。更不同说不同的编程助手了。

通常我的做法是使用软连接。首先创建一个统一的 instructions 文件，再通过软连接将 .clinerules 和 .cursor/rules、.github/copilot-instructions.md 都链接到同一个文件。

你也可以使用 intellectronica/ruler，ruler 可以将同一份 instructions 文件 .ruler/ 分发给多个编程助手，并更新 .gitignore 文件。

久而久之，你将会收获一个混乱的项目目录（再加上 MCP 服务器的管理文件），即使用上软链接或者 ruler（只是降低了维护成本）。

image from @shadcn

AGENTS.md

天下大事，分久必合。合久必分。

Google、OpenAI、Factory、Sourcegraph 和 Cursor 等公司联合推出了 AGENTS.md，一个简单开放的标准，旨在为编码代理提供一种可预测的方式来理解和操作软件项目。

说人话就是，项目目录不会再混乱了。

它的内容类似于 README.md，但更注重于编程助手的使用和配置。通常包含：

项目概述
构建和测试命令
代码风格指南
测试说明
安全注意事项

目前主流的编程助手均都支持 AGENTS.md。

如何使用

非常简单，在项目的根目录创建 AGENTS.md 文件即可，内容使用标准 Markdown 格式。

示例：

# 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.