告别 README：为什么你的代码库必须立刻增加一个 AGENTS.md？

在软件工程的历史上，总有一些看似微小却具有里程碑意义的改动。

就在上周，顶级开源项目、全球部署量最大的数据库 SQLite 的官方仓库里，悄悄合并了一个看似非常奇怪的提交。他们没有修改核心的 C 语言逻辑，也没有添加新功能，而是在仓库根目录下新增了一个名为 AGENTS.md 的文件。

这个文件的开宗明义第一句话就是：“本文件不是给人类开发者看的。”

它是专门写给指向该代码库的 AI Agent（例如 Claude Code、Cursor、Cline 等工具）阅读的。SQLite 官方甚至立下了规矩：“我们不接受 AI 生成的代码，但我们欢迎且只接受符合本规范的 AI 生成 Bug 报告。”

这绝不是一个随意的猎奇行为。

从写 README.md 给人看，到写 OpenAPI/Swagger 契约给微服务看，再到今天写 AGENTS.md 给大模型看——这是一个标志性的工程范式转移。

一、为什么 Agent 在你的代码里总是“胡作非为”？

在过去的几个月里，我们一直在探讨“AI 编程的幻觉”与“技术债蔓延”的问题。

你一定经历过这样的崩溃瞬间：你只是让本地的 Cursor 或 Claude Code 修复一个路由跳转的 Bug。五分钟后，你发现它“顺手”把你写了一半的鉴权中间件重构了，甚至在 package.json 里擅自引入了三个你根本不需要的 npm 库。

导致这种“越界行为”的根本原因，并不是大模型不够聪明（事实上，Opus 4.8 的智商已经碾压了大多数初级程序员）。其核心病灶在于上下文错位（Context Misalignment）。

人类程序员在阅读 README.md 和审视代码树时，会自动结合工程师常识：

• “这个老文件虽然丑，但是历史包袱，绝对不能动。”
• “这个表名的拼写虽然是个错别字，但整个公司的中台都在用，千万别改。”

但 AI 没有这些暗默知识。当缺乏显式的“护栏（Guardrails）”和系统提示时，Agent 只会基于纯粹的逻辑，去全网寻找它认为的“局部最优解”。这也是为什么它会无所顾忌地进行我们在前两篇文章中提到的“顺向污染”。

二、硬核解构：一份合格的 AGENTS.md 应该写什么？

为了阻止 AI 破坏你的心血，你不能靠祈祷，你必须通过协议级别的契约来约束它。

<figure><img src=“images/01-agents-md-structure.png” alt=“AGENTS.md 面向机器的工程边界契约” /></figure>

一份能真正发挥作用的 AGENTS.md（或 Cursor Rules），通常需要包含以下四个立等可用的核心板块：

1. 代码拓扑声明 (Repository Topology)

不要让 AI 像没头苍蝇一样遍历你所有的文件夹。直接告诉它你的架构地图：

• “MVC 的控制器在 /src/controllers，核心业务逻辑在 /src/domains。”
• “/generated 目录下的所有 TypeScript 类型是由 Prisma 自动生成的，绝对禁止 AI 尝试手动修改它们，否则会引发构建灾难。”

2. 硬性不可侵犯边界 (Hard Boundaries)

明确画出红线，这是约束 Agent “多动症”的关键：

• 禁止引入行为：“未经人类显式授权（Prompt 明确要求），绝对禁止修改 package.json 或 Cargo.toml 引入任何新的第三方依赖库。”
• 写保护区域：“/src/auth (鉴权) 和 /src/billing (支付) 属于高危只读区域，Agent 仅允许执行读取和分析动作。任何针对该区域的修改方案，只能输出为 Markdown 提议，严禁直接生成 .patch 或直接写入。”

3. 验证与测试契约 (Verification Protocol)

这是防止 AI 留下烂摊子就跑的最有效手段，强制约定 Agent 的工作闭环：

• “在修改任何 *.ts 代码后，必须立即在沙箱终端调用 npm run lint 和 npm run type-check。”
• “如果在运行 npm run test:unit 时出现失败，你必须自动捕获错误日志并最多重试 3 次；如果依然失败，必须立即停止修改并向用户报告。”

4. 业务暗知识注入 (Context Injection)

把你平时会在 Code Review 中骂新人的话，提前写给 AI 听：

• “本项目前端使用了全局的 Zustand 状态管理，严禁使用深层的 React Props Drilling 模式。”
• “所有涉及时间戳的存储必须使用 UTC 标准，禁止使用本地时间转换函数。”

三、从纯文本走向真正的“智能体接口”

SQLite 的 AGENTS.md 只是打响了第一枪。

未来，这种面向机器的契约绝不会仅仅停留在 Markdown 纯文本阶段。

随着工具链的演进，我们可以预见，AGENTS.md 很快就会变成一个具有极强约束力的 JSON Schema 或 YAML 文件。它甚至可以通过 CI/CD 流水线，通过静态分析（AST 解析）和代码覆盖率报告，每次提交后自动动态生成。

当下一个子 Agent 被唤醒并接入这个仓库时，它将在握手的最初几毫秒内，读取这份协议，瞬间获得一份精确的、带有隔离墙和警示牌的“3D 架构地图”。

我们相信，在接下来的几个月内，GitHub、GitLab 等平台将会在基础设施层面原生支持解析仓库根目录的 AGENTS.md，并在每次你唤起 Copilot 或第三方 Agent 时，自动作为顶级 Context 注入。

结语：新时代的开发者素养

当写代码这件事情本身被大模型接管后，人类开发者的核心工作，其实已经变成了**“系统定义与边界控制”**。

在过去，我们说“一段好的代码，是写给未来的同事看的”。 但在零边际代码成本的今天，“一段好的代码，必须配套清晰的界碑，是写给下一秒即将涌入你的仓库里的数百个并发子 Agent 看的。”

不要再抱怨 AI 总是弄乱你的项目了。

今天，就在你的仓库根目录下，新建一个 AGENTS.md 吧。给那匹狂奔的野马，套上缰绳。