agents-md协议配置工作流多工具

AGENTS.md 协议：让多个 AI 工具读同一份配置

发布 2026-08-02更新 2026-08-02核实 2026-08-02

一句话结论

AGENTS.md 是社区里「一份项目配置，所有 AI 编程工具都读」的共识尝试。它本质上是 CLAUDE.md 的开放超集——目前 Cursor / Claude Code / Cline / Codex CLI 都能识别根目录的 AGENTS.md 并自动加载。写一份放项目根，就能统一所有工具的上下文，避免「Cursor 一份规则、Claude Code 一份规则」的分裂。

提出背景与社区现状

2025 年起，团队同时用 2-3 个 AI 工具成常态：Cursor 写细节、Claude Code 跑长任务、Cline 接国产模型、Codex 在 CI 里跑。但每个工具读自己格式的配置文件：

Cursor → .cursor/rules/*.mdc
Claude Code → CLAUDE.md
Cline → 自己的 memory 文件
Codex → AGENTS.md / codex.md

结果：同一份「项目约定」要维护 3-4 份，改一处忘三处，AI 行为不一致。

AGENTS.md 的初衷就是「单一事实源」——一个标准文件，谁都能读。它最早在 Codex / 开源社区成型，随后被 Cline、Claude Code（通过 CLAUDE.md 兼容读取）、Cursor（rules 可引用）陆续接纳。

AIHO 观点：AGENTS.md 目前是「事实标准」而非「官方标准」——没有 RFC，靠工具自发兼容。但因为它向下兼容 CLAUDE.md 的写法，迁移成本几乎为零，值得采用。

标准格式与字段约定

AGENTS.md 没有强制 schema，社区约定俗成的结构：

# 项目名

一句话描述项目是什么、用什么技术栈。

## 技术栈
- 前端：Nuxt 3 + Tailwind
- 后端：Nitro server routes
- 数据库：PostgreSQL（Prisma）

## 目录结构
- pages/        页面
- components/   Vue 组件
- server/       API 路由
- prisma/       schema 与迁移

## 开发命令
- pnpm dev      开发服务器
- pnpm test     测试
- pnpm lint     lint

## 编码约定
- TypeScript strict
- 组件用 <script setup>
- 提交前必须 lint + test 通过

## 禁忌
- 不要改 migrations/ 历史文件
- 不要在前端暴露密钥
- 不要引入未声明的依赖

关键点：用 Markdown 标题分层 + 列表化，不要写大段散文。工具和人类都能读。

桥接方案：让四个工具都读它

工具	怎么读 AGENTS.md	额外动作
Claude Code	自动读根目录 `CLAUDE.md`；把 AGENTS.md 内容同步进 CLAUDE.md 或软链	`ln CLAUDE.md AGENTS.md` 或内容一致
Cursor	`.cursor/rules/base.mdc` 写「遵循根目录 AGENTS.md」	或把 AGENTS.md 内容复制进 base.mdc
Cline	原生支持 `AGENTS.md` / 项目 memory	直接放根目录即可
Codex CLI	原生读 `AGENTS.md` / `codex.md`	直接放根目录即可

最省事的实践：维护一份 AGENTS.md 作为单一事实源，然后：

Claude Code：cp AGENTS.md CLAUDE.md（或用 symlink）
Cursor：在 base.mdc 里 @import / 引用 AGENTS.md 内容

这样改约定只改 AGENTS.md，其他文件重新同步即可。

3 套现成模板

模板 1：全栈 Web 项目

# Acme Web

Nuxt 3 全栈博客，前端 Vue + Tailwind，后端 Nitro。

## 技术栈
- Nuxt 3 / Vue 3 / TypeScript strict
- PostgreSQL + Prisma
- pnpm 包管理

## 命令
- pnpm dev / pnpm test / pnpm lint / pnpm build

## 约定
- 组件 <script setup>，禁止 Options API
- API 走 server/，前端不碰 secret
- 提交前 lint + test 必须通过

## 禁忌
- 不禁用 SSR
- 不改 prisma/migrations 历史

模板 2：Python 后端 / 数据

# Data Pipeline

FastAPI 数据处理服务，Python 3.12 + uv。

## 技术栈
- FastAPI / Pydantic v2
- PostgreSQL（asyncpg）
- ruff + black

## 命令
- uv run dev / uv run test / uv run lint

## 约定
- 全类型标注 + docstring
- 用 logging 不用 print
- async/await，不阻塞事件循环

## 禁忌
- 不裸 except
- 不硬编码配置（走 env）

模板 3：多工具协作的 monorepo

# Monorepo

pnpm workspace，含 core / cli / web 三个 package。

## 结构
- packages/core      共享逻辑（TS）
- packages/cli      命令行（Node）
- apps/web          Next.js 前端

## 命令
- pnpm -r test      全量测试
- pnpm --filter web dev

## 约定
- 跨 package 改动需同时更新依赖方类型
- 统一用 changesets 管理版本

## 禁忌
- 不要跨 package 循环依赖
- 不要提交未通过 ci 的代码

常见疑问

Q：AGENTS.md 和 CLAUDE.md 冲突谁优先？ A：看工具。Claude Code 读 CLAUDE.md，若 CLAUDE.md 是 AGENTS.md 的副本则一致；建议让 AGENTS.md 为源，CLAUDE.md 同步它。

Q：旧的 .cursorrules 要留吗？ A：新版 Cursor 用 .cursor/rules/*.mdc，旧 .cursorrules 仍可兼容但建议迁移。

Q：一个项目能同时有 AGENTS.md 和 CLAUDE.md 吗？ A：能，只要内容保持同步。最省事是 symlink 或 cp。