把它写下来给机器看

要让 AI 编程智能体干得更好，最有用的一招不是更好的提示词，也不是更强的模型。是仓库根目录下一个叫 AGENTS.md 的纯文本文件——而大多数在用智能体的人，到现在都还没写过一个。

为什么它现在这么重要。一年前，每个工具都有自己专属的文件——.cursorrules、CLAUDE.md、一份 Copilot 配置、Devin 又想要别的。你的项目约定要么写五遍，要么干脆一遍都不写。那种日子过去了。截至 2026 年初，AGENTS.md 已被 Claude Code、OpenAI 的 Codex CLI、Cursor、Aider、Devin、GitHub Copilot、Gemini CLI、Windsurf 和 Amazon Q 原生读取—— 这是业界目前最接近通用编程智能体指令格式的东西。一个文件，几乎每个打开你仓库的智能体都会先读它。

让我替「真的去写它」辩护一下，因为这笔杠杆的回报严重不对称。

它到底是什么，说白了

AGENTS.md 是一个放在项目根目录的 Markdown 文件。它就是你留给一个能干但从没见过你代码库的新外包同事的便条：怎么构建、怎么跑测试、有哪些约定、什么别碰。智能体在动手之前会读它，并把它当作长期生效的指令——于是你只把上下文写一次，而不用在接下来整个项目里把它一遍遍敲进每条提示词。

整个窍门就这么简单。它不是什么新框架，也不是什么巧妙的提示词。它就是 把你对自己项目已经清楚的那些事写下来，让机器也知道。

为什么它这么管用

智能体出错不是因为蠢。是因为它在盲打——它看不见你团队里每个人靠耳濡目染吸收的那些不成文规矩。智能体不知道你永远用 pnpm、从不用 npm。它不知道那个谁都不敢不经评审就改的模块。它不知道你的测试在任何东西上线之前必须先过覆盖率门槛。于是它去猜，而其中三分之一的猜测是错的。

一份好的 AGENTS.md 把猜测去掉了。这背后的道理和规格胜过提示词是同一个：耐用、可复用的产物是写下来的上下文，不是用完即弃的指令。而且它会复利——每一次智能体运行，跨每一个工具，在每一条分支上，都从同一份共享的理解出发，而不是从零开始。

里面到底写什么

写短、写具体。真正管用的那种读起来像一张清单，不像一篇作文：

• 怎么构建、怎么运行。 确切的命令——安装、开发服务器、构建。把 pnpm 还是 npm、正确的 Node 版本、任何不显而易见的配置步骤都讲清楚。
• 怎么测试。 测试命令、覆盖率底线、「提交前每道门槛都得是绿的」。当智能体能自己跑测试、亲眼看到真实的报错时，它有用得多。
• 重要的约定。 命名、lint/格式规则、「跟周围的代码保持一致」。那些评审人本来会打回来的东西。
• 什么别碰。 生成的文件、那一个脆弱的模块、密钥，以及任何「好心帮你重构了一下」就是灾难的地方。
• 项目的样子。 一行字的地图，说明东西都在哪儿，省得智能体每接一个任务都要逆向推你的结构。

哲学就别写了。智能体不需要你的使命宣言；它需要命令、约束，以及那些地雷在哪。

归根结底

我们在提示词上花了大量精力，可提示词是一次性的、用完就没；而对那个唯一属于整个项目、能一直留存的产物，我们几乎不上心。AGENTS.md 从一个各家工具自玩的小花招翻身成近乎通用的标准，恰恰是因为它解决的是真问题：智能体在盲打，而解法就是别再让它去猜你早就知道的东西。

所以下次把智能体指向你的仓库之前，花上那一小时。写下怎么构建、怎么测试、规则是什么、什么别动。这是少见的那种 AI 建议：几乎不花成本，在你会用到的每个工具上都管用，而且在每一次运行里都给你回报。把它写下来给机器看——它正在读呢。