AGENTS.md 快速上手指南让 AI 编程助手真正读懂你的项目【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.mdAGENTS.md 是一个开放、跨工具的配置文件格式专门给 AI 编程助手看。你可以把它理解成给助手的 README一个放在项目根目录的 Markdown 文件写清项目怎么跑、测试怎么执行、哪些规矩不能碰。它对刚接触 AI 编程工具的新手和普通开发者很友好——不需要换 IDE、不需要装插件一个纯文本文件就能收敛助手的行为而且换工具时配置不用重写。先看一个真实场景。你让助手在这个 Next.js 项目里加个页面它干完活顺手执行了npm run build把.next目录切成了生产产物热更新直接失效开发服务器卡在半路。你只能重启、回滚再口头叮嘱以后别碰构建命令——但下一次它还会犯。AGENTS.md 的意义就在于把这类口头叮嘱固化成项目级规则写一次所有支持该格式的助手都会照做。AGENTS.md 是什么给 AI 编程助手的标准化上下文一句话定义它 项目根目录下一个固定文件名的 Markdown 文档为编码代理提供构建步骤、测试方式、代码约定等上下文替代过去散落在聊天记录里的临时叮嘱。和 README 的关系值得说清楚。README.md服务人类读者快速开始、项目介绍、贡献指南所以要精简。AGENTS.md 装的是助手需要、但塞进 README 会显得臃肿的细节精确的构建命令、测试矩阵、内部约定。两个文件互补互不替代。这个格式并非某一家公司的私有规范而是由 OpenAI Codex、Google Jules、Cursor、Factory、Amp 等多个 AI 编程团队联合推动的开放标准目前由 Linux 基金会旗下的 Agentic AI Foundation 托管。可以参考的生态数据超过 60,000 个开源项目已经在用Codex、Cursor、VS Code、GitHub Copilot 等主流工具都支持读取。本仓库 public/logos/ 目录收录了各工具标识components/CompatibilitySection.tsx 里维护着完整的兼容工具清单包括 Gemini CLI、Aider、goose、Zed、Warp、Windsurf、Devin、RooCode、Kilo Code、opencode、Junie 等二十余种。想看格式本身的参考实现可以 clone 官方仓库git clone https://gitcode.com/GitHub_Trending/ag/agents.md仓库里的 AGENTS.md 本身就是一份可以直接抄作业的样本README.md 里附了最小示例。从零创建最小可用的 AGENTS.md 配置文件放哪里位置项目根目录与README.md平级命名就叫AGENTS.md大小写敏感别写成agents.md或AGENT.md格式普通 Markdown没有必填字段、没有 schema助手直接解析你写的文本标题层级随你定三节骨架就够用最小示例浓缩下来就是三节从你每天真正会敲的命令抄过来即可## Dev environment tips—— 开发环境怎么起。例如pnpm install --filter project_name把包装进工作区pnpm dlx turbo run where project_name直接定位到某个包别用ls盲扫## Testing instructions—— 测试怎么跑。例如pnpm turbo run test --filter project_name跑全量检查合并前必须全绿改了代码要补测试哪怕没人要求## PR instructions—— 提交流程。例如标题格式[project_name] Title提交前跑pnpm lint和pnpm test建议第一版只写这三节。写不全没关系文件可以随用随长。AGENTS.md 写什么能力授权与约束边界配置内容可以归成四类每类都尽量写成可执行、可验证的规则而不是口号。命令与执行边界最值钱的一类明确助手可以跑什么、禁止跑什么。本仓库的 AGENTS.md 就是范本迭代时始终用npm run dev禁止在助手会话里执行npm run build——生产构建会把.next切成生产资产热更新直接失效增删依赖后必须同步锁文件pnpm-lock.yaml等并重启开发服务器让 Next.js 加载变更附一张命令速查表npm run dev/npm run lint/npm run test各干什么、哪条禁用技术栈与风格新组件、工具函数一律用 TypeScript.ts/.tsx组件相关样式就近放在组件同目录命名规范、注释格式、目录组织要求也放在这里规则越具体助手输出越稳定质量门禁提交前lint和test必须全绿移动文件或改动 import 后重新跑一次 lint 确认类型规则没破改动过的代码要补对应测试安全与性能不提交、不回显密钥等敏感信息性能约束写成可检查的条款例如避免引入不必要的重渲染列表渲染必须带 key原则只有一条每条规则都应该是助手能照做、你能验收的。写代码要高质量等于没写写提交前跑pnpm lint红了就修才算配置。进阶定制分层目录与按阶段切换子目录再放一个 AGENTS.md规则冲突时的裁决顺序是离被编辑文件最近的那个 AGENTS.md 生效你在对话里的显式指令优先级最高。这意味着 monorepo 可以在根目录放全局规则再在某个包的目录里放局部规则互不干扰。按开发阶段调整侧重点日常开发阶段侧重快速迭代写清启动命令、热更新注意事项测试与审查阶段强调质量门禁测试矩阵、lint 规则、覆盖率要求面向生产突出性能与安全检查项对接团队知识库文件保持精简长文档放出去再引用历史技术决策、业务术语表、内部流程规范写成见某文档的指引而不是把整篇贴进来。已有规则的迁移如果项目里已有旧规则文件如旧名AGENT.md直接改名并留一个符号链接兜底ln -s AGENTS.md AGENT.md团队怎么用个人、开源与企业三个尺度个人项目起步时就把三节骨架写进根目录等于给项目定下出生规范避免助手先跑偏、后期再返工开源项目它是给贡献者的低成本入门文档。参考生态里已经在用的项目——openai/codex、apache/airflow、temporalio/sdk-java、PlutoLang/Pluto——它们的 AGENTS.md 都承担新人第一站的角色直接减少 review 来回企业团队把文件纳入版本控制后它就是一份全员共享的助手行为标准新人照着上手、跨团队对齐口径、code review 有统一依据关键动作只有一个和对待代码一样对待这个文件——变更走 review过时内容及时删。排错指南 配置不生效时查这四处文件位置必须在项目根目录文件名大小写正确。多数不生效其实是路径问题工具支持确认你的 AI 编程助手支持该格式。Codex、Cursor、VS Code、Copilot 默认读取Aider 需要在.aider.conf.yml里加一行read: AGENTS.mdGemini CLI 在.gemini/settings.json里配置context: { fileName: AGENTS.md }指令歧义检查是否存在互相矛盾的规则。裁决规则是离文件最近者胜但你自己写得自相矛盾行为就会漂移命令可达性写进文件的测试命令助手会在任务收尾前尝试执行并修复失败项——前提是这些命令在你环境里真的能跑通。先自己敲一遍再写进文件验证效果的实用办法挑一个固定任务分别在有 / 无 AGENTS.md 的情况下各跑一次对比一次通过率、规范遵循度、需要的纠正次数。如果三次纠正里有两次是同类问题那就该写进文件了。持续优化把 AGENTS.md 当活文档维护每次纠正助手之后顺手把纠正内容沉淀成一行规则这是最便宜的更新时机项目结构变化拆包、换构建工具时同步更新命令清单过期的命令比没有命令更危险定期清理删掉已经不再成立的历史条款今天就可以做一件事打开你的项目根目录新建AGENTS.md把最近一周里你口头纠正助手最多的三句话写进去然后跑一遍同样的任务看纠正次数少了多少。【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考