AGENTS.md 入门指南：给 AI 编码助手立规矩，只需一个文件

AGENTS.md 入门指南给 AI 编码助手立规矩只需一个文件【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md你大概率遇到过这种场面换了个 AI 编码工具得把项目背景从头讲一遍好不容易讲明白了它又忘了。AGENTS.md 就是解决这件事的——一个给编码代理看的纯 Markdown 说明文件告诉 AI 助手你的项目怎么构建、怎么测试、有哪些规矩。目前已有超过 6 万个开源项目采用它由 Linux 基金会下的 Agentic AI Foundation 维护Codex、Cursor、VS Code、Gemini CLI、GitHub Copilot 等主流工具都支持读取。没有它的时候你在重复教 AI 做同一件事场景一你让 AI 改一个函数它顺手跑错了构建命令。你纠正了。第二天换个新会话同样的错误再来一遍。项目知识只存在于你的脑子里每个新会话都要重新喂一遍。场景二你想把用哪个测试命令提交信息怎么写塞进 README。可 README 是写给人看的塞满机器指令后人类读者也受不了文件越写越长两拨人都看不下去。两边都别扭根源是缺一个专门给 AI 看的固定位置。一句话理解它是写给 AI 的新人入职手册README 是给人类读者的项目介绍AGENTS.md 则是给 AI 助手的入职手册环境怎么搭、测试怎么跑、代码风格是什么、有哪些雷区。文件名固定、位置固定任何支持它的工具都知道去哪里找。你写的不是某种私有配置而是一份随仓库走的活文档换个工具、换个同事接手都不用重新交代。四步给你的项目配好 AGENTS.md克隆演示仓库git clone https://gitcode.com/GitHub_Trending/ag/agents.md仓库里的 README.md 有一份完整的真实样例可以抄作业。在你的项目根目录新建一个名为AGENTS.md的文件纯 Markdown 即可。写上四块内容项目简介、构建/测试命令、代码风格约定、安全注意事项。提交进版本控制让每位团队成员和每个 AI 会话都拿到同一份指令。最小可用的文件长这样# AGENTS.md ## 构建 - pnpm install 安装依赖 - pnpm dev 启动开发服务器 ## 测试 - pnpm test 运行全部测试提交前必须全绿 ## 代码规范 - 新组件一律用 TypeScript - 组件样式放在组件同目录下三个核心功能看看它到底帮你做了什么写一次23 款工具都能用这份官网的兼容列表里挂了 23 款工具OpenAI 的 Codex、Google 的 Jules 和 Gemini CLI、Cursor、VS Code、GitHub Copilot、Zed、Windsurf、Devin、Aider 等。对你意味着什么配置跟仓库走而不是跟工具走。今天用 Cursor明天换 Codex 命令行指令不用重写一份。大仓库分层配置就近的那份文件说了算单体大仓库可以在每个子包里各放一个 AGENTS.md代理会自动读取离被编辑文件最近的那份如果多份指令打架也是离文件最近的那份生效而你在对话里的明确指令优先级最高。对你意味着什么子项目各自有定制规则又不会互相打架。OpenAI 的主仓库里就放了 88 个 AGENTS.md 文件一个包一份说明互不干扰。把测试命令写进去代理会自己跑你在文件里列出的测试、lint 等命令代理会主动执行相关检查失败了先修好再交活。对你意味着什么你不再需要每次提醒改完跑一下测试它已经变成代理的标准动作。新手容易踩的两个坑坑一以为必须按某种格式写。没有必填字段、没有私有语法就是普通 Markdown标题爱怎么写怎么写代理只解析你提供的文本本身。坑二已有文档不知道怎么办。如果你之前用的是 AGENT.md 之类的名字直接重命名成 AGENTS.md再用符号链接兼容旧名即可ln -s AGENTS.md AGENT.md。个别工具需要显式指一下文件比如在 Aider 的.aider.conf.yml里加一行read: AGENTS.md或者在 Gemini CLI 的.gemini/settings.json里设置fileName: AGENTS.md。另外提醒一句这个文件是活文档项目结构变了就顺手更新它。三种真实场景对号入座个人项目一个人维护的仓库把构建命令和踩过的坑写进去之后无论用哪个 AI 工具打开项目它上来就知道该怎么干活省掉每次的口头交代。团队开发提交信息格式、合并前必须过 lint 这类团队铁律写进 AGENTS.md新老成员的 AI 助手行为就统一了代码风格不再因人而异。开源贡献给贡献者人和 AI 都是一份标准指引贡献者按文件里的规范开发维护者 review 的成本明显下降。常见问题问AGENTS.md 和 README.md 冲突吗不冲突是互补。README 面向人类管快速上手和贡献指南AGENTS.md 面向代理装下那些对人类没太大必要、对 AI 却很关键的细节。问会不会越来越长最后又变成没人看的文件会过时但不会失控——它就是 Markdown删改零成本而且只有代理真的会精读它。问现在的项目马上能用吗可以直接新建文件提交即可不需要安装任何东西。一句话总结AGENTS.md 用一个文件把你脑子里的项目规矩变成了所有 AI 助手都能读懂的标准配置。下一步很简单回到你最近的一个仓库花十分钟把构建命令和测试命令写进根目录的 AGENTS.md 里——今天多花的十分钟省掉的是往后每天的重复解释。【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考