写给程序员的 AGENTS.md:让 AI 编程助手效率翻倍

把项目规则写进 AGENTS.md，让 AI 少猜一点｜图片由 AI 生成

很多程序员第一次用 AI 编程助手，都会经历一个尴尬阶段：它很聪明，但总像刚入职的新人。它不知道你的项目怎么启动，不知道哪些文件不能碰，不知道测试应该跑哪一组，也不知道你们团队那些“默认都懂”的约定。

解决办法不是每次都写一大段提示词，而是把这些稳定规则沉淀到项目里的 AGENTS.md。

一、为什么你的 AGENTS.md 没有用起来

低效的 AGENTS.md，通常不是因为写得太少，而是因为写得太虚。

• 只写“遵守最佳实践”，但没有说这个仓库的最佳实践是什么。
• 复制 README 内容，却没有补充 AI 真正需要的工作规则。
• 没有写安装、构建、测试、格式化命令，导致每次都要重新猜。
• 没有写禁止事项，比如不要改生成文件、不要提交密钥、不要重置用户改动。

OpenAI Codex 的 AGENTS.md 指南 也强调，应该把构建、测试、代码约定、验证方式和 PR 预期这类信息写进去。换句话说，它最有价值的部分不是“态度”，而是“操作”。

二、好用的 AGENTS.md 应该写什么

你可以把它想象成给 AI 的入职文档。真正能提升效率的内容，通常包括下面七类。

• 项目地图：核心目录、模块职责、关键入口在哪里。
• 常用命令：安装、开发、构建、测试、lint、类型检查。
• 编码约定：组件怎么写，接口怎么封装，错误怎么处理，命名怎么统一。
• 验证规则：改了哪类代码要跑哪些测试，什么输出才算完成。
• 常见流程：新增页面、新增 API、新增数据库字段时分别走什么路径。
• 安全边界：哪些文件不能改，哪些操作必须先确认，哪些信息不能输出。
• 交付格式：最后要总结改动、列出验证命令、说明风险或未覆盖点。

三、不要只写一个大而全的根文件

很多团队会把所有规则塞进仓库根目录的 AGENTS.md，结果文件越来越长，真正重要的规则反而被淹没。

更推荐分层写法：

• 根目录写全局共识：项目结构、通用命令、默认约定、交付要求。
• 前端目录写前端规则：组件库、路由、状态管理、样式约束、截图检查。
• 后端目录写后端规则：接口规范、鉴权边界、数据库迁移、单测命令。
• 特殊模块写局部规则：支付、权限、风控、生成代码等高风险区域。

Codex 会按层级读取说明，越靠近当前工作目录的文件越具体。这意味着你可以把“全公司都适用的规则”和“这个模块独有的规则”拆开，避免每次任务都塞进一大包噪音。

四、一个可直接改的 AGENTS.md 模板

下面这个模板不追求完整，而是追求能立刻减少沟通成本。你可以先复制，再按项目实际情况改。

五、把“泛泛要求”改成“可执行规则”

AI 最怕模糊口号。你写“保持代码优雅”，它只能猜；你写“组件不要直接请求接口，统一通过 hooks/useXxxData.ts 封装”，它就能执行。

这就是 AGENTS.md 的核心写法：把经验变成规则，把规则变成命令，把命令变成可验证的完成标准。

六、什么时候更新它

很多项目的 AGENTS.md 写完就不动，时间一长就变成“过期规则集”。更好的方式是把它当作团队协作协议，随着项目演进持续维护。

• 当 AI 连续两次犯同一个错，把纠正方式写进去。
• 当 Review 里反复出现同类问题，把评审标准写进去。
• 当脚手架、测试框架、包管理器变化时，第一时间更新命令。
• 当某个模块风险升高，比如支付、权限、数据迁移，新增局部规则。

七、让效率翻倍的检查清单

写完之后，可以用这份清单快速自检：

• 一个新成员能否通过它知道项目怎么启动和验证？
• 每条规则是否足够具体，能被 AI 执行或检查？
• 是否写清楚不同类型改动对应的测试命令？
• 是否明确了不要碰的文件、不要做的操作和需要先确认的事项？
• 是否把局部规则放到了更靠近对应代码的目录？
• 是否能让最终交付更容易 review，而不是只让生成速度更快？

好的 AGENTS.md 不会让 AI 变得神奇，但会让它少走很多弯路。它把团队经验前置，把反复沟通自动化，把“你应该懂的”变成“你已经知道的”。

当你开始认真维护它，AI 编程助手就不再只是一个会写代码的工具，而更像一个熟悉项目规则、懂得验证边界、交付前会自检的协作者。