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

AI 编程代理每次开始会话前，都会先读一份指令文件。你有没有检查过自己那份文件里写了什么？

这类文件本质上是一份纯文本笔记，作用类似于给新同事留的交接说明。不同工具对它的命名各不相同——Claude Code 读的是项目根目录下的 claude.md，Codex 读 AGENTS.md，Gemini CLI 读 GEMINI.md，Cursor 则使用自己的规则文件体系。理解这些文件的加载逻辑与优先级，是让 AI 代理真正按团队规范干活的前提。

指令文件到底该写什么

判断标准很简单：一个新同事入职第一天必须知道的事，就应该写进去。具体包括三类内容——怎么跑测试、代码风格约定、以及绝对不允许做的事。

这三类信息的共同点是：它们不体现在代码本身，但违反了就会出问题。测试命令写错，代理会把时间浪费在无效验证上；风格约定缺失，产出的代码需要人工反复返工；禁止事项不明确，代理可能做出破坏性操作。

原文的建议是"从小的文件开始"，先写清楚怎么测试、你的风格、以及哪些事必须先问。不要试图一开始就把所有规范塞进去，指令文件的价值在于精准，而非篇幅。

系统提示（System Prompt）与指令文件的区别：AI 编程代理的指令来源通常分层。系统提示由工具厂商内置，定义代理的基础行为准则（如安全边界、工具调用格式），用户无法修改；而指令文件是用户可编辑的持久化上下文，在每次会话初始化时被注入到系统提示之后，作为项目专属的补充约束。二者共同构成代理的“初始记忆”，但指令文件更灵活、更贴近具体工程实践。理解这一分层有助于避免混淆：你不能通过指令文件覆盖厂商设定的安全策略，但可以精细控制代码风格、测试流程等项目级行为。

项目级与用户级：两个位置，两种职责

指令文件有两个存放位置，职责划分清晰：

项目文件放在项目仓库里，团队共享，进版本控制。团队共同遵守的事实写在这里——测试怎么跑、分支规范、代码审查要求。

用户文件放在用户主目录下，只属于你个人，对所有项目生效。个人习惯写在这里，比如"添加依赖包之前必须先问我"。

这个划分解决了一个常见困惑：同一条规则，该团队共享还是个人私有？答案是看它是否与具体项目绑定。团队约定进项目文件，个人偏好进用户文件。

版本控制与指令文件：项目级指令文件通常应纳入 Git 等版本控制系统，以便团队共享和审计。但需注意，某些工具（如 Cursor）的规则文件可能包含本地路径或敏感配置，建议在 .gitignore 中排除用户级文件（如 ~/.claude/CLAUDE.md），仅提交项目根目录下的共享文件。此外，合并冲突时，指令文件的变更应像代码一样经过代码审查，确保规则变更是团队共识而非个人随意修改。

同时存在时谁生效：代理会合并而非二选一

很多人以为项目文件和用户文件是互斥的，实际上多数代理会把两者合并读取，并且读取顺序上更靠近当前项目的文件排在后面——也就是说，项目文件的优先级在时序上更高。

这意味着你不需要在项目文件里重复用户文件的内容，代理会自己叠加。反过来说，如果两边写了冲突的规则，最终行为取决于合并逻辑，容易产生难以排查的偏差。保持两份文件职责不重叠，比纠结优先级更重要。

各代理的命名差异与 AGENTS.md 的通用地位

命名不统一是这套机制最容易被忽视的坑：

• Codex：AGENTS.md
• Gemini CLI：GEMINI.md
• Cursor：自有规则文件
• Claude Code：claude.md

有一个名字是共享的——AGENTS.md。Codex 和 Cursor 可以直接读取它；Gemini 需要额外设置才能识别；Claude Code 则只在没有 claude.md 的情况下才会读 AGENTS.md。

这个细节对混合技术栈团队影响很大。如果你的团队里有人用 Claude Code、有人用 Codex，只维护一份 claude.md 意味着 Codex 用户拿不到任何指令。

AGENTS.md 开放标准的具体内容：AGENTS.md 是一个由社区推动、Linux Foundation 托管的开放规范，旨在为 AI 代理提供统一的项目指令入口。它不定义具体语法，而是约定文件位置和基本结构（如使用 Markdown 标题划分章节），使不同代理能按相同方式解析。目前，Codex、Cursor 等工具已原生支持，Gemini CLI 需通过配置启用，Claude Code 则将其作为后备。该标准降低了多工具协作的维护成本，但尚未被所有厂商采纳，实际使用时需确认所用代理的兼容性。

混合团队的最优解：一份 AGENTS.md + 一行指向

原文给出的方案很直接：保留 AGENTS.md 作为唯一事实来源，然后在 claude.md 里用一行指向它。这样 Codex 和 Cursor 原生读取，Gemini 通过设置接入，Claude Code 则通过指向文件间接获得同一套规则。

支撑这个方案的是一个关键事实：AGENTS.md 目前已是开放标准，由 Linux Foundation 维护。这意味着它不绑定任何单一厂商，作为团队级指令文件的载体具备长期稳定性。相比把规范锁死在某个工具的私有格式里，押注开放标准是更稳妥的选择。

实操建议

上手时不必追求完备。先建立最小可用的指令文件，覆盖测试命令、代码风格、必须先询问的操作这三项，然后在实际协作中逐步补充。混合团队优先落地 AGENTS.md 单一来源方案，避免多份文件各自漂移导致代理行为不一致。

指令文件是代理行为的隐形约束层，写得好能显著减少返工和误操作，写不好则形同虚设——毕竟代理每次都会读它，而你未必每次都记得检查它。