在实践 SDD（语义驱动开发）的过程中，一个常见的困惑是：AGENTS.md、CLAUDE.md 和 rules/ 目录，到底有什么区别？ 它们看起来都是给 AI 看的配置文件，但实际上承担着截然不同的职责。本文通过一个实际案例，帮你彻底理清这三者的边界和协作关系。

一、问题的由来：配置文件的"命名困惑"

最近在使用 OhMyOpenCode（OMO）时，执行 /init 命令后生成了一个 AGENTS.md 文件。这让我产生了一系列疑问：

“这个 AGENTS.md 和 Claude Code 的 CLAUDE.md 有什么区别？”
“项目级的 rules/ 目录又是什么作用？”
“这三者是互斥的还是互补的？”

这些问题的核心在于：AI 编程工具的配置体系缺乏统一的标准，不同工具使用不同的配置文件，容易造成混淆。理解它们的区别，是正确使用 SDD 工具链的前提。

二、核心区别：解决不同层面的问题

用一个类比来理解三者的关系：

配置文件	核心问题	类比
AGENTS.md	“谁来做？怎么协作？”	项目地图 + 协作协议
CLAUDE.md	“我是谁？遵循什么规范？”	单兵作战手册
rules/	“遇到 X 情况，执行 Y”	场景应对卡片

1. AGENTS.md：多 Agent 编排的"总指挥"

定位：OhMyOpenCode (OMO) 的多 Agent 编排配置文件
核心职责：定义"谁来做"和"怎么协作"

AGENTS.md = 项目地图 + 协作协议
    ├── 告诉 Agent 项目长什么样（目录结构）
    ├── 告诉 Agent 功能在哪里（快速定位表）
    └── 告诉 Agent 如何与其他模块协作（服务清单、接口契约）

典型内容：

项目概述与技术栈
目录结构与模块划分
常用命令（构建、测试、运行）
编码规范与命名约定
服务接口清单（Providers & Consumers）
中间件配置（缓存、数据库、RPC、MQ）
关键依赖版本
反模式清单（已知技术债务）

关键特征：

支持嵌套（子模块可有独立 AGENTS.md）
包含动态元信息（生成时间、Git Commit、分支）
强调模块间的协作关系

2. CLAUDE.md：单 Agent 的"行为规范"

定位：Claude Code 的项目级指令文件
核心职责：告诉一个 Claude 实例"在这个项目里你应该怎么表现"

CLAUDE.md = 单兵作战手册
    ├── 我是谁（角色定位）
    ├── 我遵循什么规范（编码风格、行为准则）
    └── 我使用什么工具（项目特定的工具链）

典型内容：

编码规范（缩进、命名、注释语言）
行为准则（如何处理错误、何时询问用户）
工具使用规范（构建工具、测试框架）
项目特定的最佳实践

关键特征：

通常项目级单一文件
聚焦单个 Agent 的行为规范
与 Claude Code 深度绑定

3. rules/：场景化的"规则片段"

定位：场景化规则存储目录
核心职责：特定场景下的行为指导

rules/ = 场景应对卡片
    ├── 遇到代码审查场景 → 执行 review-rules.md
    ├── 遇到测试生成场景 → 执行 test-rules.md
    └── 遇到文档生成场景 → 执行 doc-rules.md

典型内容：

特定任务的行为指导
条件触发的规则（“如果…那么…”）
细粒度的场景应对策略

关键特征：

按需匹配（文件名模式或条件触发）
细粒度、场景化
可被 AGENTS.md 或 CLAUDE.md 引用

三、对比总结：一张表理清边界

维度	AGENTS.md (OMO)	CLAUDE.md (Claude Code)	rules/ 目录
核心问题	“谁来做？怎么协作？”	“我是谁？遵循什么规范？”	“遇到 X，执行 Y”
定位	多 Agent 编排配置	单 Agent 项目指令	场景化规则片段
内容侧重	项目结构、模块划分、服务清单	编码规范、行为准则、工具使用	特定场景的行为指导
目标读者	多个协作的 Agent	单个 Claude Code 实例	按需加载的规则引擎
生成方式	`/init` 命令自动生成	手动创建或初始化生成	手动创建或模板生成
层级关系	支持嵌套（子模块独立）	通常项目级单一文件	扁平化或按场景分类
典型大小	较大（200-500 行）	中等（50-150 行）	较小（20-50 行/文件）

四、载体的时态属性：存量、对齐、迭代

理解了三种配置文件的边界之后，还有一个更底层的问题值得追问：这些载体，以及更广泛意义上的 Spec 文件，各自适合承载什么"时态"的信息？

这里的"时态"不是语法概念，而是工程概念——一份文档描述的是系统的过去（现状存量）、当下（需求对齐）还是未来（迭代步骤）？

时态	描述	典型载体
存量（系统现状）	系统当前是什么样的	`AGENTS.md`、`project.md`、`specs/`、`service-catalog.yaml`
对齐（需求共识）	这次要做什么、验收标准是什么	`proposal.md`、Gherkin 用户行为文档、PRD
迭代（执行步骤）	具体怎么做、分几步完成	`tasks.md`、系统行为 Gherkin、接口契约

这个分类并非学术游戏，而是有实际的工程含义：

存量载体的核心要求是准确。AGENTS.md 里的目录结构、service-catalog.yaml 里的服务能力，必须与代码库的实际状态保持同步。一旦存量信息过时，后续所有基于它生成的 proposal 和 tasks 都会偏离现实。这是 GIGO 在 AI 工程中最隐蔽的表现形式。

对齐载体的核心要求是可读性。proposal.md 和用户行为 Gherkin 必须让 PM 和研发都能读懂、都能确认。它的价值不在于技术精确，而在于消除歧义——让人类在 AI 开始写代码之前就达成共识。

迭代载体的核心要求是可执行性。tasks.md 和系统行为 Gherkin 是 AI 的直接输入，必须足够具体，让 Agent 能够按步骤执行，而不需要再做大量推断。

理解这三种时态，有助于在实践中做出正确的选择：不要用迭代载体（tasks.md）来记录存量，也不要用存量载体（AGENTS.md）来表达对齐意图。混用时态是 AI 工程中常见的配置混乱来源。

五、实际案例：一个 Java 项目的 AGENTS.md

以某隐私号码管理项目为例，其 AGENTS.md 结构如下：

# AGENTS.md - LSE2 Secret Number Project

**Generated:** 2026-03-16
**Commit:** 689592ad
**Branch:** feature/xxx

## Overview
Pandora Boot application for privacy number management...

## Structure
lse2-secret-number/
├── lse2-secret-number-service/   # Business logic
├── lse2-secret-number-start/     # Entry point
└── lse2-secret-number-client/    # Published library

## Where to Look
| Task | Location |
|------|----------|
| Core domain | `service/.../secretno/controller/` |
| Number pool | `service/.../numberpool/` |
| Diamond configs | `service/.../diamond/` |

## Commands
```bash
mvn clean install                    # Full build
mvn -pl lse2-secret-number-start pandora-boot:run  # Run

Conventions

Naming

Type	Convention	Example
Class	PascalCase	`SecretNoController`
Method	camelCase	`bindNumber()`

HSF Services

Providers

Service	Interface	Methods
`leadsService`	LeadsService	callRecordQuery, queryLeads…

Alibaba Middleware

Service	Purpose	Key Config
Tair	Cache	`CacheHandleService`
Diamond	Config	`service/.../diamond/`


这个 AGENTS.md 的核心价值：
1. **项目导航**：快速定位不同功能所在的目录
2. **协作契约**：服务接口清单让模块间协作有据可查
3. **上下文保存**：中间件配置、依赖版本等信息一目了然

# 五、"单一 Agent"概念的澄清

在讨论 CLAUDE.md 时，经常听到"单一 Agent 的项目级指令"这样的表述。这里的"单一 Agent"指的是：

> **Claude Code CLI 进程本身** —— 你在终端运行的 `claude` 命令，启动的一个交互式会话。

┌─────────────────────────────────────────────────────────┐
│ Claude Code CLI 进程（单一 Agent） │
│ ├── 读取 ~/.claude/CLAUDE.md（全局配置） │
│ ├── 读取 /CLAUDE.md（项目级指令） │
│ └── 读取 /.claude/rules/*.md（场景化规则） │
└─────────────────────────────────────────────────────────┘
vs
┌─────────────────────────────────────────────────────────┐
│ OhMyOpenCode (OMO) 多 Agent 系统 │
│ ├── AGENTS.md（总指挥配置：谁来做、怎么协作） │
│ ├── Agent A（专门处理 PRD 分析） │
│ ├── Agent B（专门处理技术方案） │
│ └── Agent C（专门处理代码开发） │
└─────────────────────────────────────────────────────────┘


**关键区别**：
- **CLAUDE.md**：配置"一个" Claude 实例的行为规范
- **AGENTS.md**：配置"多个" Agent 如何协作完成复杂任务

# 六、实践建议：如何选择和搭配

## 场景 1：纯 Claude Code 项目（无 OMO）

项目根目录/
├── CLAUDE.md # 项目级指令
└── .claude/
└── rules/ # 场景化规则
├── review.md
├── test.md
└── doc.md

1
2
3


## 场景 2：OhMyOpenCode 项目（推荐）

项目根目录/
├── AGENTS.md # 多 Agent 编排配置
├── CLAUDE.md # （可选）补充单 Agent 规范
├── .claude/
│ └── rules/ # 场景化规则
└── .specs/ # SDD 规范目录
├── prd/
├── user-behavior/
└── system-behavior/


## 场景 3：混合使用

当同时使用 OMO 和 Claude Code 时：
- **AGENTS.md**：定义项目结构、模块协作、服务接口
- **CLAUDE.md**：补充编码规范、行为准则（如果 AGENTS.md 未覆盖）
- **rules/**：特定场景的精细化规则

# 七、总结

理解这三者的区别，关键在于抓住它们解决的不同层面的问题：

┌────────────────────────────────────────┐
│ AGENTS.md → “协作层面” │
│ 解决：谁来做？模块间如何协作？ │
├────────────────────────────────────────┤
│ CLAUDE.md → “个体层面” │
│ 解决：单个 Agent 应该遵循什么规范？ │
├────────────────────────────────────────┤
│ rules/ → “场景层面” │
│ 解决：特定场景下如何行为？ │
└────────────────────────────────────────┘


**一句话记忆**：
- **AGENTS.md** = 告诉**多个** Agent "谁写哪部分、怎么对接"
- **CLAUDE.md** = 告诉**一个** Claude "你该怎么写代码"
- **rules/** = 告诉 Agent "遇到这种情况，执行那个规则"

在 SDD 的实践中，这三者不是互斥的，而是互补的。AGENTS.md 提供宏观的协作框架，CLAUDE.md 提供微观的个体规范，rules/ 提供灵活的场景应对。理解它们的边界，才能构建高效的 AI 协作体系。

---

**参考阅读**：
- [SDD 与超级个体：AI 时代的人机协作范式](/2026/03/12/SDD与超级个体-AI时代的人机协作范式/)
- [OhMyOpenCode 官方文档](https://github.com/opensoft/oh-my-opencode)
- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)