AI 编程工具的普及带来了一个新问题：项目里到处都是 .md 文件。AGENTS.md、CLAUDE.md、rules/、openspec/……它们各自解决什么问题？边界在哪里？什么时候该用哪一个？

这篇文章的核心洞察是：这些配置文件可以用"核心问题"和"时态属性"两个维度来区分——前者决定它们解决什么层面的问题，后者决定它们适合承载什么类型的信息。

理解这两个维度，就能在配置文件的迷宫中找到方向。

一、背景：为什么需要这么多配置文件？

传统软件项目只需要一个 README.md——它是给人读的。但在 AI 编程时代，项目需要同时面向两类读者：人类和 AI Agent。

人类需要的是高层次的概览（“这个项目是做什么的？”），而 AI Agent 需要的是结构化的、可执行的上下文（“代码在哪里？怎么跑起来？有哪些约束？”）。这两类需求差异巨大，单一文件难以同时满足。

于是，项目配置文件开始分化。每一类配置文件都针对特定的问题域，服务于特定的 AI 工具或工作流。理解它们，就是理解 AI 编程工具的协作边界。

二、目录结构：一个典型 AI 项目的配置全景

一个完整的 AI 辅助项目，其配置文件通常呈现如下结构：

项目根目录/
├── AGENTS.md          # 多 Agent 编排配置（通用规范）
├── CLAUDE.md          # Claude Code 项目级指令（L2 配置）
├── .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）、Claude Code、Cursor 等多个工具采用）
核心职责：定义"谁来做"和"怎么协作"

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

典型内容：

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

关键特征：

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

2. CLAUDE.md：分层提示机制的 L2 项目配置

定位：Claude Code 的项目级指令文件，属于分层提示机制的第二层（L2）
核心职责：在 System Prompt（L1）和用户输入（L3）之间，提供项目级的上下文和行为约束

分层提示机制（Three-Layer Prompting）
├── L1: System Prompt    → 行为宪法（全局约束，由 Anthropic 预设）
├── L2: CLAUDE.md        → 项目配置（项目级上下文、编码规范、工具权限）
└── L3: 用户输入          → 任务指令（具体需求、即时指令）

典型内容：

项目上下文（技术栈、架构决策、关键依赖）
编码规范（缩进、命名、注释语言）
行为准则（错误处理策略、用户交互时机）
工具使用规范（构建工具、测试框架）
项目特定的最佳实践

关键特征：

位于分层配置体系的中间层
与 System Prompt 协同工作，而非独立存在
为 Agent Loop 提供项目级的持久上下文
与 Claude Code 深度绑定

与 AGENTS.md 的本质区别：

AGENTS.md 解决"多 Agent 协作"问题——定义多个 Agent 的职责划分与协作方式
CLAUDE.md 解决"单次 Agent Loop 的上下文"问题——为 Claude Code CLI 进程提供项目级配置

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

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

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

典型内容：

每个规则文件遵循"触发条件 → 执行动作"的模式。以代码审查规则为例：

# review.md

## 触发条件
- 用户请求代码审查
- PR 创建或更新时

## 审查维度
1. **代码质量**：命名规范、复杂度、重复代码
2. **安全性**：SQL 注入、XSS、敏感信息泄露
3. **性能**：N+1 查询、大循环、内存泄漏风险
4. **可维护性**：注释完整性、测试覆盖率

## 输出格式
- 问题列表（按严重程度排序）
- 修复建议（附代码示例）
- 总体评分（A/B/C/D）

关键特征：

按需匹配：根据当前任务类型自动加载对应规则
细粒度：每个规则文件聚焦单一场景
可组合：多个规则可同时生效
优先级机制：当规则冲突时，按优先级执行

与 AGENTS.md / CLAUDE.md 的关系：

AGENTS.md 和 CLAUDE.md 提供项目级的全局约束
rules/ 提供场景级的精细化补充
规则文件可被 AGENTS.md 或 CLAUDE.md 引用，形成"全局 + 局部"的配置体系

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

OpenSpec 是一套语义驱动开发（SDD）的规范体系，通过结构化的 md 文件来管理项目知识、能力规范和变更提案。它包含三个核心组成部分：project.md 作为项目知识库，存储业务领域知识、技术架构决策等人工维护的知识；specs/ 目录用于管理已归档的能力规范集合，使用 SHALL/MUST 等语义约束定义系统能力边界；changes/ 目录则负责管理从需求到实现的变更流程，每个需求都有独立的 proposal.md、tasks.md 和 specs/ 子目录。

OpenSpec 的核心价值在于通过结构化的文档体系，将项目知识、规范定义和变更流程有机地整合在一起，形成"增量 + 基线"的关系。这种设计使得 AI 能够基于准确的项目上下文生成高质量的提案，同时支持变更历史的追溯和模块化的规范管理。由于 OpenSpec 的内容较为丰富和复杂，已将其详细内容独立成文，你可以参考 OpenSpec 实战教程：从入门到精通获取更全面的介绍和实践指导。

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

维度	AGENTS.md	CLAUDE.md	rules/	openspec/
核心问题	“谁来做？怎么协作？”	“项目级上下文是什么？”	“遇到 X，执行 Y”	“系统是什么？要变成什么？”
定位	多 Agent 编排配置	分层提示机制的 L2 项目配置	场景化规则片段	语义驱动规范体系
内容侧重	项目结构、模块协作	项目上下文、编码规范、工具权限	特定场景指导	知识库、规范、变更提案
目标读者	多个协作的 Agent	Claude Code CLI 进程（Agent Loop）	按需加载的规则引擎	AI + 人类协作
生成方式	`/init` 自动生成	手动创建	手动创建	`openspec init` 自动生成骨架
维护方式	自动更新	手动维护	手动维护	proposal 驱动增量更新

六、时态属性：理解配置文件的深层框架

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

七、实际案例：一个 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. **上下文保存**：中间件配置、依赖版本等信息一目了然

# 八、AGENTS.md 与 SDD 知识库的区别

一个常见的误解是：`/init` 或 `/init-deep` 生成的 `AGENTS.md` 就是 SDD（Spec-Driven Development）知识库。**它们是两个不同的概念**。

| 维度 | AGENTS.md | SDD 知识库 |
|------|-----------|-----------|
| **定位** | 项目说明书 | 开发操作系统 |
| **内容范围** | 项目结构、技术栈、规范 | 项目上下文 + 规范 + 变更 + 决策 |
| **变更追踪** | 无（需手动更新） | 有（`changes/` 目录） |
| **适用场景** | 快速上手新项目 | 长期维护的企业级项目 |

**关键洞察**：两者可以共存——用 `AGENTS.md` 提供快速上下文，用 SDD 知识库驱动规范化的开发流程。

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

## 场景 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 # L2 项目配置（项目级上下文）
├── .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**：作为分层提示机制的 L2，提供项目级上下文和编码规范——为 Agent Loop 提供持久上下文
- **rules/**：特定场景的精细化规则——按需加载，覆盖未涉及的细节
- **openspec/**：语义驱动的规范体系——管理知识、规范和变更

# 十、总结

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

```mermaid
flowchart TB
    subgraph 协作层
        A["AGENTS.md<br/>谁来做？怎么协作？"]
    end
    
    subgraph 上下文层
        B["CLAUDE.md<br/>项目级上下文是什么？"]
    end
    
    subgraph 场景层
        C["rules/<br/>遇到 X，执行 Y"]
    end
    
    subgraph 语义层
        D["openspec/<br/>系统是什么？要变成什么？"]
    end
    
    A --> B --> C --> D