为何在AI写代码时需维护AGENTS.md

背景

当前许多公司已全面推行 AI 辅助开发，员工每月获得固定 token 额度用于项目编码。然而在实践中，大部分同事使用 AI 工具（如 OpenAI Codex）的方式非常粗放：要么直接打开对话框进行“裸对话”提需求，要么仅执行 /init 命令做项目初始化后就没了后续，如同只写了一份 README。这种使用方式导致开发过程频繁出现问题——AI agent 不按项目规范设计、经常遗漏测试验证步骤、随意修改甚至删除文件；重复的提示每次都得重说，使得上下文窗口日益臃肿；最终交付的代码 bug 多、返工频繁，每月的 token 额度根本不够用。

许多同事将此归咎于模型选型不对，但原文作者认为更重要的原因是未能有效管理和运用 AGENTS.md 这个文件。本文将围绕 AGENTS.md 的定位、加载机制、与 README.md 及 CLAUDE.md 的区别、如何与 Claude Code 的 Memory 机制配合等展开深度解读，帮助开发者和团队从根本上提升 AI 辅助开发的效率与质量。

核心内容

AGENTS.md 是什么

AGENTS.md 是一个开放标准，官方定义将其视为“代理的 README”——一个专门的、可预测的位置，用于提供上下文和说明，帮助 AI 编码代理在项目中工作。它被 OpenAI Codex、GitHub Copilot、Cursor、Aider、Zed、JetBrains、Claude Code 等多种工具支持。一份文件即可在多个 Agent 中通用。

一个简洁的 AGENTS.md 示例包含：

• 构建和测试命令（如 npm run build、npm test）
• 编码规范（如 API 入参统一用 XxxParams，响应用 XxxResponse，禁止 console.log 使用 logger）
• 禁止事项（如不要手动修改 generated/ 目录、不要提交 .env 文件）
• 联动规则（如修改 API 接口后同步更新文档和测试）

AGENTS.md 与 README.md 的本质区别

| 文件 | 目标读者 | 用途 | |----------|----------|--------------------------------| | README.md | 人类开发者 | 快速了解项目、技术栈、环境搭建、代码仓库入口 | | AGENTS.md | AI 代理 | 按规矩做事：构建命令、测试步骤、编码规范、验证规则 |

两者虽同为 markdown 格式，但使用场景完全不同。README.md 帮助人理解项目，AGENTS.md 帮助 agent 减少出错、保持交付质量。

AGENTS.md 的加载机制（以 Codex 为例）

Codex 官方文档说明，启动时会构建一条指令链：

• 先读全局作用域（~/.codex 目录）
• 再从项目根目录向下遍历到当前工作目录
• 在每个目录依次查找 AGENTS.override.md → AGENTS.md → fallback 文件名
• 文件按位置优先级拼接：全局配置 → 项目根目录 → 当前工作目录，后面的优先级更高。

例如 monorepo 结构：

my-monorepo/
├── AGENTS.md              # 全局项目规则
├── frontend/
│   └── AGENTS.md          # React 相关规则
├── backend/
│   └── AGENTS.md          # Java/Spring 相关规则
└── infra/
    └── AGENTS.md          # 部署相关规则

在 frontend/ 目录下启动 Codex，会依次加载 ~/.codex/AGENTS.md → my-monorepo/AGENTS.md → my-monorepo/frontend/AGENTS.md，最终合并为一个上下文。

Codex 默认限制总大小为 32 KiB，超过限制会截断。原文作者建议不轻易调大限制，而是精简规则——规则太多 agent 也记不住，精简比扩容更有效。

此外，AGENTS.md 不是实时配置中心，修改后需新开会话才会生效。

如何与 Claude Code 的 CLAUDE.md 协同

尽管 Claude Code 有自己专属的 CLAUDE.md 格式，但 AGENTS.md 作为开放标准同样可以被 Claude Code 读取。不同工具有不同的实现细节，但总体原则一致：全局规则管个人习惯，项目规则管仓库，子目录规则更具体。

区别：

• AGENTS.md：开放标准，多工具通用，适合放构建命令、测试命令、编码规范、禁止事项、联动规则等通用项目规则。
• CLAUDE.md：Claude Code 专属，仅 Claude Code 识别，适合放特有配置（如 skills、hooks、Memory 相关说明）。

推荐做法：在项目的 CLAUDE.md 中显式引入 @AGENTS.md（这是 Claude Code 的 @file 引用语法），后面只补充 Claude Code 专属内容。这样通用规则维护一份，Claude Code 通过 @ 导入，其他工具直接读 AGENTS.md，项目规则一致。

也可以设置全局 ~/.claude/CLAUDE.md，添加一条约定：“遵循并维护/创建最近的 AGENTS.md 文件”，这样 Claude Code 进入任何项目都会主动围绕 AGENTS.md 工作。但原文更推荐团队将规则显式放在仓库内（CLAUDE.md + @AGENTS.md 方式），确保团队共享一致。

Claude Code 的 Memory 机制

Claude Code 还有第三个文件体系：Memory，存储在 ~/.claude/projects/<项目hash>/memory/MEMORY.md。每条记录是独立的 md 文件，MEMORY.md 是索引。Memory 是协作过程中的经验记录，仅本地保存，不提交到 git。每次启动新会话时，Memory 的前 200 行自动加载进上下文。

作用：记录近期遇到的问题、临时约定、尚未提炼成规则的经验。建议定期检查 Memory，将反复出现的提示提炼到 AGENTS.md 中，然后删除 Memory 中对应条目，从而持续优化规则集。

（注：Codex 也有类似的 Memory 机制，原文未详细展开。）

关键要点

• AGENTS.md 是一个开放标准，被多个主流 AI 编码工具支持（OpenAI Codex、Copilot、Cursor、Aider、Claude Code 等），一份文件可在不同 Agent 间通用。
• AGENTS.md 是给 AI 代理看的，而非人类开发者。它规定了构建/测试命令、编码规范、禁止事项、联动规则等，帮助 agent 按规矩做事、减少出错。
• /init 命令只是项目初始化，后续必须持续维护 AGENTS.md，否则效果等同于只写了 README。
• Codex 的加载顺序为：全局作用域 → 项目根目录 → 当前工作目录，层层拼接，后面优先级更高。文件总大小默认限 32 KiB，超限会被截断。
• 精简规则比调大限制更有用，过多的规则 agent 记不住；修改后需新开会话才能生效。
• AGENTS.md 与 CLAUDE.md 分工明确：前者放通用项目规则，后者放 Claude Code 专属配置。推荐在 CLAUDE.md 中通过 @AGENTS.md 引用通用规则。
• Claude Code 的 Memory 是本地经验记录，用于临时记忆；应定期将反复出现的提示提炼到 AGENTS.md，实现规则的持续沉淀。
• 团队协作时，规则应放入仓库（AGENTS.md 或 CLAUDE.md + @），而非仅依赖本地全局配置，确保所有成员行为一致。

意义与影响

AGENTS.md 的合理运用能够从根本上改善 AI 辅助开发的效率和稳定性。它让 AI agent 在进入项目时即获得清晰、结构化的规则约束，从而减少“漫无目的”的代码生成、避免随意修改文件、强制遵循测试验证流程。这不仅降低了 bug 率和返工率，还显著节省了 token 消耗（不再需要反复重复提示）。

更重要的是，AGENTS.md 作为开放标准