AGENTS.md 完整指南：3 步教 AI 编码助手遵守项目规则
项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md 多包 monorepo 里，你是不是每次都得叮嘱 AI："别跑生产构建、改完先跑测试、提交标题要带前缀"？AGENTS.md 就是为这类项目准备的开放格式：一个放在仓库根目录的 Markdown 文件，把这些"不成文规矩"一次性讲给 AI 编码助手听，从此不用反复口头交代。
🚧 AI 为什么老在同一个项目上踩同样的坑
让你头疼的，往往不是 AI 不会写代码，而是它不知道你这边的约定：
- 选错了构建工具，或者随手敲一条项目里根本不存在的命令
- 改完代码不跑测试，或者在没动依赖前急着验证
- 迭代中途直接跑生产构建，热重载整个废掉
这些规矩你心里有数，但从来没写下来。AI 看不见你脑子里的东西。
AGENTS.md 到底是什么？
官方定义是：一种用于指导编码助手的简单、开放格式。说人话一点，它就是递进 AI 的新员工手册。
本仓库 README 里的说法更直接：把 AGENTS.md 当作给 agent 看的 README——一个专属的、位置可预期的地方，专门放上下文和指令。人看 README，AI 看 AGENTS.md，各干各的，互不干扰。
整个文件就是纯 Markdown，没有强制结构。写法上有个诀窍：条目越具体、越可执行，AI 越不容易跑偏。
核心内容拆解：AGENTS.md 里到底写什么
开发环境提示
README 示例的第一节 "Dev environment tips" 就是在教 AI 命令都藏在哪：跳去某个包用什么命令、怎么把包挂进工作区、新建包用什么模板。这类"怎么跑起来"的信息，是 AI 最容易猜错的部分。
测试与提交要求
示例里的 "Testing instructions" 和 "PR instructions" 把验收标准一条一条钉死：合并前相关包的测试必须全绿、提交标题写成 [项目名] 标题 的格式、提交前先跑 lint 和 test。把要求写成单行条目，比事后口头解释省事得多。
本仓库自带的 AGENTS.md：一份现成范本
这个仓库自己也放了一份，内容非常实在，你可以直接参考 AGENTS.md：
- 迭代期间只用开发服务器，AI 会话中禁止跑生产构建——那会污染
.next目录并干掉热重载 - 增删依赖后必须同步锁文件并重启开发服务器
- 新代码优先 TypeScript，组件样式尽量和组件同目录放
注意它的行文方式：每条都能直接照做，还附了对应命令。
3 步上手：从 0 到第一份 AGENTS.md
- 新建文件：仓库根目录建一个
AGENTS.md，纯 Markdown 即可 - 补三块内容：开发环境怎么起、测试怎么跑、代码提交前必须满足什么
- 先让 AI 干一轮活：哪里踩坑就把哪条规矩补进文件，越用越全
项目还自带一个 Next.js 官网，用来讲解目标并展示各家项目的真实写法，站点源码在 pages/index.tsx。
适合谁用，以及它替代不了什么
值得写：
- monorepo、构建和测试命令多的项目
- AI 助手经常参与改代码的仓库
- 希望人和 AI 遵守同一套规范的团队
注意边界：
- 它是"引导"不是"强制"，AI 遵守程度取决于你写得是否具体
- 替代不了 README——README 仍然面向人类读者
- 不是一次写完就完事：命令和流程变了要同步更新，过期的指引会变成新的坑
一句话总结
AGENTS.md 没有给 AI 增加什么超能力，它只是把项目的"潜规则"落到纸面，放到 AI 找得到的位置——然后你就少了一半的返工。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
