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

这三者并非递进的"高低层次"，而是三个不同维度的配置：从宏观的多 Agent 协作框架（AGENTS.md），到单个 Agent 的个体行为规范（CLAUDE.md），再到细粒度的场景应对规则（rules/）。理解它们各自解决的问题，是正确使用 SDD 工具链的前提。

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

最近在使用 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 编排的"总指挥"

定位：多 Agent 系统的项目级配置文件（通用规范，最早由 OpenAI Codex CLI 引入，现已被 OhMyOpenCode 等多个工具采用；OMO 的 /init 命令遵循此规范自动生成该文件）
核心职责：定义"谁来做"和"怎么协作"

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

典型内容：

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

关键特征：

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

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

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

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

典型内容：

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

关键特征：

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

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

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

1
2
3
4
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 行/文件）

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 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/ 
1
2
3
4
5
6
7
8
9
10
11
12

这个 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（专门处理代码开发） │
└─────────────────────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9

**关键区别**：
- **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/

1
2
3
4
5

## 场景 3：混合使用

当同时使用 OMO 和 Claude Code 时，三者各司其职、互补协作：

项目根目录/
├── AGENTS.md # 多 Agent 编排配置（项目结构、模块协作、服务接口）
├── CLAUDE.md # 单 Agent 行为规范（编码规范、行为准则）
├── .claude/
│ └── rules/ # 场景化规则（代码审查、测试生成等精细化规则）
│ ├── review.md
│ ├── test.md
│ └── doc.md
└── .specs/ # SDD 规范目录
├── prd/
├── user-behavior/
└── system-behavior/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

**分工说明**：
- **AGENTS.md**：定义项目结构、模块协作、服务接口——让多个 Agent 知道"谁负责哪块"
- **CLAUDE.md**：补充编码规范、行为准则——让单个 Claude 实例知道"怎么写代码"
- **rules/**：特定场景的精细化规则——按需加载，覆盖 AGENTS.md 和 CLAUDE.md 未涉及的细节

# 七、延伸思考：载体的时态属性

理解了三种配置文件的边界之后，还有一个更底层的问题值得追问：**这些载体，以及更广泛意义上的 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 工程中常见的配置混乱来源。

# 八、总结

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

┌────────────────────────────────────────┐
│ 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)