AGENTS.md 企业级项目管理

一份统一的入门文档，让任何 AI Agent 都能第一时间读懂你的项目——不限工具

🎯 什么是 AGENTS.md？

AGENTS.md 是一个正在兴起的跨工具约定：放在仓库根目录的一份 Markdown 文档，为任何 AI 编程 Agent（Claude Code、Codex、Cursor 等）提供新人入职第一天需要知道的信息——技术栈、构建/运行命令、架构、以及项目特有的约定。

和只服务于 Claude Code 的 CLAUDE.md 不同，AGENTS.md 是工具无关的。很多团队把 AGENTS.md 当作唯一真实来源，再用软链接或者一份精简的 CLAUDE.md（指向它）来兼容，这样同一份内容就能服务团队用到的所有 AI 工具。

💡 AGENTS.md vs. CLAUDE.md vs. skills/rules

• AGENTS.md —— 通用入门文档，任何 AI 工具都适用，内容高层且稳定
• CLAUDE.md —— Claude Code 的专属入口；完全可以只写"详见 AGENTS.md"再加一些 Claude 专属说明
• .claude/rules/ 与 .claude/skills/ —— AGENTS.md 刻意不重复的细节内容，按路径自动加载或按需触发（详见 .claude 配置层级 与 Claude Skills）

🧩 AGENTS.md 该写什么，不该写什么

一份边界清晰的 AGENTS.md 应该保持简短、结构化。细节化、重复性强的规范（命名风格、分层编码规则）应该放进 skills/rules——否则文件会越写越臃肿，最终没人会认真读完。

应该写进去	应该挪到 skills/rules
技术栈与版本	完整的语言风格指南
构建/运行/测试命令	每一种可能的测试场景
多服务项目的启动顺序	详细的 API 文档
高层架构与模块地图	各层（controller/service/mapper）的代码模板
项目特有的"坑点"约定（比如自定义响应包装类）	已经被某个技能覆盖的通用最佳实践

📖 示例结构（多模块后端项目）

# AGENTS.md

本文件是 Cloud Platform 项目的统一开发指南。

> 通用编码规范（命名、格式化、OOP、异常、日志、安全、数据库、单元测试）
> 由 skills 提供，见 `.claude/skills/`。
> 分层编码规则（controller、service、mapper、entity、dto）按文件路径
> 自动加载，见 `.claude/rules/`。

## 一、技术栈
- Java 17, Spring Boot 3.5.5, Spring Cloud 2025.0.0
- MyBatis Plus, Undertow, Druid
- pom.xml 为版本真实来源，本文档若与其不一致以 pom 为准

## 二、构建与运行
​```bash
mvn clean install -DskipTests
mvn test -pl 模块名 -Dtest=SomeTest
​```

## 三、启动顺序
1. registry-service（服务发现）[8848]
2. core-biz-service（等待路由初始化）[4000]
3. auth-service [3000]
4. gateway-service [9999]

## 四、架构概览
多模块 Spring Cloud 微服务平台，两种部署模式：
- `cloud`（默认）：完整微服务模式，含服务发现
- `boot`：单体模式，通过聚合模块合并启动

| 模块 | 职责 | 端口 |
|---|---|---|
| registry-service | 服务发现与配置中心 | 8848 |
| gateway-service | 统一入口 | 9999 |
| auth-service | OAuth2 授权服务器 | 3000 |

## 五、项目特有约定
- 仅使用构造函数注入（`@RequiredArgsConstructor`）；禁止 `@Autowired`
- 所有响应统一用 `R<T>` 包装：`R.ok(data)` / `R.failed(msg)`
- 枚举字段必须使用项目自定义的 `@EnumValue` 校验注解

## 六、代码示例
​```java
@RestController
@RequiredArgsConstructor
@RequestMapping("/example")
public class ExampleController {
    private final ExampleService exampleService;
}
​```

💡 保留"真实来源"的说明

注意例子里"pom.xml 为版本真实来源"这句话。文档会过时，构建文件不会骗人。明确写清楚"两者不一致时以谁为准"，能避免 AI（以及新人）依据过时信息行动。

🚀 为你的项目写 AGENTS.md

1. 先想清楚新人第一天需要什么——技术栈、怎么构建/运行、怎么跑单个测试、多服务项目的启动顺序
2. 加一张架构地图——模块表格，写清楚职责和端口/入口，而不是完整 API 文档
3. 列出 3~5 条最容易踩坑的约定——那些光看一遍代码不容易发现的（比如"禁止用 @Autowired"、"所有 DTO 的 @Size 必须跟数据库字段长度一致"）
4. 细节交给 skills/rules，不要全部塞进 AGENTS.md——保持它可以被快速浏览
5. 每个架构层给 1~2 个最简代码示例，这样 AI 匹配的是你项目的真实风格，而不是框架的通用默认写法
6. 保持同步——把 AGENTS.md 当代码对待，改构建命令或启动顺序时，在同一个 PR 里一并更新文档

⚠️ 常见误区：AGENTS.md 变成垃圾场

很多团队一开始很克制，但随着时间推移不断往里塞细节，最终文件长达几千行，人和 AI 都不会再逐字认真读。如果某段内容只适用于一种文件类型或一种场景，几乎总是应该放进 .claude/rules/（按路径加载）或 .claude/skills/（按需加载）。

🎉 效果

写得好的 AGENTS.md 意味着任何同事——或者任何 AI 工具——克隆仓库之后都能立刻上手：他们知道技术栈、怎么构建、服务怎么启动，以及那几条否则要靠 code review 才能发现的约定。