在实践 SDD（语义驱动开发）的过程中，一个常见的困惑是：AGENTS.md、CLAUDE.md、rules/ 目录以及 openspec/ 目录中的各类 md 文件，各自承担什么职责？边界在哪里？ 这些配置文件均为 AI 服务的项目级配置，但解决的问题截然不同。本文将系统性地梳理这些 md 文件的作用与边界，帮助读者构建清晰的 AI 项目配置体系。

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

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

在使用 AI 编程工具时，我们经常遇到以下问题：

“AGENTS.md 与 Claude Code 的 CLAUDE.md 有何区别？”
“项目级的 rules/ 目录承担什么职责？”
“openspec/ 目录下的 project.md、proposal.md、tasks.md 分别是什么？”
“这些文件是互斥关系还是互补关系？”

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

二、核心配置文件一览

首先，让我们用一个全景图来展示所有关键的 md 文件：

your-project/
├── AGENTS.md                        # AI 行为规则（openspec init 自动生成，不要手改）
├── CLAUDE.md                        # 单 Agent 行为规范（Claude Code 专用）
├── .claude/
│   └── rules/                       # 场景化规则片段
│       ├── review.md                # 代码审查场景
│       ├── test.md                  # 测试生成场景
│       └── doc.md                   # 文档生成场景
└── openspec/                        # SDD 语义驱动开发目录
    ├── project.md                   # 项目知识库（需要人工填充，是 proposal 质量的天花板）
    ├── specs/                       # 当前事实：已归档的规范集合
    │   └── <capability-name>/
    │       ├── spec.md              # 能力规范（SHALL/MUST 语义约束）
    │       └── design.md            # 设计说明（可选）
    └── changes/                     # 变更提案（每个需求一个子目录）
        ├── <change-id>/
        │   ├── proposal.md          # 为什么改、改什么、验收标准
        │   ├── tasks.md             # 实现任务清单（后端/前端/测试分项）
        │   └── specs/               # Delta：仅包含本次变更的规范片段
        └── archive/                 # 已完成的变更历史（archive 后自动移入）

三、三大基础配置：AGENTS.md、CLAUDE.md 与 rules/

用下表概括三者的关系：

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

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

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

AGENTS.md = 项目地图 + 协作协议
    ├── 项目结构定义（目录结构）
    ├── 功能定位表（快速定位）
    └── 协作关系定义（服务清单、接口契约）

典型内容：

项目概述与技术栈
目录结构与模块划分
常用命令（构建、测试、运行）
编码规范与命名约定
服务接口清单（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 引用

四、openspec 目录：语义驱动开发的核心

OpenSpec 是一套语义驱动开发（SDD）的规范体系，通过结构化的 md 文件来管理项目知识、能力规范和变更提案。

1. project.md：项目知识库

定位：项目的语义知识库
核心职责：存储项目的人工维护知识，是 AI 生成 proposal 的上下文基础

project.md = 项目知识库
    ├── 业务领域知识
    ├── 技术架构决策
    ├── 历史演进记录
    └── 隐性知识沉淀

关键特征：

需要人工填充，无法自动生成
是 proposal 质量的"天花板"
越详细，AI 生成的提案越精准

2. specs/：能力规范集合

定位：已归档的能力规范集合
核心职责：定义系统的"当前事实"

specs/
└── <capability-name>/
    ├── spec.md              # 能力规范（SHALL/MUST 语义约束）
    └── design.md            # 设计说明（可选）

典型内容：

spec.md：使用 SHALL/MUST 等语义约束定义能力边界
design.md：补充设计说明、架构图、决策记录

关键特征：

代表系统"当前是什么"
使用语义化约束语言
支持模块化管理

3. changes/：变更提案目录

定位：变更提案的存储目录
核心职责：管理从需求到实现的变更流程

changes/
├── <change-id>/
│   ├── proposal.md          # 为什么改、改什么、验收标准
│   ├── tasks.md             # 实现任务清单（后端/前端/测试分项）
│   └── specs/               # Delta：仅包含本次变更的规范片段
└── archive/                 # 已完成的变更历史

关键文件：

文件	作用	时态
proposal.md	定义"为什么改、改什么、验收标准"	对齐态
tasks.md	定义"具体怎么做、分几步完成"	迭代态
specs/	本次变更涉及的规范片段（Delta）	增量态

关键特征：

每个需求一个独立子目录
支持变更历史追溯（archive）
与 specs/ 目录形成"增量 + 基线"的关系

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

维度	AGENTS.md	CLAUDE.md	rules/	openspec/
核心问题	“谁来做？怎么协作？”	“我是谁？遵循什么规范？”	“遇到 X，执行 Y”	“系统是什么？要变成什么？”
定位	多 Agent 编排配置	单 Agent 项目指令	场景化规则片段	语义驱动规范体系
内容侧重	项目结构、模块协作	编码规范、行为准则	特定场景指导	知识库、规范、变更提案
目标读者	多个协作的 Agent	单个 Claude 实例	按需加载的规则引擎	AI + 人类协作
生成方式	`/init` 自动生成	手动创建	手动创建	`openspec init` 自动生成骨架
维护方式	自动更新	手动维护	手动维护	proposal 驱动增量更新

六、实际案例：一个 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"指的是：

> **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/ # 场景化规则
└── openspec/ # SDD 规范目录
├── project.md
├── specs/
└── changes/

1
2
3


## 场景 3：完整 SDD 项目（最佳实践）

项目根目录/
├── AGENTS.md # 多 Agent 编排配置
├── CLAUDE.md # 单 Agent 行为规范
├── .claude/
│ └── rules/ # 场景化规则
│ ├── review.md
│ ├── test.md
│ └── doc.md
└── openspec/ # SDD 规范目录
├── project.md # 项目知识库
├── specs/ # 能力规范集合
│ └── /
│ ├── spec.md
│ └── design.md
└── changes/ # 变更提案目录
├── /
│ ├── proposal.md
│ ├── tasks.md
│ └── specs/
└── archive/


**分工说明**：
- **AGENTS.md**：定义项目结构、模块协作、服务接口——使多个 Agent 明确职责划分
- **CLAUDE.md**：补充编码规范、行为准则——使单个 Claude 实例明确编码风格
- **rules/**：特定场景的精细化规则——按需加载，覆盖未涉及的细节
- **openspec/**：语义驱动的规范体系——管理知识、规范和变更

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

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

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

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

这个分类的工程含义：

**存量载体**的核心要求是**准确**。`AGENTS.md` 里的目录结构、`specs/spec.md` 里的能力定义，必须与代码库的实际状态保持同步。一旦存量信息过时，后续所有基于它生成的 proposal 和 tasks 都会偏离现实。这是 GIGO（Garbage In, Garbage Out）在 AI 工程中最隐蔽的表现形式。

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

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

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

# 十、总结

理解这些 md 文件的区别，关键在于明确它们解决的不同层面的问题：

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


**核心定位**：
- **AGENTS.md**：定义**多个** Agent 的职责划分与协作方式
- **CLAUDE.md**：定义**单个** Claude 实例的编码规范与行为准则
- **rules/**：定义特定场景的精细化行为指导
- **openspec/**：定义语义驱动的规范体系（知识库、能力规范、变更提案）

在 SDD 的实践中，这些配置文件不是互斥的，而是互补的。AGENTS.md 提供宏观的协作框架，CLAUDE.md 提供微观的个体规范，rules/ 提供灵活的场景应对，openspec/ 提供语义驱动的规范管理。理解它们的边界，才能构建高效的 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)