AI 编程助手约束文件全解析：CLAUDE.md 和 AGENTS.md 到底怎么配？

上周有个朋友问我：「你用 AI 写代码，它怎么知道你们项目的规范？每次都要重新说一遍？」

说实话，半年前我也是这么干的——每次开新会话，先花五分钟铺垫背景：「我们项目用 Java 8，commit message 用中文，API 返回格式是 RestResult 包装……」说多了自己都烦。

后来才发现，不管是 Claude Code 还是 OpenCode，人家早就设计好了一套「约束文件」体系，专门解决这个问题。把规则写到配置文件里，AI 启动时自动读取，从此不用重复唠叨。

但坑就在这——两套工具的文件体系完全不一样，名字长得像功能却不同，搞混了轻则规则不生效，重则写了半天的配置全白费。今天就把这事掰扯清楚。

先搞清楚一件事：为什么需要约束文件？

AI 编程助手本质上是个「没有记忆的实习生」。每次新会话，它对你的项目一无所知。你不告诉它规矩，它就按自己的「常识」来——可能给你的 Java 8 项目写出 var 声明，给你的中文团队生成英文注释。

约束文件就是给这个实习生的「员工手册」：项目架构是什么、编码规范怎么定、哪些雷区不能碰。写一次，每次会话自动加载，省心。

目前主流的两个 AI 编程终端工具——Claude Code 和 OpenCode，都有自己的约束文件方案。接下来逐个拆解。

Claude Code：五层配置，各司其职

Claude Code 的配置体系设计得比较完整，文件类型多、分工明确。第一次看可能觉得复杂，但理解了分层逻辑之后会觉得挺合理的。

1. CLAUDE.md —— 核心指令文件

这是 Claude Code 最重要的配置文件，作用类似于「项目规章制度」。

它支持三个层级，全部同时生效、内容叠加：

划重点：三层不是互斥的，是叠加的。企业级说「禁止提交密钥」，项目级说「用 Java 8」，用户级说「回答用中文」——三条规则同时生效。只有冲突时才按优先级（企业 > 项目 > 用户）覆盖。

还有个容易忽略的细节——Claude Code 启动时会从当前目录向上遍历，每一层目录的 CLAUDE.md 都会被加载。你在 src/api/ 目录下启动，它会依次读取 src/api/CLAUDE.md、src/CLAUDE.md、根目录的 CLAUDE.md，全部叠加生效。

2. .claude/rules/*.md —— 模块化规则

CLAUDE.md 写多了会变成一个巨大的文件，不好维护。rules 目录就是用来拆分的。

目录名 rules 是固定的，不能改，但下面随便建子目录。项目级放 .claude/rules/，用户级放 ~/.claude/rules/（个人规则，跨项目生效）。两级同时存在时都会加载，但用户级先加载、项目级后加载，项目级优先级更高——冲突时以项目级为准。没有 paths 条件的 rules 文件，启动时就加载，优先级等同于 .claude/CLAUDE.md。

最实用的是条件加载——用 YAML frontmatter 的 paths 字段控制「什么时候加载这条规则」：

这样 Claude 只在碰到 API 模块代码时才读这条规则，不浪费上下文窗口。写后端的时候不会被前端规则干扰，反过来也一样。

3. MEMORY.md —— AI 自动记忆

这个文件不是你写的，是 Claude 自己写的。

当你在对话中纠正它——「以后 commit message 用中文」「我说的构建是指 mvn package」——Claude 会自动把这些偏好存入 MEMORY.md。下次新会话，它就记住了。

实际路径在：~/.claude/projects/<project-hash>/memory/MEMORY.md

注意：MEMORY.md 是按项目隔离的。你在 A 项目里教它的习惯，B 项目不知道。想跨项目生效的个人偏好，应该写 ~/.claude/CLAUDE.md。

4. .claude/agents/*.md —— 子代理定义

可以定义专门的子代理来执行特定任务。支持多个层级，同名子代理按优先级取高的那个：

每个子代理有独立的记忆目录，和主会话互不干扰。项目级的子代理可以提交到 Git，团队共享；用户级的是你个人的，跨项目通用。

5. .claude/skills/ —— 可复用技能

技能是可复用的工作流模板。每个技能是一个目录，里面有个 SKILL.md 入口文件。同名技能按优先级取高的：企业级 > 用户级（~/.claude/skills/） > 项目级（.claude/skills/）。注意这里用户级比项目级优先，跟 agents 的优先级方向是反的。

启动时只加载技能的描述信息（让 Claude 知道有哪些技能可用），完整内容在被调用时才加载，不浪费上下文。

OpenCode：AGENTS.md 一个文件打天下

相比 Claude Code 的五层体系，OpenCode 的方案简洁得多——核心就一个文件：AGENTS.md。

AGENTS.md —— 项目指令文件

AGENTS.md 放在项目根目录，作用等同于 Claude Code 的 CLAUDE.md（项目级）。OpenCode 启动时自动读取。

它也支持两个层级：

双层同时生效，内容叠加

跟 Claude Code 一样，OpenCode 的两层 AGENTS.md 也是同时生效、内容叠加的，不是互斥关系。

翻了一下 OpenCode 源码（instruction.ts），加载逻辑是这样的：

1. 项目级加载：从当前工作目录开始，向上遍历查找 AGENTS.md
   
   （也兼容 CLAUDE.md、CONTEXT.md），找到第一个匹配的文件名就停止（同一层只取一种）
2. 用户级加载：再从 ~/.config/opencode/AGENTS.md
   
    加载（也会检查 ~/.claude/CLAUDE.md，找到第一个就停止）
3. 两层结果叠加：项目级和用户级的内容一起注入到系统提示词里，全部生效

那冲突了怎么办？ 这里有个跟 Claude Code 的重要区别。Claude Code 有明确的优先级链：企业级 > 项目级 > 用户级，冲突时高优先级覆盖低优先级，是确定性行为。

但 OpenCode 没有显式的优先级覆盖机制。从源码看，它就是把所有指令文件的内容全部拼接注入系统提示词，冲突了怎么办——交给 LLM 自己判断。

实际效果上，项目级的内容在提示词中排前面，用户级排后面。根据 LLM 的一般行为倾向（后出现的指令会覆盖先出现的），用户级在冲突时可能占优。但注意，这不是 OpenCode 的设计保证，只是 LLM 的行为倾向，不同模型的表现可能不一样。

所以实战建议：尽量让项目级和用户级的指令互补而非冲突。项目级写项目特有的规范，用户级写跨项目的个人偏好，别在两边写矛盾的指令。

还有个容易忽略的细节——子目录也支持 AGENTS.md。跟 Claude Code 的行为类似，当 AI 在会话中读取某个子目录的文件时，OpenCode 会向上遍历该目录链，把路径上的 AGENTS.md 也按需加载进来。比如你的项目结构是这样的：

当 AI 读取 src/api/ 下的文件时，src/api/AGENTS.md 会被延迟加载并追加到上下文中。这个机制虽然没有 Claude Code 的 paths 条件加载那么精细，但也能实现一定程度的模块化规则管理。

兼容性小彩蛋

从源码还能看到一个有意思的设计：OpenCode 不只认 AGENTS.md，它的文件名查找列表是 ["AGENTS.md", "CLAUDE.md", "CONTEXT.md"]。也就是说，你的项目根目录放 CLAUDE.md 也能被 OpenCode 识别，不需要额外复制一份。不过它只取找到的第一个文件名，如果目录下同时有 AGENTS.md 和 CLAUDE.md，只会读 AGENTS.md（排在前面优先）。

缺失的能力

和 Claude Code 比，OpenCode 没有以下能力：

• 没有 rules 条件加载（不能按文件路径主动触发不同规则，但子目录 AGENTS.md 可以部分替代）
• 没有自动记忆（MEMORY.md）
• 没有子代理定义文件
• 没有企业级管理

不过 OpenCode 的 AGENTS.md 也不是只能写规则。它本质上是一个自由格式的 Markdown，你可以在里面写任何东西——项目架构、编码规范、工作流程、甚至人设定义。灵活度很高，就是全靠自觉维护。

OpenCode 的技能系统走的是另一条路——通过 ~/.config/opencode/skills/ 目录管理，每个技能是一个独立文件夹。这个和 Claude Code 的 skills 思路类似，但实现和调用方式不同。

正面对比：哪个适合你？

文件体系对比

加载机制对比

记忆机制对比

这是两者差异最大的地方：

简单说：Claude Code 像个「会记笔记的同事」，你纠正过的事它会自动记住；OpenCode 像个「什么都靠文档的新人」，规矩写在 AGENTS.md 里它才知道。

实战建议：两个工具都用的人怎么办？

如果你和我一样，Claude Code 和 OpenCode 都在用，有几个经验分享：

1. 核心规则两边都写

CLAUDE.md 和 AGENTS.md 的核心内容保持同步。项目规范、架构约束、编码标准——这些东西写一份，两边都放。

2. 个人偏好放对地方

3. 善用 Claude Code 的条件加载

如果项目模块多，把规则拆到 .claude/rules/ 下，用 paths 做条件加载。比 CLAUDE.md 写一大坨效率高得多。OpenCode 没有这个能力，只能在 AGENTS.md 里老老实实全写上。

4. 技能统一管理

两边的 skill 系统格式不同，没法直接复用。但核心逻辑可以共享——把技能的「知识部分」抽成独立 Markdown，然后分别包装成各自的技能格式。

常见误区

误区 1：CLAUDE.md 三层只能生效一个

错。 三层全部加载、全部生效，内容叠加。只有冲突指令才按优先级覆盖。

误区 2：MEMORY.md 可以跨项目

错。 MEMORY.md 按项目隔离。A 项目里教的习惯，B 项目不知道。跨项目偏好请写 ~/.claude/CLAUDE.md。

误区 3：两套工具的文件完全不互通

不完全对。 AGENTS.md 是 OpenCode、Gemini CLI 等工具使用的约定，Claude Code 确实不会读它。但反过来，OpenCode 其实能读 CLAUDE.md——前面「兼容性小彩蛋」说了，OpenCode 的文件名查找列表包含 CLAUDE.md，项目里只有 CLAUDE.md 没有 AGENTS.md 时，OpenCode 也能正常加载。所以不用刻意维护两份文件，用 CLAUDE.md 两边都能工作。

误区 4：约束文件写了就万事大吉

错。 约束文件不是法律，AI 有时候还是会犯规。特别是指令多的时候，优先级靠后的规则可能被「挤掉」。重要规则写在前面，定期检查 AI 是否遵守。

总结

约束文件是 AI 编程助手从「随机实习生」变成「靠谱队友」的关键。两套工具的设计哲学不同：

• Claude Code：精细化管理，分层叠加，条件加载，自动记忆——适合企业团队和重度用户
• OpenCode：简洁直接，一个 AGENTS.md 解决大部分问题——适合个人开发者和轻量使用

没有好坏之分，看你的使用场景。但不管用哪个，把约束文件写好是 AI 编程的基本功。花半小时写好配置，省的是以后每次会话反复解释的时间。

能跑不代表没问题，能用不代表用得好。配置文件这事，值得认真对待。

#AI编程 #ClaudeCode #OpenCode #AGENTS文件 #AI工具配置 #编程效率 #开发工具 #AIAgent #后端开发 #程序员工具 #claudemd #agentsmd