AGENTS.md 完整教程：5 步让 AI 编码助手听懂你的项目

AGENTS.md 完整教程5 步让 AI 编码助手听懂你的项目【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md上次让 AI 编码助手写个接口代码连着三次被打回 review它用 npm 而项目装的是 pnpm测试没跑文件命名也不符合约定。后来我在仓库根目录放了一个 40 行的 AGENTS.md返工次数明显降下来了。这就是面向编码代理的开放规范文件格式 AGENTS.md下面带你按写法分三步过一遍。什么是 AGENTS.mdAI 最先读的规范文件AGENTS.md 是放在项目根目录的一个 Markdown 文件可以理解为写给编码代理的 README。它没有必填字段也没有固定模板AI 会把整份文件当纯文本来读你写什么它就遵循什么。它不替代 READMEREADME 面向人讲项目背景AGENTS.md 面向 AI讲那些人类很少看、但 AI 每次干活都得守的内容比如构建命令、测试流程、代码约定。差异很直观没有配置时AI 每次自己猜包管理器、猜风格写好一份 AGENTS.md 之后它从第一行代码开始就跟着你的目录结构和质量标准走。还有两个细节值得知道monorepo 里可以在每个子目录各放一份离被修改文件最近的那份优先写在文件里的测试命令AI 会主动帮你执行。从零写第一份 AGENTS.md 的三步个人项目 20 行以内就够团队规模上去了再补上 PR 约定和命令速查表别一上来就写手册。第一步写上 AI 能直接用的环境和命令最有价值的就是 setup 命令依赖怎么装、服务怎么起、测试怎么跑。可以从 README.md 里提炼关键步骤不用复述全部说明。# AGENTS.md ## Setup commands - Install deps: pnpm install - Start dev server: pnpm dev - Run tests: pnpm test第二步写上编码与测试规范第二层是风格和质量标准这是 AI 和人最容易不一致的地方引号风格、文件命名、提交前测试必须全绿。可以看看本仓库的 AGENTS.md 怎么写的比如它明确禁止在代理会话里跑生产构建命令只允许npm run dev保证热更新一直可用。## Code style - TypeScript strict mode - Single quotes, no semicolons - Run pnpm lint before commit第三步补上新功能与代码审查的场景化规则最后给高频场景补充具体行为写得越具体AI 越少发挥。可以参照 components/ 目录约定新组件放哪、文件怎么命名把这类隐式知识显式写出来。## PR instructions - Title format: [module] change description - Run lint and tests, green before commit - Never run npm run build during agent sessions两个真实工作流AGENTS.md 如何生效工作流一开发新功能触发条件你让助手新增一个搜索框组件。AI 动手前先读 AGENTS.md 的 Setup commands知道用 pnpm 装依赖、用 dev 命令起服务接着 Code style 一节生效它按 TypeScript 和既定命名产出代码。产出结果代码直接落在约定目录里风格与现有文件一致你不用返工改格式。工作流二合并前自检触发条件你让助手提交前自己检查一遍。AI 读到 PR instructions 后先跑 lint再跑测试套件把报错逐个修完才回报完成。产出结果你拿到的提交已经过本地验证review 时只需要看设计不用揪格式问题。⚠️ 新手最容易踩的 3 个坑把整本 README 粘进去。AI 的注意力会被无关信息稀释效果反而变差。只写它干活必须知道的内容二三十行通常就够了。写完一次就再没更新过。构建体系或目录结构一变配置立刻失真AI 会照着旧命令执行然后报错。把它当成活文档和 README 一样随项目演进。给每个 AI 工具单独维护一份。Cursor rules、Copilot instructions、Gemini 配置各写一套维护成本翻倍。AGENTS.md 是跨工具的开放格式一份文件支持它的工具都能读。主流工具支持情况一览绝大多数主流编码代理已内置对 AGENTS.md 的识别例如 OpenAI Codex、GitHub Copilot、Google Gemini CLI、Jules、Cursor、Aider、Zed、goose、opencode、Amp 等。个别工具配置方式略有差异Aider 在配置里声明read: AGENTS.mdGemini CLI 在 settings.json 里指定文件名其余多为自动加载不需要额外操作。✅ 5 步快速上手清单先本地拿到项目执行git clone https://gitcode.com/GitHub_Trending/ag/agents.md提炼 setup、启动、测试命令新建 AGENTS.md 写入补 3~5 条编码与测试规范为新功能开发和合并前自检两个高频场景各写一段具体规则用一个真实任务验证哪里跑偏就修哪里的描述【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考