📜用一个文件治理你所有的智能体 · 掌握 AGENTS.md

你需要它的那个确切时刻

这种需求会在这一天冒出来:你的项目有了规则,而且不止一个人工大脑要经手它。可能是你用 Claude Code 来搭建、用另一个工具来审查,偶尔还开个 Cursor 或 Copilot 处理点零碎活儿。也可能是明天你为了省点额度而换个智能体。所有这些情况里,都有一些不写在代码里的知识:环境怎么启动、用什么命令跑测试、哪些文件夹是神圣不可侵犯的、你希望保存信息(commit)的时候怎么写。这些知识如今住在你的脑子里——而每个新来的智能体都从零开始,对这些一无所知。

它诞生于哪种痛 · 蒸发掉的上下文

这种痛是无声的,而且是分期付款式的。你今天跟 AI 的这场会话对你的项目了如指掌,因为是你花了好几个小时一点点讲给它听的。可这些知识哪儿都没存下来:当你关掉对话,它就蒸发了。明天你开一场新会话——或者换个模型来少花点钱——你又回到了起跑线,再一次重复 “记住测试要用这个命令跑”、“别碰支付那个文件夹”、“commit 要用这个格式”。

为什么会这样?因为每个智能体启动时都是瞎的:它只看得见你的代码,看不见你的规则和你的习惯。而由于每个工具都用各自的方式保存指令——Claude 存一个文件、Cursor 存另一个、Copilot 又存一个——你就得把同样的知识写上三四遍。这是一团会自己走样的乱麻:你在一个文件里改了条规则,却忘了在其他文件里同步。

AGENTS.md 到底是什么?(说人话)

AGENTS.md 就是一份给智能体看的 README。 就像老一辈的 README 会告诉人类你的项目是干嘛的,AGENTS.md 会告诉任何一个写代码的 AI,在这个项目里该怎么行事。它是一个你放在项目根目录里的纯文本(Markdown)文件,就这么简单。没有奇怪的配置、没有代码、没有繁文缛节。

让它变强大的不是格式——而是它已经成了一个如今被 25 种以上不同工具读取的开放标准:OpenAI Codex、Cursor、GitHub Copilot、Gemini CLI、Google Jules、Aider、Zed、Windsurf、Devin、JetBrains Junie、Warp、goose 等等。已经有超过 60,000 个开源项目在用它。你把规则写一次,它就能配合你今天用的 AI,也配合你明天要用的 AI。你不再被绑死在某一个工具上了。

真实的解剖图 · 它里面装了什么

好消息来了:你不用去背什么死板的格式。 AGENTS.md 就是普普通通的 Markdown——用 # 写标题、用短横线写列表、写文字。它不需要那种塞满冒号和花括号的技术头部(程序员管那叫 YAML frontmatter):这些统统不是必需的。你用任意你喜欢的名字写成一节一节,智能体就读你写给它的东西。就这样。

话虽如此,几乎每份好的 AGENTS.md 都会包含五大块——因为它们恰好就是那些会在会话之间蒸发掉的知识。把它们想成岗位手册的五个抽屉:

习惯 · 写一次,让它保持鲜活

这份资源不是那种每天都要用的——而是那种认真做好一次、时不时润色一下的。这里的坚持不在于频率,而在于两个你绝不能把它忘掉的具体时刻:

几乎没人讲清楚的那个细微之处 · AGENTS.md vs CLAUDE.md vs .cursorrules

这里就是大家容易绕晕的地方,所以我们说清楚。在这个标准出现之前,每个工具都发明了自己的规则文件:Claude Code 读一个 CLAUDE.md,Cursor 以前读一个 .cursorrules,每个都这样。明摆着的问题:如果你用三个工具,你就得维护三个文件,里面装着同样的知识,自己就走样了。AGENTS.md 的诞生正是为了终结这种混乱:一个所有工具都读取的单一事实来源。

# CLAUDE.md

# Las reglas del proyecto viven en AGENTS.md (fuente única).
# Claude Code las carga con esta línea de importación:

@AGENTS.md

# Debajo, solo lo específico de Claude Code que NO aplica
# a los demás agentes (si es que hay algo).

什么时候用哪个?简单:凡是你想让任何一个智能体都遵守的,都放 AGENTS.md(你 95% 的规则)。某个工具自己的文件(CLAUDE.md、.cursorrules)只放那些该工具独有的东西——只有它才懂的命令、只对它管用的设置。要是拿不准,就放 AGENTS.md。记住这条心法:默认写给所有人;写给某一个只是例外。

正反两面 · 那如果 spec 已经说了要建什么呢?

如果你是从“在动手之前先写一份规格说明(spec)”(也就是你想让它建成什么样)的思路过来的,那 AGENTS.md 就是这对搭档的另一半——而且它们不冲突,是互补的。spec 管建什么:功能、目标、结果。AGENTS.md 管任何智能体在建的过程中怎么行事:用什么命令、什么规则、什么不能碰。一个是建筑的图纸;另一个是施工现场的安全规范。两个你都需要。

大师级 prompt · 生成你完美的 AGENTS.md

捷径来了。你不用手写这个文件,也不用去琢磨每一节:你在你的项目里面把这个 prompt 丢给你的编码智能体,它就会看着你代码的真实结构替你起草。你只管审阅和调整。原样复制,把方括号里的内容填上你知道的,然后让它去干活:

我想在我项目的根目录里创建一个 AGENTS.md 文件:就是那个被 AI 编码工具读取的开放标准(agents.md)的"给智能体看的 README"。它是纯 Markdown,不带 YAML 头部。请用简单的语言引导我,假设我不是程序员。

首先,真正地探索我的项目(查看文件夹结构、package.json 或其等价物,以及它是怎么组织的),这样才不会瞎编任何东西。然后用干净的 Markdown 起草一份包含以下几节的 AGENTS.md:

1. 项目概述 —— 用 2 到 3 句话说明它是什么、用了什么技术(从代码里推断)。
2. 准备环境 —— 从零安装和启动项目的真实命令。
3. 怎么跑测试 —— 测试和错误/类型检查的确切命令,好让任何智能体在把成果当成合格之前先验证自己的工作。
4. 风格规则 —— 代码所用的语言,以及你检测到的约定(引号、命名、格式)。
5. commit 和 PR —— 这是我的 commit 信息格式:[描述它,或者告诉我如果我没有一个,并提出一个好的方案]。
6. 边界 · 什么不能碰 —— 把这些神圣的文件夹/文件标为未经明确允许不可触碰:[在这里列出敏感的东西:支付、密钥、配置、迁移……凡是你有的]。讲清楚智能体在修改它们之前必须停下来并询问。

起草时的规则:
- 只陈述你能通过查看我的代码来核实的事情。如果有什么你不知道,放一个 [待确认] 标记,而不是把它编出来。
- 要简洁、可执行,不要写成小说。一个智能体在干活之前会把它整个读完。
- 如果我的主力工具已经有它自己的规则文件(比如 CLAUDE.md),不要重复内容:让那个文件用一行导入 AGENTS.md,并把 AGENTS.md 留作我唯一的事实来源。

完成后,把整个文件展示给我,并用一句话解释你在每一节里放了什么,好让我审阅。

最省事的路 · 用聊天 vs. 手动

和整个系列一样,做这件事有两种方式,而且哪一种都不强迫你去碰终端,除非你想碰:

如果你走手动这条路,这就是一份可以直接复制、随手填写的最小模板。随你喜欢改动它:记住,没有强制的格式。

# AGENTS.md

## Resumen del proyecto
[Qué es y con qué está hecho. 2-3 frases.]

## Preparar el entorno
[Comandos para instalar y arrancar de cero.]

## Cómo se prueba
- Pruebas: [comando exacto]
- Chequeo de errores/tipos: [comando exacto]
> Corre esto y déjalo en verde antes de dar por terminado un cambio.

## Reglas de estilo
[Idioma del código, convenciones de nombres/formato.]

## Commits y pull requests
[Tu formato de mensajes de commit. Ejemplo de uno bueno.]

## Límites · NO tocar sin permiso
- [Carpeta o archivo sagrado 1 — por qué es sensible]
- [Carpeta o archivo sagrado 2]
> Ante cualquiera de estos: PARA y pregunta antes de modificar.

黄金日常 · 你带走的总结