痛点：AI 写代码为什么总在同一个地方翻车

用 Cursor、Windsurf 或者 Claude Code 写项目的人，几乎都经历过同一种崩溃：AI 输出一整段代码，你复制粘贴跑起来——构建报错、测试红屏、依赖装错位置。问题不在 AI 智力，而在于它根本不知道你这个项目的「潜规则」。

AGENTS.md 就是放在项目根目录的一个 Markdown 文件，专门写给 AI 看，告诉它怎么构建、怎么测试、遵循什么规范。README.md 是写给人类看的，里面塞满了项目介绍、贡献指南、品牌故事。AI 读到这些内容，就像一个新人入职第一天被塞了一本公司宣传册，然后被要求立刻写代码——它知道公司做什么，但不知道构建命令、不知道测试怎么跑、不知道 ESLint 规则是什么。结果就是每次都要在对话里反复纠正：「用 pnpm 不是 npm」「测试在 packages/web 下」「别忘了跑 lint」。这些纠正重复一百遍，项目还是乱。

接单场景的损失更直接：你接了一个 Next.js + Prisma 的外包，用 Cursor 帮你加速，结果 AI 用 npm install 装依赖，pnpm 的 workspace 配置全废；它不知道你的数据库 schema 在哪个目录，生成的 migration 文件直接报错。客户催交付，你花三小时 debug AI 生成的代码——这钱赚得太憋屈。

AI 不知道项目潜规则的 3 个典型翻车场景：① 包管理器搞错（项目用 pnpm，AI 默认 npm install），依赖装到错的位置，workspace 配置失效；② 测试入口找不到（项目测试在 packages/web 下，AI 在根目录跑 pnpm test，报「找不到测试文件」）；③ 代码风格不一致（项目用 ESLint + Prettier，AI 生成的代码缩进、引号全错，CI 直接挂掉）。

机会：AGENTS.md 把「人类文档」和「机器文档」彻底切开

GitHub 上的开源项目 AGENTS.md（仓库地址 github.com/agentsmd/agents.md，截至 2026-08-25 约 2.4 万 stars）解决的就是这个问题。它的核心思路极其简单：在项目根目录放一个 Markdown 文件，专门告诉 AI 如何构建、如何测试、遵循什么代码风格。

这不是 README 的替代品，而是补充。README 服务于人类贡献者，AGENTS.md 服务于 AI 智能体。两者职责清晰，互不干扰。

据源帖称，AGENTS.md 已被数万个开源项目采用（具体数字待核），覆盖 VS Code、Cursor、Windsurf、Aider、GitHub Copilot 等主流 AI 编程工具（核证结论确认）；此外据社区反馈，OpenAI Codex、Google Jules 等工具也提供支持（⚠️未核实）。你现在不学，等于让 AI 用方言跟你对话。

路径一：手写一份最小可用的 AGENTS.md

成本极低。新建文件，写三段就够用。

前置认知：以下示例用 pnpm（比 npm 更省磁盘、支持 monorepo workspace），turbo 是 monorepo 任务编排工具，--filter 参数指定只对某个子包生效，避免影响整个仓库。

第一段「Dev environment tips」：告诉 AI 项目用什么包管理器、怎么跳转子包、怎么新建模块。例如官方示例里的：

• pnpm dlx turbo run where <project_name> —— 直接跳到指定子包目录，不用 ls 一个个翻
• pnpm install --filter <project_name> —— 只装某个子包的依赖，不动整个 monorepo
• pnpm create vite@latest <project_name> -- --template react-ts —— 新建一个带 TypeScript 检查的 React + Vite 子包

这些命令 AI 自己猜不到，但你写下来它就照做。

第二段「Testing instructions」：告诉 AI 测试怎么跑、CI 计划在哪、提交前必须跑哪些检查。官方示例包含：

• pnpm turbo run test --filter <project_name> —— 跑指定子包的全部检查
• pnpm vitest run -t "<test name>" —— 只跑匹配某个名字的单个测试
• 「Fix any test or type errors until the whole suite is green」—— 不全绿不许停
• 「Add or update tests for the code you change, even if nobody asked」—— 最后这句是关键，不写的话 AI 经常偷懒不写测试

第三段「PR instructions」：规范提交标题格式、强制跑 lint 和 test。官方示例是 Title format: [<project_name>] <Title>，以及「Always run pnpm lint and pnpm test before committing」。

这三段加起来不到 50 行，但能让 AI 生成代码的一次通过率显著提升（据社区反馈，具体数字待核）。

路径二：在大型 monorepo 中嵌套使用

如果你接的是企业级项目，代码库是 monorepo 结构（多个相关项目放在同一个 Git 仓库里管理，比如前端、后端、共享代码各一个子目录），单一 AGENTS.md 不够用。AGENTS.md 支持嵌套：在每个子目录放一份专属的 AGENTS.md，AI 会自动读取「最近的那一份」。

实操做法：根目录的 AGENTS.md 写全局规范（包管理器、CI 流程、安全注意事项），然后在 packages/web/、packages/api/、packages/shared/ 各放一份，写这个子包特有的构建命令、测试入口、特殊依赖。例如前端包需要写「组件库用 shadcn，样式用 Tailwind，图标用 lucide-react」；后端包需要写「数据库 migration 用 Prisma，API 路由在 src/routes 下，鉴权用 JWT」。

AI 在子目录工作时，会自动加载最近的 AGENTS.md，优先级高于根目录。这意味着同一个项目里，前端 AI 助手和后端 AI 助手能拿到完全不同的指令，不会互相串台。

路径三：把它变成接单的差异化卖点

现在 AI 接单市场已经卷成红海——人人都会用 Cursor，但交付质量参差不齐。如果你能在投标书里写一句「本项目已配置 AGENTS.md 标准文档，AI 辅助开发遵循项目规范」，中标率会显著高于只会说「我用 AI 写代码」的同行。

具体打法：接到单后，先花 30 分钟读懂客户的项目结构，然后写一份定制化的 AGENTS.md。这份文档本身就是交付物的一部分——客户拿到后，未来自己用 AI 维护代码也会更顺畅。

把 AGENTS.md 配置服务单独标价（参考报价，需根据当地市场调整）：基础版 500 元（单文件配置 + 一份 README 说明），企业版 3000 元（monorepo 嵌套 + 安全规范 + 团队培训）。交付物清单：① 定制 AGENTS.md 文件 ② 30 天微信答疑 ③ 一段 10 分钟的录屏培训。适用场景：客户已有 Cursor/Windsurf 会员但用不出效果。不适合：客户还在用纯人工开发、没引入 AI 工具。

案例：AGENTS.md 的兼容性护城河

AGENTS.md 采用 MIT 协议（素材包确认），由社区维护（具体治理结构待核），官网是 agents.md。

兼容性是它最大的护城河：核证结论确认 VS Code、Cursor、Windsurf、Aider、GitHub Copilot 均支持读取 AGENTS.md；据社区反馈，OpenAI Codex、Claude Code、Gemini CLI、Google Jules 等工具也提供支持（⚠️未核实）。这意味着你写一份文件，主流 AI 助手都能用——不需要为每个工具单独写配置。

对比一下其他方案：Cursor 的 .cursorrules 只对 Cursor 有效，换 Windsurf 就失效；Claude Code 的 CLAUDE.md 只服务 Claude；GitHub Copilot 的指令系统又是另一套。AGENTS.md 的「一次编写，到处运行」特性，是它短期内被广泛采用的根本原因。

工具迁移成本归零。今天你用 Cursor，明天换 Windsurf，AGENTS.md 直接复用，不需要重写规则。

行动号召：今晚就给项目加一份机器手册

5 分钟行动清单：① 打开项目根目录 ② 新建 AGENTS.md ③ 复制官方模板（github.com/agentsmd/agents.md）④ 填入三项命令（构建、测试、lint）⑤ 下次让 AI 写代码时观察效果。

如果你用的是 monorepo，今晚额外花 20 分钟给每个子包加一份嵌套配置。明天开工时你会发现，AI 生成的代码不再需要你反复纠正。

AGENTS.md 是目前 ROI 最高的 AI 编程配置——30 分钟投入，换每月数小时的 debug 时间。