# 把它写下来给机器看 现在每个正经的编程智能体在动你的仓库之前，都会先读一个纯文本文件：AGENTS.md。截至 2026 年初，它已被 Claude Code、OpenAI 的 Codex CLI、Cursor、Aider、Devin、GitHub Copilot、Gemini CLI、Windsurf 和 Amazon Q 原生读取——这是业界目前最接近通用智能体指令格式的东西。它是当下你在 AI 编程上能花出去回报最高的一小时，可几乎没人去做。这篇讲清楚里面写什么、为什么管用。 - **Author:** Fedor Chishchin - **Published:** 2026-06-13 - **Tags:** methodology, ai-native - **Source:** https://fedorthinks.com/zh/blog/write-it-down-for-the-machine --- 要让 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 原生读取](https://blog.buildbetter.ai/agents-md-complete-guide-for-engineering-teams-in-2026/)—— 这是业界目前最接近通用编程智能体指令格式的东西。一个文件，几乎每个打开你仓库的智能体都会先读它。 让我替「真的去写它」辩护一下，因为这笔杠杆的回报严重不对称。 ## 它到底是什么，说白了 `AGENTS.md` 是一个放在项目根目录的 Markdown 文件。它就是你留给一个能干但从没见过你代码库的新外包同事的便条：怎么构建、怎么跑测试、有哪些约定、什么别碰。智能体在动手之前会读它，并把它当作长期生效的指令——于是你只把上下文写一次，而不用在接下来整个项目里把它一遍遍敲进每条提示词。 整个窍门就这么简单。它不是什么新框架，也不是什么巧妙的提示词。它就是 [把你对自己项目已经清楚的那些事写下来](https://blog.getbind.co/context-engineering-in-2026-the-complete-developers-guide/)，让机器也知道。 ## 为什么它这么管用 智能体出错不是因为蠢。是因为它在盲打——它看不见你团队里每个人靠耳濡目染吸收的那些不成文规矩。智能体不知道你永远用 `pnpm`、从不用 `npm`。它不知道那个谁都不敢不经评审就改的模块。它不知道你的测试在任何东西上线之前必须先过覆盖率门槛。于是它去猜，而其中三分之一的猜测是错的。 一份好的 `AGENTS.md` 把猜测去掉了。这背后的道理和[规格胜过提示词](/blog/the-spec-is-the-source)是同一个：耐用、可复用的产物是写下来的上下文，不是用完即弃的指令。而且它会复利——每一次智能体运行，跨每一个工具，在每一条分支上，都从同一份共享的理解出发，而不是从零开始。 ## 里面到底写什么 写短、写具体。真正管用的那种读起来像一张清单，不像一篇作文： - **怎么构建、怎么运行。** 确切的命令——安装、开发服务器、构建。把 `pnpm` 还是 `npm`、正确的 Node 版本、任何不显而易见的配置步骤都讲清楚。 - **怎么测试。** 测试命令、覆盖率底线、「提交前每道门槛都得是绿的」。当智能体能自己跑测试、[亲眼看到真实的报错](/blog/give-your-agent-the-error)时，它有用得多。 - **重要的约定。** 命名、lint/格式规则、「跟周围的代码保持一致」。那些评审人本来会打回来的东西。 - **什么别碰。** 生成的文件、那一个脆弱的模块、密钥，以及任何「好心帮你重构了一下」就是灾难的地方。 - **项目的样子。** 一行字的地图，说明东西都在哪儿，省得智能体每接一个任务都要逆向推你的结构。 哲学就别写了。智能体不需要你的使命宣言；它需要命令、约束，以及那些地雷在哪。 ## 归根结底 我们在提示词上花了大量精力，可提示词是一次性的、用完就没；而对那个唯一属于整个项目、能一直留存的产物，我们几乎不上心。`AGENTS.md` 从一个各家工具自玩的小花招翻身成近乎通用的标准，恰恰是因为它解决的是真问题：智能体在盲打，而解法就是别再让它去猜你早就知道的东西。 所以下次把智能体指向你的仓库之前，花上那一小时。写下怎么构建、怎么测试、规则是什么、什么别动。这是少见的那种 AI 建议：几乎不花成本，在你会用到的每个工具上都管用，而且在每一次运行里都给你回报。把它写下来给机器看——它正在读呢。