别再让 AI 瞎写代码了一篇搞懂什么是 AGENTS.md如果你经常使用 Cursor、Claude Code、GitHub Copilot 或 CodeBuddy 等 AI 编程助手大概率遇到过这些让人头疼的场景乱改依赖明明项目用的是pnpmAI 偏要执行npm install生成一堆package-lock.json风格脱节项目要求全量使用 TypeScript React 函数式组件AI 却给你抛出一段 Class 组件或含any的代码破坏边界让它加个小功能它顺手把你的.env删了或者把数据库 Migration 改得乱七八糟无限幻觉修改完代码不自动跑单测直接告诉你“改好了”结果一运行全是报错。为了解决这些“AI 缺乏项目上下文”的痛点开源社区和 AI 领域开始逐渐形成一个通用的约定——AGENTS.md。一、 什么是 AGENTS.md一句话解释README.md是写给人类开发者看的项目说明书而AGENTS.md就是写给 AI 编程助手看的“入职手册”和“行为法典”。随着各种 AI Agent 深度参与到软件开发中我们需要一种标准化的方式来告诉 AI“在这个仓库里你需要遵循什么规则用什么工具哪些能做哪些绝对不能触碰。”AGENTS.md通常放在项目的根目录下本质上是一个纯文本 Markdown 文件。当 AI 助手Agent进入你的项目上下文时系统会自动读取这个文件并将其转化为约束 AI 行为的全局系统提示词System Instructions。二、 它能解决什么问题简单来说AGENTS.md为 AI 建立了明确的行为边界Guardrails与作业标准Definition of Done1. 明确红线与禁区Hard Rules在配置文件中显式写明“绝对不能做的事”。例如严禁修改环境变量文件 (.env*)未经人类确认不得引入新的第三方依赖修改 API 接口前必须先提问。2. 锁定统一的技术规范与风格Code Style Tech Stack无需每次对话都重复提醒 AI 项目的技术栈。你可以在里面约定包管理器统一使用pnpm代码风格错误处理必须显式返回Result类型不盲目使用try-catch组件规范只使用 Tailwind CSS禁止内联样式。3. 自动化校验与完成标准Commands Verification告诉 AI“代码写完不代表任务完成”指导它主动跑测试写完代码后必须自动运行pnpm typecheck和pnpm test只有当 Exit Code 为 0 时才算真正完成任务。三、 实战示例一个标准的 AGENTS.md 长什么样下面是一个可直接参考的项目级AGENTS.md模板# Agent Operational Policy Rules ## 1. 核心边界与禁区 (Hard Rules) - 【绝对禁止】未经许可不得修改 .env 或任何包含敏感凭证的文件。 - 【绝对禁止】未经许可不得在 package.json 中添加全新的第三方依赖。 - 【提问触发】在修改任何 API 路由逻辑或数据库 Schema 前必须先向开发者提问确认。 ## 2. 技术栈与技术规范 (Tech Stack Style) - **包管理器**必须使用 pnpm严禁使用 npm 或 yarn。 - **框架**Next.js (App Router) TypeScript (Strict Mode) Tailwind CSS。 - **代码风格** - 优先使用异步函数 (async/await)。 - 所有导出的函数必须有明确的 TypeScript 类型定义禁止使用 any。 ## 3. 验证与完成标准 (Definition of Done) 每次提交代码或回答“已完成”之前必须按顺序执行以下命令进行自我验证 1. pnpm typecheck - 确保没有类型错误。 2. pnpm lint - 确保符合代码风格规范。 3. pnpm test - 确保现有单元测试全部通过。 如果上述命令报错请先自我修复报错直到全部通过为止。四、 为什么说它正在成为未来的开放标准在过去不同的 AI 工具各有各的规则文件Cursor 使用.cursorrulesClaude Code 使用CLAUDE.mdGitHub Copilot / Windsurf 也各有专有配置这种碎片的生态导致项目维护极其繁琐。而AGENTS.md正逐渐演变为一个跨平台、通用的开放标准。无论团队里的成员用的是什么 AI 编程工具只要仓库根目录下存在AGENTS.md各大 Agent 工具就能读取同一套规矩实现人机协作协同的无缝对接。五、怎么使用 AGENTS.md直接在项目根目录创建AGENTS.md文件即可。 AI编辑器如 Cursor、Trae会自动识别并加载它。除非你主动关闭如下图trae关闭然后就可以在 AI 编辑器中使用它了。下面我会提供我常用的AGENTS.md模板。六、我的 AGENTS.md 常用模板我的常用模板见前端专用AGENTS.md模板后端专用AGENTS.md模板 感谢阅读想了解更多我的博客网站 | 记录思考分享干货 我的个人主页 | 关于我、开源项目
)
