企业官网建设流程全解析

如何用 AGENTS.md 三步让 AI 读懂你的项目：面向 AI 编程助手的项目约定实操指南

【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md

AGENTS.md 是面向 AI 编程代理的简单、开放标准文件格式：在项目根目录放一个文件，它就自动读取你的项目约定、代码风格与测试要求。你不用每次重新解释一遍项目背景。

AI 在项目里反复犯的错

你让 AI 改某个模块，它把函数命名全换了一种风格；你让它补测试，它跑了一个项目里根本不存在的命令；你把提示词改成"请遵循项目规范"，下一个会话它又打回原形。根因是这些约定只存在于你的脑子里和聊天记录里，没有落进 AI 能读到的文件里。AGENTS.md 就是给这类问题的答案：一份统一的说明文件，让 AI 每次开工前都读一遍。

AGENTS.md 怎么工作

一句话：它是写给 AI 的入职手册，放在项目根目录，AI 先读它再动手。

内容通常就三类：怎么跑项目（包管理器、常用命令）；代码风格（命名、目录组织、语言偏好）；测试与质量要求（完成后跑哪些命令、何时才算可提交）。

不该写的是把 API 文档整份搬进来——只写 AI 容易搞错的部分。本仓库自己的 AGENTS.md 就是范例：它明确"必须用开发服务器、代理会话期间不许跑生产构建"，AI 就不会误操作破坏热更新。

三步跑起来

1. 建文件。在项目根目录新建AGENTS.md，与 README 同级。预期结果：下一次会话 AI 工具会自动加载它。
2. 填三块内容。依次写清运行命令、风格约定、测试要求，越短越好。最小示例：

# AGENTS.md - 使用 pnpm，不要用 npm 或 yarn - 新组件一律用 TypeScript 编写 - 完成前必须跑 pnpm lint 和 pnpm test

3. 派个任务验证。让它加一个小功能，检查输出：命名是否符合你的约定、有没有跑你指定的测试。AI 下一次输出已自动遵循你的约定，就算跑通了。

动笔前可以先看一眼 README.md，把 AI 最可能搞错的部分摘出来写进去。

常见误区与修正

• 写得过长反而失焦。把整本文档塞进去，AI 抓不住重点，你也维护不动。只写高频约定，一页以内。
• 写完从不更新。命令和目录结构变了，文件没变，AI 照着旧约定干活。更新项目结构时顺手检查它。
• 当成"公告"来写。AI 读的是指令，不是铺垫。直接写"做什么、不做什么"，每条一句话就够。

常见问题

我怎么知道我的 AI 工具读不读这个文件？

目前众多开源项目和 AI 编程工具已支持这个格式，先在常规会话里试一次最稳妥；暂不支持的工具，把文件内容贴进提示词，效果一样成立。

它应该写多长？

没有硬性规定，但一份好文件两分钟能读完。写超一页，说明你塞进了 AI 用不到的东西。

和 README 会冲突吗？

不会。README 写给人看，AGENTS.md 写给 AI 看。重复内容在 AGENTS.md 里从简，或指向 README 的对应章节即可。

现在就动手

下次 AI 再犯错，别只在提示词里补一句解释，把那条约定写进 AGENTS.md。养成这个习惯，项目里就多了一份会跟着项目一起长大的说明文档。

【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md