如何用 AGENTS.md 三步让 AI 读懂你的项目面向 AI 编程助手的项目约定实操指南【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.mdAGENTS.md 是面向 AI 编程代理的简单、开放标准文件格式在项目根目录放一个文件它就自动读取你的项目约定、代码风格与测试要求。你不用每次重新解释一遍项目背景。AI 在项目里反复犯的错你让 AI 改某个模块它把函数命名全换了一种风格你让它补测试它跑了一个项目里根本不存在的命令你把提示词改成请遵循项目规范下一个会话它又打回原形。根因是这些约定只存在于你的脑子里和聊天记录里没有落进 AI 能读到的文件里。AGENTS.md 就是给这类问题的答案一份统一的说明文件让 AI 每次开工前都读一遍。AGENTS.md 怎么工作一句话它是写给 AI 的入职手册放在项目根目录AI 先读它再动手。内容通常就三类怎么跑项目包管理器、常用命令代码风格命名、目录组织、语言偏好测试与质量要求完成后跑哪些命令、何时才算可提交。不该写的是把 API 文档整份搬进来——只写 AI 容易搞错的部分。本仓库自己的 AGENTS.md 就是范例它明确必须用开发服务器、代理会话期间不许跑生产构建AI 就不会误操作破坏热更新。三步跑起来建文件。在项目根目录新建AGENTS.md与 README 同级。预期结果下一次会话 AI 工具会自动加载它。填三块内容。依次写清运行命令、风格约定、测试要求越短越好。最小示例# AGENTS.md - 使用 pnpm不要用 npm 或 yarn - 新组件一律用 TypeScript 编写 - 完成前必须跑 pnpm lint 和 pnpm test派个任务验证。让它加一个小功能检查输出命名是否符合你的约定、有没有跑你指定的测试。AI 下一次输出已自动遵循你的约定就算跑通了。动笔前可以先看一眼 README.md把 AI 最可能搞错的部分摘出来写进去。常见误区与修正写得过长反而失焦。把整本文档塞进去AI 抓不住重点你也维护不动。只写高频约定一页以内。写完从不更新。命令和目录结构变了文件没变AI 照着旧约定干活。更新项目结构时顺手检查它。当成公告来写。AI 读的是指令不是铺垫。直接写做什么、不做什么每条一句话就够。常见问题我怎么知道我的 AI 工具读不读这个文件目前众多开源项目和 AI 编程工具已支持这个格式先在常规会话里试一次最稳妥暂不支持的工具把文件内容贴进提示词效果一样成立。它应该写多长没有硬性规定但一份好文件两分钟能读完。写超一页说明你塞进了 AI 用不到的东西。和 README 会冲突吗不会。README 写给人看AGENTS.md 写给 AI 看。重复内容在 AGENTS.md 里从简或指向 README 的对应章节即可。现在就动手下次 AI 再犯错别只在提示词里补一句解释把那条约定写进 AGENTS.md。养成这个习惯项目里就多了一份会跟着项目一起长大的说明文档。【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考