如果关注 AI 编程和 AI Agent 的使用体验你大概率遇到过这种情况同一个项目昨天和 AI 聊得好好的今天打开新会话它又忘了项目结构、忘了你指定的代码风格、忘了测试命令。每次都要重新把背景资料粘贴一遍甚至要把关键文件的路径重新告诉它。这个问题不是模型不够聪明而是对话没有持久记忆。这次我们来看 AGENTS.md 的思路。它不依赖复杂的向量数据库也不需要微调模型核心就是一个容易被 AI 代理读取的项目级记忆文件。目标很直接让 AI 在每次新对话里都能快速恢复对项目的“长期记忆”知道自己该用什么命令、遵循什么规范、注意什么约束。这篇文章会从 AGENTS.md 的概念、标准格式、目录组织、工具接入到实际验证完整过一遍落地方法。如果你平时用 Claude Code、Cursor、Codex 这类 AI 编程工具或者正在给团队搭 AI 协作规范这篇文章可以直接收藏。1. 核心能力速览能力项说明项目类型AI 代理协作规范 / 项目记忆文件标准核心作用为 AI 编程代理提供项目级长期记忆减少重复说明文件本质纯 Markdown 文本文件无需 GPU、无需显存、无推理负担主要功能记录项目命令、代码规范、架构说明、禁止事项、测试流程放置位置项目根目录也可在用户全局目录配置全局记忆兼容工具Claude Code、Codex、Cursor 等主流 AI 编程代理及部分 IDE 插件均支持同类规范文件是否支持远程仓库支持文件可直接提交到 Git 仓库团队共享是否支持批量任务不直接涉及但可借助脚本批量检查文件生效情况适用场景个人项目、团队协作、开源仓库、AI 自动化任务AGENTS.md 不是一个模型也不是一个服务。它是“给 AI 看的 README”。项目里放一份结构化的 Markdown 文件AI 代理在启动时会自动读取它然后按照文件里的约定处理任务。相比每次手动粘贴背景这种方式更稳定、更统一也更容易维护。2. 适用场景与使用边界2.1 适合谁经常用 AI 编程代理改代码的人AGENTS.md 可以在新会话里快速恢复项目背景减少重复描述。团队协作场景把项目命令、代码风格、分支规范写进文件团队成员和 AI 使用同一套约束。开源项目维护者给仓库加上 AGENTS.md外部贡献者用 AI 辅助开发时也遵循项目既有约定。需要跑自动化任务的人AI 代理读取文件后能独立完成多步骤任务比如构建、测试、提交。2.2 能解决什么问题新会话遗忘问题AI 读完文件后能恢复项目关键信息。团队规范统一问题不同人用 AI 时提示词习惯不同统一文件降低差异。重复劳动问题不再需要每次把项目结构、命令、要求粘贴给 AI。2.3 不适合什么场景不适合存储机密信息AGENTS.md 通常提交到仓库密码、Token、内网地址不要写在里面。不适合当数据库用文件适合存放稳定的项目事实不适合频繁变化的任务状态。不适合替代代码注释它描述项目层面约定不能替代代码内的必要注释。不适合超大文件堆砌AI 上下文有限文件过于冗长反而浪费 token。2.4 合规与安全边界AGENTS.md 本质上是一个文本文件本身没有特殊安全风险。但使用时需要明确不要把任何敏感凭据、私有接口地址、客户数据写进仓库内的 AGENTS.md。如果项目涉及人脸、声音、版权素材、用户隐私数据AI 辅助开发时需要进一步确认数据来源和授权。团队内部规范文件如果涉及商业策略建议放在私有仓库或内网。3. 为什么普通提示词不够用先看一个典型场景。你在终端里让 AI 代理修改一个模块第一轮对话里告诉它“项目用 pnpm测试用 vitest接口在 src/api 下”。AI 执行得很好。第二天新开会话它又不知道 pnpm 了也不知道测试命令是什么。原因很简单大模型本身没有记忆每轮对话都是独立的上下文只来自当前会话中你提供的消息、工具返回结果以及它读取的文件。解决方法有两个方向给模型塞更多上下文每次手动粘贴项目说明或者把文件内容写进系统提示词。让 AI 自己去读项目里的记忆文件这就是 AGENTS.md 的核心思路。对比一下方式持久性维护成本团队一致自动生效手动粘贴说明低每次新会话都要重复高差否系统提示词全局配置中只在本机生效中差是AGENTS.md 项目文件高随仓库走低修改一次长期有效好是AGENTS.md 的价值就是把“项目背景知识”从临时对话里抽出来固化成仓库里的一个文件。AI 每次进入项目都能主动读取相当于给 AI 配了一份长期有效的“入职手册”。4. 环境准备与前置条件AGENTS.md 对硬件没有任何特殊要求。不需要 GPU不需要 CUDA也不需要特定的内存大小。它的载体就是一个 Markdown 文件任何文本编辑器都能编辑。准备清单如下4.1 基础条件一个项目目录比如my-project/。Git 仓库可用方便提交和共享。安装了至少一个支持 AGENTS.md 或同类规范文件的 AI 编程工具比如 Claude Code、OpenAI Codex、Cursor。文本编辑器比如 VS Code、Neovim用来编辑 Markdown 文件。4.2 验证工具条件不同工具对规范文件的命名稍有差异工具/生态文件名示例AGENTS.md 通用规范AGENTS.mdAnthropic Claude CodeCLAUDE.mdOpenAI CodexAGENTS.mdCursor.cursorrules / .cursor/rules 目录实际使用时以你当前工具的官方文档为准。下面统一用 AGENTS.md 作为主文件名说明。4.3 磁盘与目录AGENTS.md 文件本身只有几 KB 到几十 KB磁盘空间可以忽略。推荐的项目目录结构my-project/ ├── AGENTS.md ├── README.md ├── docs/ │ └── architecture.md ├── src/ ├── package.json └── .gitignore建议把 AGENTS.md 放在项目根目录这样 AI 代理扫描项目时最容易发现它。5. 从零创建 AGENTS.md5.1 基本语法与结构AGENTS.md 不是标准组织强制定义的格式而是社区形成的一套惯例。核心是使用 Markdown 的结构化信息让 AI 能快速解析。推荐的结构# 项目名称 ## 项目概述 用 2-3 句话说明这个项目是做什么的、技术栈是什么。 ## 常用命令 - 安装依赖pnpm install - 启动开发环境pnpm dev - 运行测试pnpm test - 构建产物pnpm build - 代码检查pnpm lint ## 项目架构 - 前端框架React TypeScript - 后端服务Node.js Express - 数据库PostgreSQL - 主要目录 - src/components 页面组件 - src/api 接口层 - src/utils 工具函数 ## 代码规范 - 使用 TypeScript 严格模式 - 组件使用函数式组件和 Hooks - 样式使用 CSS Modules - 提交信息遵循 Conventional Commits ## 测试要求 - 新增功能必须补充单元测试 - 涉及接口的修改需提供测试用例 - 使用 vitest 运行测试 ## 注意事项 - 不要在代码中硬编码 API 地址 - 不要修改 src/api 下接口函数的签名 - 涉及数据库迁移需单独提交文件写得越结构化AI 越容易理解。不要写大段散文尽量用列表、短句和明确命令。5.2 项目级与全局级配置项目级 AGENTS.md 放在项目根目录随仓库共享。如果你有多个项目都需要遵守同样的个人偏好可以在用户目录配置一个全局文件。以 Claude Code 为例全局记忆通常放在用户配置目录。文件命名建议用 CLAUDE.md 或 AGENTS.md具体看工具的扫描规则。全局文件的典型内容# 个人开发偏好 ## 常用环境 - 默认使用 pnpm 作为包管理器 - Python 虚拟环境使用 uv - 终端优先使用 zsh ## 代码风格 - TypeScript 函数优先使用箭头函数 - 命名使用 camelCase - 组件文件使用 PascalCase ## 工作流 - 修改代码前先运行测试 - 提交信息使用英文 - 避免生成不必要的注释项目级文件和全局文件同时存在时项目级文件通常会覆盖全局中的对应条目。这个行为具体取决于代理工具的实现。5.3 编写高质量 AGENTS.md 的原则写这个文件时可以把它当作给 AI 的“入职文档”。要避免自说自话尽量站在 AI 的角度思考它缺少哪些信息。第一条原则是只写稳定的项目事实。命令、目录结构、架构决策、代码风格、禁止事项都比较稳定。临时任务、当前迭代进度不适合写进去。第二条原则是控制文件长度。文件太长会消耗上下文窗口还容易淹没重点。核心信息放在最前面。可以按“概述、命令、架构、规范、测试、注意”的顺序组织。第三条原则是用祈使句。AI 擅长执行指令文件内容写清“使用 xxx”“运行 xx”“不允许 xx”效果比描述性文字更好。第四条原则是保持单一事实来源。AGENTS.md 里写了测试命令之后就不要再在 README 或 docs 里用不同的命令描述同一件事。如果命令变动优先更新 AGENTS.md。5.4 一个更完整的实战示例下面是一个前后端分离项目的 AGENTS.md 参考# my-awesome-project ## 项目概述 本项目是一个任务管理 Web 应用。前端使用 React TypeScript Vite后端使用 Node.js Express数据存储使用 MongoDB。支持用户注册、任务创建、任务状态流转。 ## 常用命令 - 安装前端依赖cd frontend pnpm install - 安装后端依赖cd backend pnpm install - 启动前端开发服务cd frontend pnpm dev - 启动后端开发服务cd backend pnpm dev - 运行全部测试pnpm test - 前端构建cd frontend pnpm build - 代码检查pnpm lint ## 项目架构 - frontend/src/api 封装所有后端接口请求 - frontend/src/components 存放可复用的 UI 组件 - frontend/src/pages 存放页面级组件 - backend/src/routes 维护 HTTP 路由 - backend/src/controllers 处理业务逻辑 - backend/src/models 定义数据模型 ## 代码规范 - TypeScript 开启 strict 模式禁止使用 any - React 组件统一使用函数组件禁止使用 class 组件 - API 请求统一走 src/api 下的封装函数禁止直接调用 axios - 向后端传参使用 camelCase - 文件命名组件和页面使用 PascalCase工具函数使用 camelCase ## 测试要求 - 新增工具函数需要补充单元测试测试文件与源码同目录 - 新增页面需要补充冒烟测试 - 测试命名要能说明意图例如 should return error when task not found - 运行测试前确认前端和后端依赖都已安装 ## 注意事项 - 不要在后端返回未经脱敏的用户手机号 - 所有数据库变更必须通过迁移脚本执行禁止手动改库 - 不要将 .env 文件内容提交到 Git - 新增第三方依赖前需评估包体积和维护状态 ## 提交规范 - 提交信息使用 Conventional Commits 格式 - 提交前必须运行 pnpm lint 和 pnpm test这份文件可以直接放进项目根目录然后让 AI 代理读取并尝试回答问题。下面说如何验证生效。6. 让 AI 代理真正读到 AGENTS.md6.1 确认工具读取机制不同 AI 编程工具对规范文件的自动扫描机制不一样。以 Claude Code 为例它启动会话时会读取当前项目目录下的 CLAUDE.md 文件作为上下文。OpenAI Codex 也支持 AGENTS.md。Cursor 支持将 AGENTS.md 或项目规则文件作为指令上下文。实际使用中可以按以下步骤确认在项目根目录放置 AGENTS.md。启动 AI 编程工具。直接提问“这个项目的测试命令是什么”。观察 AI 的回答是否来自 AGENTS.md 中的内容。如果回答不出来检查工具支持的文件名和读取规则。6.2 验证 AGENTS.md 是否生效的测试方法推荐做一组基础验证第一项验证是项目信息读取。问 AI“根据项目记忆文件这个项目的技术栈是什么”预期能回答出 AGENTS.md 中记录的 React、TypeScript、Node.js 等信息。第二项验证是命令执行。问 AI“这个项目怎么运行测试”它会根据文件内容给出对应命令。第三项验证是规范执行。让 AI 创建一个新的 React 组件观察它是否使用了函数组件而不是 class 组件。如果 AGENTS.md 中写明了“禁止使用 class 组件”它应当遵循。第四项验证是多个会话一致性。新开一个会话重复第一个问题观察回答是否一致。如果上述测试都能通过说明 AGENTS.md 已经生效。如果部分失败比如 AI 没有读取文件需要检查工具的规则文件名、文件位置和工具的上下文开关。6.3 文件放置位置的影响AI 编程代理通常只扫描当前目录或项目根目录下的规范文件。如果你把 AGENTS.md 放在子目录里大部分工具不会自动读取。最简单的做法是放在项目根目录并在 README 中加一个链接引用。如果使用了 monorepo可以考虑每个子包放一个 AGENTS.md根目录放一个总文件。这样既能在子包内约束具体命令又能在根目录描述整体架构。不过要注意文件数量增加会占用更多上下文需要根据实际情况权衡。7. 让 AI 工具自动加载 AGENTS.md7.1 Claude Code 与 CLAUDE.mdClaude Code 是最早推广“项目记忆文件”的工具之一。它支持在项目根目录使用 CLAUDE.md也支持在用户配置目录使用全局 CLAUDE.md。使用方式很简单在项目根目录创建 CLAUDE.md。编辑内容记录项目命令、规范、架构。重启 Claude Code 会话让文件生效。如果团队项目里已经存在 AGENTS.md也可以复制一份内容到 CLAUDE.md或者使用 import 语法引入其他文件。部分工具支持在 CLAUDE.md 中使用path/to/file的方式引用其他文档具体语法需要参考对应工具文档。7.2 OpenAI Codex 与 AGENTS.mdCodex 是 OpenAI 的编程代理支持 AGENTS.md 作为项目指令文件。使用时同样放在项目根目录。它和 Claude Code 的主要区别是文件命名和上下文策略。格式依然是 Markdown。7.3 Cursor 的规则文件Cursor 支持.cursorrules文件后来增加了.cursor/rules目录可用于按目录粒度维护规则。它也会扫描 AGENTS.md 作为项目上下文。如果你从 Claude Code 切换到 Cursor可以把 CLAUDE.md 的内容迁移到 .cursorrules 或 AGENTS.md基本不需要大改。不同工具的差异主要体现在文件命名和加载优先级。底层逻辑一致用 Markdown 描述项目事实和指令代理自动读取并执行。因此团队里维护一份标准 AGENTS.md再按工具要求复制或软链接到对应文件名是兼容性最高的做法。7.4 命令行方式验证加载如果你习惯用命令行可以直接让 AI 代理读取文件再用脚本检查。例如# 在项目根目录查看 AGENTS.md 是否生效 cat AGENTS.md # 询问 AI 代理时让它先读取文件再回答在 Claude Code 里可以这样提问请先阅读项目根目录下的 CLAUDE.md然后告诉我 1. 项目的运行命令是什么 2. 项目的代码规范有哪些 3. 是否存在禁止事项如果代理没有读取回答会和你预期不一致。这时检查文件是否命名为工具要求的名字以及路径是否正确。8. 多工具共用与团队协作8.1 一份文件多处引用如果团队成员有人用 Claude Code有人用 Cursor有人用 Codex最好的方式是在仓库里维护一份规范的 AGENTS.md然后通过软链接或复制生成其他工具需要的文件名。例如在项目根目录创建 AGENTS.md 后可以建立软链接ln -s AGENTS.md CLAUDE.md注意Windows 下创建软链接需要管理员权限。如果不方便直接复制一份内容也可以但要注意同步更新。更稳妥的方式是在 AGENTS.md 里直接写清楚所有约定然后其他文件通过引用方式携带。如果工具支持import语法可以这样做# CLAUDE.md - Claude Code 项目指令 此文件内容由 AGENTS.md 自动维护修改前请先更新 AGENTS.md。 import ./AGENTS.md不同工具的 import 语法不完全一致使用前需要确认当前工具是否支持。如果不支持维护一份主文件加软链接即可。8.2 提交到 Git 仓库AGENTS.md 应该提交到 Git 仓库吗建议提交。理由如下新成员克隆仓库后AI 工具可以直接读取项目规范。CI/CD 流程可以校验 AGENTS.md 是否存在避免团队忘记维护。代码评审时可以同步审查文件变更。仓库里的 AGENTS.md 不建议包含个人偏好比如个人常用快捷键、个人终端配置。个人偏好放到用户全局文件里。8.3 团队评审规则如果团队要推行 AGENTS.md可以把它当作一个普通代码变更来评审。新增、修改命令时要确认命令确实可用。删除规范时要评估是否影响 AI 代理行为。建议写进 Pull Request 模板里要求涉及项目级规范的变更必须同步更新 AGENTS.md。9. 批量检查与集成到自动化流程AGENTS.md 不直接提供 API但可以配合脚本实现批量检查。比如检查仓库里所有子项目的 AGENTS.md 是否都包含关键命令。以下是一个简单的脚本示例用 Python 遍历目录并检查文件import os from pathlib import Path def check_agents_files(root: Path): 检查项目根目录和一级子目录中是否存在 AGENTS.md。 required_sections [## 常用命令, ## 项目架构, ## 注意事项] missing [] for path in root.rglob(AGENTS.md): content path.read_text(encodingutf-8) for section in required_sections: if section not in content: missing.append((str(path), section)) return missing if __name__ __main__: project_root Path(.) problems check_agents_files(project_root) if problems: for file, section in problems: print(f[WARN] {file} 缺少 {section}) else: print([OK] 所有 AGENTS.md 均包含完整结构)运行方式python check_agents.py这套检查可以挂到 pre-commit hook 里。需要留意的是AGENTS.md 不是可执行程序它只能约束 AI 代理的行为不能直接拦截代码提交。真正的约束还要靠 CI、lint、测试用例来保证。10. 资源占用与性能观察AGENTS.md 不占显存、不占推理资源适合所有本地开发环境。它影响性能的地方主要在上下文占用和文件读取时间。上下文占用方面AGENTS.md 每多 100 行大约会增加几千 token 的上下文消耗。对长会话影响不大但如果文件短则建议控制在 200 行以内。使用时可以通过工具查看上下文占用状态。文件读取时间方面纯文本文件读取极快不影响启动速度。但如果用 import 引用了大量子文档读取时间会线性增加。建议只在真正必要时引用子文档。显存方面AGENTS.md 本身不涉及 GPU。如果你同时运行本地大模型来辅助编程那个时候的显存占用取决于模型大小与 AGENTS.md 无关。如果你用的是云服务编程代理资源占用基本不影响本地机器。降低上下文占用的技巧只写核心命令和规范删除冗余描述。避免在每个子包放相同文件合并到根目录。将长文档拆到 docs/ 目录在 AGENTS.md 中使用引用链接。定期删除已失效的命令和规范。11. 常见问题与排查方法问题现象可能原因排查方式解决方案AI 代理没有遵循 AGENTS.md 中的规范文件名不符合工具要求检查工具支持的文件名列表将文件命名为 CLAUDE.md、AGENTS.md 或对应规则文件名新会话中仍然遗忘项目信息文件不在项目根目录确认文件路径移动到项目根目录文件内容被截断或没有完全读取文件过长查看工具的上下文日志精简文件拆分引用文档团队成员的 AI 行为不一致个人全局配置覆盖项目配置对比全局文件和项目文件在项目文件中明确优先级规则或删除冲突配置修改 AGENTS.md 后 AI 仍然使用旧信息会话未重启新开会话测试重启AI编程工具目录下有多个规范文件时冲突多个工具互相读取不同文件检查所有规范文件内容合并为一个主文件其他文件使用软链接或引用无法验证是否生效没有做对照测试分别做新老会话提问测试按 5.2 节方法逐项验证补充两个常见判断方法观察输出中是否包含 AGENTS.md 特有的表述。如果文件里写的是 “禁止直接调用 axios”AI 回复中体现了这一规则说明文件已生效。检查工具日志。Claude Code 和部分代理工具会打印读取的上下文文件列表如果有该文件就能确认读取成功如果没找到说明路径或命名有问题。如果确认文件已读取但 AI 仍然不遵循多数是因为上下文太长或提示词被其他指令覆盖。可以尝试把关键禁止事项写在文件最前面或重复强调一次。12. 最佳实践与使用建议12.1 第一次先做小范围测试不要一开始就把全部项目规范写进去。先在项目根目录写一个只有 20 行的 AGENTS.md记录运行命令和测试命令。新开会话让 AI 执行一次测试或修改操作确认它可以读取并执行。验证通过后再逐步补充架构说明和代码规范。12.2 保留一套最小可运行配置建议把最小配置存放在仓库的 AGENTS.md 中。一旦不生效可以删掉复杂内容回到最简版本排查问题。最小配置包括四部分项目概述、常用命令、目录结构、禁止事项。12.3 分目录管理文件与素材AGENTS.md 是“项目说明书”不适合承担太多杂项。建议在项目里建立 docs/ 目录存放详细设计、架构图、API 文档。AGENTS.md 里只需要写清楚哪个文档对应什么内容。12.4 建立更新与评审节奏可以结合 PR 流程来维护。每次涉及命令、依赖、目录结构变更时要求 PR 里同步更新 AGENTS.md。如果使用 GitHub Actions 或 GitLab CI可以加一个检查步骤当 package.json 或项目配置文件变动时提示开发者确认 AGENTS.md 是否同步更新。# .github/workflows/check-agents.yml 示例 name: Check AGENTS.md on: pull_request: types: [opened, synchronize] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Check AGENTS.md exists run: test -f AGENTS.md echo AGENTS.md found || echo AGENTS.md missing这个示例只做文件存在性检查团队可以根据需要扩展内容校验。12.5 与 README 的分工README 面向人类读者AGENTS.md 面向 AI 代理。两者可以放相同信息但 AGENTS.md 应该更精简、更指令化。建议在 README 中增加一个链接## AI 协作规范 项目包含 AGENTS.md记录 AI 代理需要遵循的命令、架构和代码规范。修改项目级配置时请同时更新该文件。12.6 安全合规建议不要将以下内容写入 AGENTS.md数据库连接串、API Key、Token、密码。生产环境 IP、内部域名。未公开的商业策略、客户信息。个人敏感信息。如果 AGENTS.md 面向公开仓库默认按公开内容对待。需要私有信息时使用工具自己的配置系统例如 Claude Code 的权限管理或本地环境变量。13. 总结与下一步AGENTS.md 不是一个复杂的系统但它能有效解决 AI 编程中“一次性对话”的痛点。把项目级事实写成结构化 Markdown让 AI 代理每次启动都读取等于给 AI 装了一份持续有效的项目记忆。它不需要 GPU、不需要额外服务、不占显存改一个文件就能发挥作用。建议你现在就做的第一件事打开项目根目录创建一份 30 行以内的 AGENTS.md写下项目概述、运行命令、测试命令和三条最重要的禁止事项。然后用 AI 代理新开一个会话问一句“这个项目的测试命令是什么”。你会立刻看到变化。最容易踩的坑有三个文件名和工具不匹配、文件放错目录、内容写得太长。如果 AI 代理没有生效优先排查前两个。内容过长导致上下文溢出时先精简到核心命令再逐步扩展。后续可以继续扩展的方向包括为 monorepo 配置多级 AGENTS.md、把 AGENTS.md 接入 pre-commit 自动校验、在团队内建立统一的 AI 协作规范模板、研究工具特有的 import 语法和动态指令能力。AGENTS.md 这个思路本身还在演化中但“让 AI 通过稳定文件获得长期记忆”的方向已经足够明确越早用上越省事。