如何编写 AGENTS.md 文件，让任何 AI 编程智能体都能理解你的项目

如果你曾眼睁睁看着一个 AI 编程智能体运行了错误的测试命令、以你项目禁止的风格格式化代码，或者重新造出一个早已存在的辅助函数，那么解决之道通常不是换一个更聪明的模型——而是上下文。AGENTS.md 是为智能体提供这种上下文的标准方式，而且它几乎在所有工具中都能奏效。

AGENTS.md 究竟是什么

AGENTS.md 是“智能体版的 README”：一个你放在仓库根目录的纯 Markdown 文件，用来告诉 AI 编程工具你的项目是如何运作的（agents.md）。它不是一种新的配置语言——没有必填字段，也没有特殊语法。你可以随意使用任何 Markdown 标题。

这一格式之所以重要，是因为它真正做到了跨工具通用。截至 2026 年年中，它已被 OpenAI Codex、GitHub Copilot、Cursor、Windsurf、Devin、Aider、Zed、VS Code、JetBrains Junie 等数十种工具原生读取——超过 28 种工具、6 万多个开源仓库（agents.md；Codersera）。它现在由 Linux Foundation 旗下的 Agentic AI Foundation 托管，与 Anthropic 的 Model Context Protocol 并列。Claude Code 也会读取 AGENTS.md，不过它更丰富的原生格式仍是 CLAUDE.md（DeployHQ）。

一个文件，就能让你的大多数工具行为保持一致。

为什么一个文件胜过在聊天里反复重复

当你把指令粘贴到一条聊天消息里时，它们只在这一次对话中存活。下一个会话——或者下一位队友，又或者一个整夜替你跑任务的云端智能体——都要从零开始。而 AGENTS.md 会在每次运行开始时自动加载，因此你的约定是默认被强制执行的，而不必取决于你是否记得提起它们。这正是关键所在：把项目知识从你的脑子里、从一次性的聊天里搬出来，放进一个工具每次都会读取的文件中。

该往里面写什么

想想一位能干的新队友在第一天需要知道什么——那正是智能体所需要的。最有用的部分包括：

• 项目概览 —— 用一段话说明这是什么以及技术栈。
• 安装与构建命令 —— 用于安装、运行和构建的确切命令。
• 测试 —— 如何运行测试，以及“变更完成前测试必须通过”这条规则。
• 代码风格 —— 格式化工具、linter、命名约定，以及应优先或避免的模式。
• 提交与 PR 规范 —— 消息格式、分支规则、哪些内容不要改动。
• 陷阱 —— 任何不那么显而易见、容易绊住人的地方。

要具体。“写出干净的代码”对智能体毫无意义。“使用 pnpm，而非 npm；完成前先运行 pnpm test；绝不要编辑 src/generated/ 中的文件”才是可执行的。

一个具体示例

下面是一个针对典型 Web 应用的精简版 AGENTS.md：

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

把它交给 Claude Code、Cursor 或 Copilot，每一个都会拾取到同样的规则。

单体仓库（Monorepo）：使用嵌套文件

在单体仓库中，你既可以在根目录放一个 AGENTS.md，也可以在每个包里各放一个。当智能体在某个子目录内工作时，最近的那个文件优先（agents.md）。把共享的约定放在根目录，把各个包特有的命令放在嵌套文件里，这样一来，编辑 packages/api/ 的智能体就能自动获得该包的构建与测试命令。

AGENTS.md、CLAUDE.md 与 Cursor 规则之比较

你可能已经有了一些工具专属的文件，比如 CLAUDE.md 或 .cursor/rules。你不必把它们丢掉。实践中，团队会把共享的、与工具无关的约定放进 AGENTS.md——那些每个智能体都需要的内容——并把工具专属的额外内容留在支持更丰富功能的那款工具的原生文件里（DeployHQ）。以 Claude Code 为例，它两者都读取，其中 CLAUDE.md 是其表达力更强的格式。一种常见做法是保留一份权威的 AGENTS.md，在某款工具需要自己的文件时，让那个文件指向 AGENTS.md，从而做到单一事实来源。先从 AGENTS.md 开始；只有当你需要某款工具独有的功能时，再去动用它专属的文件。

保持简短而具体

越多并不越好。一个把你整套风格指南都复述一遍的巨型 AGENTS.md，会争夺模型的注意力，并淹没那些真正重要的规则。目标应当是那少数几件——若无指引智能体就会出错的事：那个不显而易见的命令、那个不该碰的目录、你代码库偏好的那种模式。如果一条规则从代码里就已经一目了然，那你多半就不必把它写下来。

如何让它持续有用

只有当 AGENTS.md 始终真实可信时，它才配得上它的价值。把它当作代码来对待：当某个命令或约定发生变化时，在同一次提交里更新这个文件。而当一个智能体第二次犯下同样的错误时，不要只在聊天里纠正它——把规则写下来。仅这一个习惯，就能把每一次失误变成一处永久的修复，而它也是你能为让 AI 智能体在你项目上变得可靠所做的、单位投入回报最高的一件事。