CLAUDE.md、AGENTS.md、GEMINI.md：AI编程助手指令文件配置指南

AI编程助手在每次会话开始前都会读取一个指令文件，但你真的清楚里面写了什么吗？这个文件就像留给新队友的一张便签，告诉AI如何运行测试、遵循什么代码风格、哪些操作绝对不能碰。不同工具给这张便签起了不同的名字：Claude Code 用 claude.md，Codex 和 Cursor 认 agents.md，Gemini CLI 则用 gemini.md。混乱的命名背后，其实有一套清晰的协作逻辑。

指令文件到底是什么？

指令文件是一份纯文本说明，存放在项目目录或个人主目录中，AI助手在每次会话启动时自动读取。它的内容不需要复杂，核心是回答一个问题：一个新队友上手前必须知道什么？

据 YouTube 频道 AI Academy 的讲解，一份好的指令文件至少覆盖三件事：如何运行测试、项目的代码风格、以及“永远不要做”的禁区清单。这相当于把团队的口头约定固化成AI可执行的上下文，减少每次对话重复解释的成本。

你可能没注意到，指令文件不是越厚越好。AI Academy 建议从最小可用版本开始，先写清测试命令、风格约定和优先询问事项，再根据实际磨合逐步补充。

AI 编程助手的指令文件在技术上属于系统提示（system prompt）的一部分。模型本身不保留跨会话记忆，每次新会话都从零开始，指令文件的作用就是在会话初始化时把项目约定注入上下文，相当于一种轻量级的检索增强。与把规则写进对话相比，指令文件的优势是自动加载、无需重复输入，并且可以纳入版本控制。其局限在于占用上下文窗口，内容越长，留给实际代码和对话的 token 越少，过长还可能稀释关键指令的权重。因此实践中建议控制在几百行以内，把高频、硬性约束放前面，细节性说明按需拆分到独立文档中引用。

项目文件与用户文件：分工与优先级

指令文件有两个存放位置，职责截然不同。

项目文件放在代码仓库里，随项目一起共享给团队所有成员，承载的是团队共识——测试怎么跑、分支怎么建、代码评审的硬性要求。用户文件放在个人主目录下，只对你自己生效，但会作用于你参与的每一个项目，适合放个人习惯，比如“添加新依赖包之前必须先询问”。

两者冲突时谁赢？答案有些反直觉：**多数情况下不存在覆盖关系，AI会把两份文件合并读取，只是读取顺序上更靠近当前项目的那份排在最后。**这意味着后读的内容在语义上权重更高，但并非简单的“项目覆盖用户”或反之。实际配置时，把团队规则放项目文件、个人偏好放用户文件，就能自然形成合理的分层。

AI 编码助手在启动会话时，通常会将多个来源的上下文拼接成一段系统提示：用户级配置、项目级配置以及会话中附加的文件内容。不同工具对上下文的 token 预算有限，当合并后的内容过长时，靠近末尾或优先级更高的部分更容易被模型关注。这也是为什么后读取的项目文件在语义上权重更高。需要注意的是，合并读取意味着冲突指令可能同时存在，模型未必严格按“覆盖”处理，而是综合理解。因此两份文件中应避免给出直接矛盾的指令，例如项目文件要求提交前运行全部测试、用户文件却允许跳过测试，这类冲突会导致 AI 行为不稳定。

各工具命名差异与 AGENTS.md 的跨平台价值

生态碎片化是当前最现实的痛点。Claude Code 读 claude.md，Codex 读 agents.md，Gemini CLI 读 gemini.md，Cursor 则使用自己的规则文件体系。同一个团队混用多种工具时，维护多份内容雷同的指令文件既冗余又容易不同步。

AGENTS.md 正在成为公约数。据该视频介绍，Codex 和 Cursor 直接读取 agents.md；Gemini 需要一项设置才能识别；Claude Code 仅在缺少 claude.md 时才会退回到它。换言之，agents.md 已是一种开放标准，由 Linux Foundation 维护。

对混合工具团队，AI Academy 给出的实操建议是：**以 agents.md 作为单一事实来源，然后在 claude.md 中用一行指向它。**这样既保留了 Claude Code 的原生入口，又避免了内容分叉。

AGENTS.md 是由 OpenAI 发起、后交由 Linux Foundation 旗下 Agentic AI Foundation 维护的开放约定，用于描述 AI 编码代理在仓库中应遵循的指令。其设计目标是为不同厂商的编码代理提供统一的上下文入口，避免每个工具各自定义规则文件造成碎片化。它采用普通 Markdown 格式，无需特定 schema，阅读对象是 AI 代理而非人类开发者，因此内容通常聚焦构建命令、测试运行方式、代码风格与安全禁区。目前包括 Codex、Cursor、Gemini CLI、Aider 在内的多种工具已支持或可通过设置启用对 AGENTS.md 的识别，使其逐步成为跨工具协作的事实标准。

落地建议：从最小文件开始

配置指令文件的门槛比想象中低。起步阶段不必追求完备，先把三件事写清楚：测试怎么跑、代码风格是什么、遇到不确定的情况先问什么。这三条覆盖了AI协作中最容易出错的环节。

随着项目演进，再按需补充构建命令、目录结构约定、提交信息规范等内容。关键是让文件保持精简可维护——一份没人愿意更新的冗长指令文件，对AI和人类队友都是负担。

对于多工具并存的团队，尽早统一到 agents.md 并做好指向配置，能省下大量同步成本。指令文件虽小，却是AI编程协作流程中确定性最高、投入产出比最划算的一环。