AGENTS.md 使用教程：三步让 AI 编程代理读懂你的项目

AGENTS.md 使用教程三步让 AI 编程代理读懂你的项目【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.mdAGENTS.md 是一个开放、无门槛的标准文件格式专门给 AI 编程代理提供项目上下文、构建命令和代码规范Cursor、Copilot、Codex 等主流工具都原生支持它。读完这篇指南你能在自己的仓库里建好第一份 AGENTS.md让 AI 开工前就知道这个项目该怎么做。 AI 改了个 bug顺手把你的构建流程搞崩了你让 AI 代理修一个边界 bug它顺手执行了一条npm run build缓存切到生产产物开发服务器热重载直接失效。你回来只能再解释一遍这个项目用 pnpm别动 lockfile。下一次它照犯不误。这就是用 AI 编程工具的通病每个项目的构建方式、测试要求、代码习惯都不一样AI 只能按通用习惯瞎猜。你脑子里显而易见的信息在它的输出里就是下一个坑。AGENTS.md 解决的就是这个问题——它是一个为 AI 代理而生的项目说明书标准文件名OpenAI、Google、GitHub 等团队的工具均已支持超过 6 万个开源项目在仓库里放了这份文件。 它是怎么工作的给 AI 贴一张随取随用的便签README 是写给人看的简介、快速开始、贡献指南。但代理还需要更具体的东西该跑哪条命令、哪些文件不能碰、命名和格式有什么讲究。这些内容太碎塞进 README 会把它搞臃肿AGENTS.md 就是把它们放到一个固定、可预期的位置。说白了它就像贴在项目门口的便签开工前先读我。代理开始干活时会自动读取仓库根目录的这份文件如果项目是大型 monorepo可以在每个子包里再放一份代理会自动采用离它正在编辑的文件最近的那份离得越近优先级越高。你在聊天里亲自说的指令优先级最高文件没有字段要求就是普通的 Markdown。✍️ 三步创建你的第一个 AGENTS.md第 1 步在仓库根目录新建文件。直接建一个AGENTS.md即可多数 AI 工具还能帮你起草——让它先扫一遍项目结构再照着写初稿。第 2 步只写AI 猜不出来的东西。一个够用的起步模板就三块# AGENTS.md ## 构建与测试 - 安装依赖pnpm install - 启动开发服务器pnpm run dev代理会话里禁止执行 build - 提交前所有测试必须通过 ## 代码约定 - 新组件一律使用 TypeScript.tsx - 样式文件与组件放在同一目录 ## PR 规范 - 标题格式[模块名] 改动说明本仓库自己的 AGENTS.md 就是很好的范本第一条就写用 dev server别跑 build并附了一张命令用途对照表README 里还有一个最小示例可供参考。第 3 步大仓库往下再细化。monorepo 的每个子包再放一份 AGENTS.md写清该包专属的命令与约定代理按就近原则自动读取不需要任何额外配置。⚠️ 新手最容易踩的三个坑坑一把 README 整段搬过来。❌ 复制粘贴项目背景、致谢、安装步骤全家桶 ✅ 只写代理无法自行推断的操作信息构建/测试命令、禁用项、命名约定坑二写一堆没法验证的模糊指令。❌ 请写出优雅、易读、注重性能的高质量代码 ✅ 运行 pnpm lint 和 pnpm test全绿才算完成代理擅长执行可检查的指令形容词只会让它在原地打转。坑三建完就再也不看。❌ 建完放那儿三年构建命令早变了规范也烂在文件里 ✅ 当成活的文档维护构建命令变了、新增约定了顺手更新它 写在最后AI 从外援变成项目成员AI 编程工具过去像个通用外援能力强但不熟你的项目。AGENTS.md 把关系改成了项目成员——入职资料、行为守则、验收标准全在这一张纸上。下次觉得 AI 不顶用时先问一句给它发工牌了吗【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考