文章目录一个默认答案缺失的场景AGENTS.md 是什么为什么需要 AGENTS.mdAGENTS.md 怎么写9 条真正有效的规则实战场景示例最小可复制模板结尾今天就给你的项目补一份摘要你的 Agent 总在项目里自由发挥缺的就是这份 AGENTS.md。它是给 Agent 看的作业手册技术栈、编码规范、边界禁区一次说清。看完这篇你能立刻写出一份 30 行就够用的模板让 Agent 从凭感觉干活变成按规矩办事。提示本文图片由AI生成。你有没有遇到过 Codex 进陌生仓库在 Vue2 项目里写出 Vue3 语法、硬编码字符串、组件命名混乱的情况不是模型笨是它不知道团队的默认约定——这些约定本该写在 AGENTS.md 里。说白了不是它笨是没人告诉它规矩。一个默认答案缺失的场景上周帮同事看他新仓库。Codex 跑起来倒快但改了三四个文件全乱命名一会儿驼峰一会儿下划线注释一会儿英文一会儿拼音提交像流水账。我问他有没有 AGENTS.md他愣住。大部分开发者都踩这个坑。咱们写 README、PR 模板、Issue 模板唯独没给 Agent 准备一份工作手册。每次开新会话它都像第一次进你家的外卖员。门牌在哪、鞋脱哪、冰箱能不能开全靠猜。AGENTS.md 是给 Agent 看的项目说明书让它在动手前就知道边界。AGENTS.md 是什么放项目根目录或子目录的 Markdown 文件告诉 Coding Agent 项目用什么栈、目录怎么走、命名啥规则、哪些事别干。AGENTS.md 和 README.md 怎么分工README.md→ 给人看的项目说明书AGENTS.md→ 给Agent的安全作业手册和 CLAUDE.md 啥关系AGENTS.md 跨工具通用Claude Code、Codex、Cursor 都认CLAUDE.md 是 Claude 系专属。实际项目里最省事的做法是软链或同一份内容两边错配风险最小。有个坑要知道根目录 AGENTS.md 全局生效子目录的 AGENTS.md 处理该目录时动态注入、离开即卸载。换目录启动规则范围随之变化。为什么需要 AGENTS.md第一遗忘。对话式指令关窗即失。这次告诉它用单引号下次又默认双引号。规则写进文件每次自动加载。第二漂移。多 Agent 协作时颜色、命名、结构对不齐。规则不固化就是一锅粥。第三没默认答案。Agent 在陌生仓库不知道用 Vue 还是 React“API 放哪”“提交规范”AGENTS.md 给出默认答案。三个问题指向一个解法通过 AGENTS.md 把团队约定固化下来。AGENTS.md 怎么写我见过最离谱的 AGENTS.md写了 380 行把背景、目录、规范、命令全塞进去。结果 Agent 看完还是乱改。正确写法只写可执行约束少写形容词。项目概述一句话说清项目是什么、技术栈。目录结构关键目录职责Agent 该读哪、改哪、别碰哪。技术栈与版本框架版本、包管理器、运行时避免 Agent 写出错误版本语法。编码规范命名、组件结构、资源文件策略、禁止硬编码等。命令清单安装 / 启动 / 测试 / 构建的可执行命令优先用项目脚本。工作流约定改动前是否先出方案、提交信息格式、分支策略、何时需人工确认。边界与禁止不要静默重构、不要升级依赖、不要删死代码、密钥处理。9 条真正有效的规则反面把项目背景、目录、规范全塞进去两百行 → Agent 仍乱改、重复造轮子。正面规则要点写可执行的约束命令、路径、正则少写形容词。规则与现有代码模式对齐别自创理想化规范。分层根目录放全局子目录放局部避免一份文件包打天下。精简Fable / GPT-5 代模型不需要规定每个步骤过长反而稀释重点、增加 Token 成本。明确默认答案框架版本、包管理器、API 位置先定死。禁止项单独成段语气坚决。保留人工确认触发条件破坏性操作、外部服务、密钥。与测试对齐规则应能被测试 / lint / hook 兜底而非只靠文字。长期维护行为变化时同步更新不让 AGENTS.md 腐化成过期文档。▶ 规则能被测试 / lint / hook 兜底比写一万字文档管用。实战场景示例新人 Agent 首次进入没 AGENTS.md 时花十分钟口述规则有了一份直接干活。Vue2 防 Vue3 入侵一行禁止 Composition API 和 setup 语法糖Agent 一秒老实。多 Agent 协作Claude 改前端、Codex 跑后端测试。读同一份 AGENTS.md命名、风格、提交格式全对齐。子目录独立规则apps/web/AGENTS.md写前端规范进哪个目录自动套用。最小可复制模板# 项目概述 一句话说清楚项目是干什么的。 ## 核心规则 - Vue 组件一律 语法 - API 调用在 src/api/ 下定义组件内 import 使用 - 禁止组件内直接 console.log用 src/utils/logger.ts - 提交前确保 npm run type-check 通过 ## 技术栈 - Vue 3.4 / TypeScript 5 / Vite 5 - Element Plus 2.5 / Pinia 2.1 / Vue Router 4.2 ## 目录结构 src/ ├── api/ # 接口定义按模块划分 ├── components/ # 公共组件 ├── composables/# 组合式函数 ├── stores/ # Pinia 模块 ├── types/ # TS 类型 ├── utils/ # 工具函数 └── views/ # 页面组件 ## 常用命令 - npm run dev # 启动开发 - npm run build # 生产构建 - npm run test # 单元测试 - npm run lint # ESLint 检查 ## 特殊约定 - 日期统一用 dayjs已配 UTC 插件 - 金额单位统一分前端展示 /100 - 表单必须有防重复提交 - 删除/禁用等敏感操作必须二次确认 ## 排除范围别碰 - 不要改 src/assets/styles/element-override.css团队公共文件 - 不要删 src/types/global.d.ts - 不要直接往 main.ts 加代码用插件模块 ## 最终回复 完成任务时汇报 * 改了什么。 * 验证了什么。 * 如果有未验证内容说明原因。 * 触及了哪些重要文件。 * 还有哪些风险或后续建议。 最终回复要简洁、实用。不要让我自己检查一遍才知道工作是否可用。大家根据实际需求进行调整建议约束在 200 行以内。 多了不仅消耗 Token 还容易造成 Agnet 抓不住重点。结尾今天就给你的项目补一份AGENTS.md 不是写给同事看的文档是给 Agent 的契约。写它的那一刻Agent 就从凭感觉的临时工变成了按规矩办事的搭子。你的项目里有 AGENTS.md 吗写的时候踩过什么坑评论区聊聊咱们一块儿把它变好。