AGENTS.md 实践指南3 步让 AI 编码助手按你的规矩写代码【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md让你用 AI 写代码却总把构建命令跑错、风格写歪AGENTS.md 是指导 AI 编码代理的开放格式一个 Markdown 文件写清项目规则Codex、Cursor 等 23 款编码工具都认它已有 6 万多个开源项目在用。它到底是什么一句话AGENTS.md 是给代理看的 README。README 面向人写项目介绍和上手方式AGENTS.md 面向 AI写它完成构建、测试、改代码所需的命令和规矩。它没有必填字段也没有固定 schema就是标准 Markdown想用什么标题都行。对比项README.mdAGENTS.md读者人AI 编码代理常见内容项目介绍、上手方式安装/测试命令、代码风格、安全坑写法偏粗尽量短越具体越好可写很长维护节奏写完很少动跟代理一起持续修正兼容性是它最大的卖点一份文件多家工具通用不用再为每个工具单独维护一套配置。三步跑起来 第一步拿到参考实现git clone https://gitcode.com/GitHub_Trending/ag/agents.md cd agents.md这个仓库是官网源码既有完整示例仓库根目录自带的 AGENTS.md 本身就是一份现成样板。第二步写最小可用配置在你自己项目的根目录新建AGENTS.md只写三块# MyProject AGENTS.md ## Setup commands - 安装依赖: pnpm install - 启动开发服务器: pnpm dev - 跑测试: pnpm test ## Code style - TypeScript 严格模式 - 单引号不加分号预期效果不超过 20 行但代理已经知道怎么启动、怎么验证、怎么写。第三步验证生效重启你的编码代理派一个小任务你修复 src/utils.ts 里的类型报错完成前跑一遍全部测试。看它是否执行了你写的pnpm test、新代码是否遵守你定的风格都符合就说明配置生效了。想顺带看官方示例站点在参考仓库里跑pnpm install pnpm run dev浏览器打开 http://localhost:3000 即可。按场景抄作业 个人项目一份文件就够仓库根目录放一份 20~50 行的文件覆盖启动、测试、风格三件事即可。注意别把 README 整段搬过来面向人的项目背景和介绍对代理是噪音只会撑大上下文。小团队把隐性知识显性化除了命令把你平时在 review 里反复唠叨的也写进去PR 标题格式、提交前必须跑哪些命令、哪些文件不许动。比如本仓库的 AGENTS.md 就写明迭代时只用pnpm dev代理会话里别跑pnpm build免得热更新被毁。注意写的命令必须在开发环境真实可跑否则代理只会卡壳。大型协作 / monorepo用嵌套 AGENTS.md根目录放总则每个子包再各放一份代理干活时自动读取离目标文件最近的那份就近生效。OpenAI 主仓库目前就有 88 份 AGENTS.md各模块一份。注意子包文件只写差异别把根文件的内容抄一遍否则两层规则会打架。拉开差距的细节 1. 写可执行的命令不写形容词改法把注意代码质量提交前记得测一下换成pnpm test。 为什么有效代理只执行它能执行的命令越具体行为越稳定返工越少。 常见误区照抄 CI 脚本——那类命令常依赖只在流水线里存在的环境变量和步骤本地一跑就挂。2. 把纠错沉淀进文件改法每次发现代理犯错把正确做法直接补进 AGENTS.md。 为什么有效每个错误都变成一条规则代理的错误率随时间下降比每次在对话里临时纠正更省沟通成本。 常见误区只在大错之后才回头改文件小绕路随手记下下次才不会再犯。3. 全局规则与局部规则分层改法通用约定语言、风格、测试流程写根文件子包特有内容写嵌套文件。 为什么有效靠就近生效机制子包不必重复全局规则新人也能顺着文件层级读懂项目结构。 常见误区两层规则互相矛盾——代理认离它最近的那份人却在看顶上那份团队就出现了两套工作方式。踩坑速查 ⚠️现象代理根本不理 AGENTS.md原因工具需要显式配置才会读它。解法Aider 在.aider.conf.yml里加一行read: AGENTS.mdGemini CLI 在.gemini/settings.json的context.fileName里写上AGENTS.md。各工具的配置方式可查仓库 README.md 与站点 FAQ。现象代理跑完 build开发环境就挂了原因生产构建会把构建产物切到生产模式热更新直接失效。解法文件里写明一句代理会话中禁止跑 build迭代一律用 dev。现象文件里的规则和我对话里说的冲突原因这是设计使然不是 bug。解法聊天里的明确指令优先级永远最高离文件最近的 AGENTS.md 其次——想临时改行为就当面说想长期生效就写进文件。现象文件越写越长该删吗原因正常现象AGENTS.md 就是活文档。解法定期清理失效命令和过期约定如果发现文件一膨胀代理行为反而变差就把内容拆成嵌套文件。下一步AGENTS.md 本质上是写给 AI 同事的入职手册。明天花 10 分钟写下启动命令、测试命令、代码风格这三节的第一版然后看它在下一次任务里的表现——跑通最小模板再逐步加规则。【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考