AGENTS.md标准化文档：兼容Claude/Cursor/Codex全方案评测

2026-06-19阅读 0热度 0

Claude

AGENTS.md 正是为解决多工具配置碎片化而生的统一 Markdown 规范文件，专门面向各类 AI Coding Agent，相当于为 AI 量身定制的项目导航 README。2025 年由开源社区推动标准化，Linux Foundation 下属 Agentic AI Foundation 托管，截至 2026 年已有超过 6 万个开源项目采用，兼容 Codex、Cursor、Qoder、灵码、Gemini CLI 等主流 AI 编程工具。仅需一份文件即可统一项目全部开发规则，配合软链接可无缝兼容 Claude Code。

本文以 Spring Boot React 全栈管控系统为落地案例，完整拆解 AGENTS.md 的诞生背景、核心设计思路、分模块编写规范、monorepo 仓库改造方案、自动化检测脚本以及端到端验证闭环。附带可直接复用的配置文件、Shell 校验代码，全程无外部链接、表格、图片，覆盖从空白项目搭建到 AI 自主执行的全流程实践。

二、AGENTS.md 诞生背景与统一标准演进

2.1 早期多工具配置碎片化痛点

在统一标准落地前，各类 AI 编程工具各自推出专属规则文件，格式、存放路径互不兼容，形成了严重碎片化的维护困局：

Claude Code：CLAUDE.md，独立语法，支持导入子规则
Cursor：.cursorrules 隐藏目录配置
GitHub Copilot：.github/copilot-instructions.md
Gemini CLI：GEMINI.md
Sourcegraph AMP：单数 AGENT.md
OpenAI Codex：复数 AGENTS.md

团队同时使用多款 AI 工具时，修改一条编码规则需要同步更新 6 份配置，极易出现内容不一致。AI 获取项目信息存在偏差，生成代码质量自然参差不齐。

2.2 统一标准成型过程

2025 年 5 月，Sourcegraph AMP 率先提出单数 AGENT.md 通用标准。随后 OpenAI 推出复数 AGENTS.md 方案，主张多智能体共用一份配置文件。双方协商对齐规范，统一采用 AGENTS.md 作为通用文件名，底层标准由 Agentic AI 基金会托管，最终形成行业公认的事实标准。针对 Claude Code 不原生识别 AGENTS.md 的问题，仅需一条软链接命令即可双向兼容：

ln -s AGENTS.md CLAUDE.md

执行后，Claude 可直接读取同一份项目规则，无需重复编写两份文档，从根源上解决了多工具同步维护的难题。

2.3 AGENTS.md 核心设计理念：地图而非手册

标准的核心设计原则是「渐进式披露」，拒绝上万行巨型文档。AGENTS.md 仅作为项目导航地图，控制在 200 行以内，只存放 AI 理解项目必备的全局硬性规则；架构详情、组件用法、开发流程等长篇内容，统一拆分至 docs 目录下的独立 Markdown 文档，AGENTS.md 仅提供文档索引跳转指引。

信息存放的判定标准非常明确：如果 AI 缺失该信息会直接生成错误代码，就写入 AGENTS.md；仅影响代码美观度、优化细节的内容，放置到 docs 专题文档，避免关键规则被冗余信息淹没。

三、无 AGENTS.md 时五大核心开发痛点

以 Spring Boot React 全栈管控系统为例，未配置 AGENTS.md 的情况下，AI 编程存在五类高频阻碍，这也是落地该文档的核心驱动力。

3.1 前后端上下文割裂

早期项目后端、前端、组件库分三个独立 Git 仓库，AI 单次只能打开单一仓库。开发前后联动接口时，需要反复切换窗口、重复描述业务背景，导致上下文丢失，大量时间消耗在重复沟通上。

3.2 私有组件库无法识别

项目自研的 ProTable、ProForm 等闭源前端组件，公开训练数据中无相关信息。AI 只能调用原生 HTML、Antd 组件来替代，写出的代码不符合内部统一开发规范，每次都需要人工重写组件调用逻辑。

3.3 编码规范无统一约束

分层架构、异常抛出规则、响应体封装标准仅存在于团队口头约定中。AI 随机混用 RuntimeException 与业务自定义 BusinessException，甚至直接跨层注入 Repository，产生大量违规代码，人工修复工作量巨大。

3.4 AI 无法自主构建自测

AI 完成代码修改后，不了解项目启动命令、数据库配置、接口验证方式，无法自动执行构建与接口测试。修改效果只能人工逐一校验，无法实现夜间无人自主迭代。

3.5 项目知识分散无统一入口

架构文档、启动脚本、接口示例散落在聊天记录、本地零散文件中，AI 无法自动检索。每次编码都需要开发者重复提供环境、架构等背景信息。

所有痛点的本质是项目知识存储在人类大脑中，而非 AI 可自动读取的标准化文件。AGENTS.md 的核心作用，就是把全部项目约束、流程、命令结构化沉淀下来，实现 AI 打开项目即可完整理解业务体系。

四、落地前置改造：monorepo 仓库统一方案

解决上下文割裂的基础改造分为两种方案，存量旧项目使用脚本聚合，新项目直接采用单体多仓架构。

4.1 存量项目脚本聚合方案

前后端仓库分离的存量工程，可以编写一键聚合脚本 setup-repos.sh，将前端、组件库克隆至后端主仓库子目录，配置 gitignore 不纳入版本管理，不影响原有 CI 流程：

#!/bin/bash
# setup-repos.sh 仓库聚合脚本
mkdir -p frontend
cd frontend
git clone 前端仓库地址 web-app
git clone 私有组件库地址 component-lib
cd ..
echo "frontend/" >> .gitignore

执行脚本即可一键整合多仓库代码，AI 在单一目录下同时读取前后端文件，完整联动接口与页面逻辑。

4.2 新项目标准 monorepo 目录结构

全新项目推荐直接采用单体多仓架构，目录分层清晰，AGENTS.md 可精准指引 AI 定位各模块源码。完整标准目录如下：

project-root/
├── AGENTS.md              # AI专属导航文档
├── README.md             # 人类阅读项目介绍
├── Makefile              # 统一质量检测、构建命令入口
├── server/               # Spring Boot后端源码
├── web/                 # React前端源码
├── user-guide/          # 产品使用手册
├── scripts/             # 启动、校验自动化脚本
├── docs/                # 详细专题文档
│   ├── architecture.md
│   └── design-docs/
└── reference-projects/  # 第三方/私有组件源码子模块
    ├── pro-components
    └── higress-gateway

reference-projects 目录通过 git submodule 引入私有组件、开源网关的完整源码，AI 需要查阅组件定义时可直接读取源码，无需依赖滞后文档。拉取子模块的基础命令：

# 首次拉取全部参考项目
git submodule update --init
# 仅拉取前端组件库
git submodule update --init reference-projects/pro-components

五、AGENTS.md 标准完整模板（可直接复用）

遵循 200 行以内精简原则，划分九大固定模块，覆盖项目概述、命令、架构、规范、验证、参考项目、文档索引全部核心内容。完整示例代码如下：

# AGENTS.md

## 1. 项目概述
本项目为企业资源管控全栈系统，后端采用 Spring Boot 3，前端基于 React TS，采用 monorepo 架构，实现资源审批、权限管控、数据统计全功能。仓库分为 server 后端、web 前端、参考组件三大模块，所有业务接口前后端统一交互规范。

## 2. 快速命令
# 后端一键构建启动（自动加载环境配置）
./scripts/start-server.sh
# 前端开发服务启动
./scripts/start-web.sh
# 分层架构依赖检测
make lint-arch
# 代码格式化修复
make format
# 单元测试执行
make test
# 环境配置文件路径 ~/.project_env，启动脚本自动加载

## 3. 后端架构
后端分层五层：Entity 层→Repository 层→Service 层→Controller 层→公共 Common 层，禁止跨逆向依赖，详情查看 docs/architecture.md

## 4. 前端架构
采用私有 Pro 系列组件，禁止直接使用原生表单表格，所有接口统一封装在 src/services，路由文件集中管理，组件采用 Pascal 命名，详情 docs/design-docs/frontend-architecture.md

## 5. 硬性编码约定
1. 异常统一抛出 BusinessException，禁止直接使用 RuntimeException
2. 接口响应由全局拦截器统一封装，禁止手动构造返回体
3. Controller 禁止直接注入 Repository，必须通过 Service 中转
4. 前端组件禁止行内样式，统一使用全局样式文件
5. 所有新增接口必须配套 curl 验证脚本，存放 scripts/curl-demo

## 6. 开发验证闭环
代码修改完成执行流程：构建→启动服务→curl 调用接口验证→查看返回数据，完整 curl 模板存放 scripts 目录，参考 docs/design-docs/api-verification.md

## 7. 质量检测命令
lint-arch：分层依赖违规检查
lint-format：代码格式校验
format：自动修复格式问题
build：打包编译
test：单元测试

## 8. 参考项目规则
私有组件查看 reference-projects/pro-components；网关逻辑查看 higress 子模块，优先读取对应 ref 文档 docs/design-docs/ref-*.md

## 9. 文档导航
全局架构：docs/architecture.md
接口规范：docs/design-docs/api-design.md
组件说明：docs/design-docs/ref-pro-components.md

编辑完成后，执行软链接即可兼容 Claude：

ln -s AGENTS.md CLAUDE.md

六、四大核心落地配套实践方案

6.1 统一环境启动脚本，实现 AI 自主运行

所有环境变量统一存放到用户根目录隐藏文件，避免提交至代码仓库，启动脚本自动加载。scripts/start-server.sh 完整代码：

#!/bin/bash
# 加载本地环境变量
source ~/.project_env
# 关闭残留旧进程
pkill -f java || true
# 执行打包构建
mvn package -DskipTests
# 后台启动服务
java -jar server/target/*.jar &
# 健康检测循环等待
for i in {1..30};do
  curl -s http://127.0.0.1:8080/health > /dev/null
  if [ $? -eq 0 ];then
    echo "服务启动完成"
    exit 0
  fi
  sleep 2
done
echo "服务启动超时"
exit 1

脚本支持 --quick 跳过构建、--skip-build 直接重启，AI 仅需调用单条命令即可完成整套启动流程。

6.2 标准化 curl 接口验证脚本，构建自测闭环

传统单行管道命令容易在 shell 环境报错，采用临时文件分段存储返回数据，可提升 AI 执行稳定性。scripts/api-verify.sh 示例：

#!/bin/bash
# 1.登录获取 token 写入临时文件
curl -s -X POST http://127.0.0.1:8080/auth/login \
  -H "Content-Type:application/json" \
  -d '{"username":"admin","password":"test123"}' > /tmp/login-res.json
# 2.提取凭证
TOKEN=$(python3 -c "import json;print(json.load(open('/tmp/login-res.json'))['data']['token'])")
# 3.调用业务接口
curl -s -X POST http://127.0.0.1:8080/resource/list \
  -H "Authorization: Bearer $TOKEN" > /tmp/api-data.json
# 4.输出结果摘要
cat /tmp/api-data.json | python3 -c "import json;print(json.load(open('/tmp/api-data'))['total'])"

AI 修改接口代码后，可直接执行该脚本自动校验返回结果，无需人工手动调用接口。

6.3 分层架构自动化检测 shell 脚本

搭建 lint-deps.sh 自动检测 Java 文件跨层依赖，违规时输出修复指引，绑定 make lint-arch 命令。AI 修改代码后一键自检：

#!/bin/bash
# 扫描所有 java 文件，检测非法跨层导入
find server/src -name "*.java" | while read file;do
  # 检测 Controller 直接导入 Repository
  if grep "import.*Repository" $file | grep -q Controller;then
    echo "违规文件:$file"
    echo "错误：Controller 禁止直接依赖 Repository，通过 Service 中转"
  fi
done

写入 Makefile 统一入口，简化 AI 记忆成本：

lint-arch:
	bash scripts/lint-deps.sh
format:
	mvn spotless:apply
build:
	mvn package -DskipTests
test:
	mvn test

6.4 参考子模块管理方案

将无官方文档的私有组件、开源中间件源码通过 git submodule 纳入仓库。AI 遇到不熟悉的组件逻辑时，可直接读取源码 TS/Java 定义，解决文档滞后问题。配套 ref 说明文档简要梳理模块整体结构，减少 AI 的探索成本。

七、迭代维护规范与团队协作规则

7.1 渐进式迭代思路

禁止一次性编写完整的 AGENTS.md。应采用问题驱动迭代：AI 生成代码出现违规问题，就新增一条对应约束写入文档，逐步完善，避免文档冗余膨胀。

7.2 文档分层分工规则

全局性、强制约束统一写入根目录 AGENTS.md；模块专属细节、业务流程拆分至 docs 专题文档；子目录差异化规则可创建嵌套 AGENTS.md，AI 会自动读取当前目录最近的一份配置文件。

7.3 区分阅读对象

README.md：面向人类开发者，记录项目介绍、本地快速上手步骤
AGENTS.md：以 AI 为核心阅读对象，存放执行命令、硬性编码规则
scripts/ 脚本：人与 AI 共用的自动化工具
docs 系列：人类与 AI 均可查阅的详细业务架构

八、落地完整收益总结

消除多工具维护成本：一份 AGENTS.md 兼容全部主流 AI 编程工具，软链接适配 Claude，无需同步多份规则
AI 代码质量大幅提升：标准化架构、组件、异常约束，减少人工修复工作量
实现 AI 自主全流程闭环：AI 可完成代码修改、构建、接口验证整套流程，支持夜间批量迭代
沉淀团队隐性知识：口头编码规范、业务架构转化为标准化可读文档，新人与 AI 均可快速熟悉项目
适配 monorepo 全栈项目，解决前后端上下文割裂痛点，实现全栈代码统一智能生成

九、总结

AGENTS.md 作为面向 AI Coding Agent 的行业通用标准化导航文档，核心价值在于把分散、隐性的项目规则转化为 AI 可自动读取、完整理解的结构化信息，解决多 AI 工具配置碎片化、AI 无法识别项目架构、代码生成返工率高等开发痛点。

落地整套方案分为仓库改造、AGENTS.md 文档编写、自动化脚本配套、参考子模块引入四大核心步骤，严格遵循「地图而非手册」的精简设计原则——全局硬性约束写入主文件，详细业务内容拆分至 docs 目录。搭配环境启动脚本、curl 验证工具、分层检测 shell 代码，构建起「AI 改代码 → 自动检测 → 自主验证」的完整开发闭环。

对于使用 Cursor、Claude、Codex 等多款 AI 工具的研发团队来说，AGENTS.md 是一个低成本、高收益的标准化方案。仅需少量前期配置，即可长期降低 AI 编程的沟通与代码修复成本，同时沉淀团队的完整项目知识库，兼顾 AI 开发效率与新人上手速度。