AGENTS.md vs CLAUDE.md：如何保持 AI 编程助手规则同步？
AGENTS.md vs CLAUDE.md vs GEMINI.md — 20+ AI 编程工具完整兼容性矩阵（Cursor、Copilot、Codex、Claude Code）。一套源文件同步所有 Agent 规则的实战指南。
← 返回博客问题：每个 AI Agent 说不同的"语言"
你用 Claude Code，合伙人用 Cursor，新同事用 Codex CLI，还有人刚发现了 Gemini CLI。
每个工具有自己的指令文件格式。如果不统一，每个开发者的 AI 助手遵循不同的规则——代码风格不一致、架构模式被破坏、花大量时间修复 AI 的错误。
ProductReady 用统一的规则同步策略解决了这个问题。 本文介绍它的工作原理以及如何采用。
兼容性矩阵
不是所有 AI 编程工具都读同一个文件。以下是 2026 年初的完整情况：
CLI 工具
| 工具 | AGENTS.md | CLAUDE.md | GEMINI.md | Cursor Rules | 原生配置 |
|---|---|---|---|---|---|
| Claude Code (Anthropic) | — | ✅ 原生 | — | — | CLAUDE.md |
| Codex CLI (OpenAI) | ✅ 原生 | 回退 | — | — | AGENTS.md |
| Gemini CLI (Google) | 可配置 | — | ✅ 原生 | — | GEMINI.md |
| OpenCode | ✅ 原生 | 回退 | — | — | AGENTS.md |
| Aider | 可配置 | — | — | — | .aider.conf.yml |
| Factory Droid | ✅ 原生 | ✅ 原生 | — | — | .factory/droids/*.md |
IDE 和编辑器
| 工具 | AGENTS.md | CLAUDE.md | GEMINI.md | Cursor Rules | 原生配置 |
|---|---|---|---|---|---|
| Cursor | ✅ 原生 | ✅ 原生 | — | ✅ 原生 | .cursor/rules/*.mdc |
| Windsurf (Codeium) | ✅ 原生 | — | — | 类似 | .windsurf/rules/*.md |
| Amp (Sourcegraph) | ✅ 原生 | 回退 | — | — | AGENTS.md |
| Zed Editor | via ACP | ✅ 原生 | ✅ 原生 | — | settings.json |
| JetBrains AI | — | — | — | — | .aiassistant/rules/*.md |
| Kiro (AWS) | — | — | — | — | .kiro/steering/*.md |
IDE 扩展
| 工具 | AGENTS.md | CLAUDE.md | GEMINI.md | Cursor Rules | 原生配置 |
|---|---|---|---|---|---|
| GitHub Copilot (Microsoft) | ✅ 原生 | 回退 | — | — | copilot-instructions.md |
| Augment Code | ✅ 原生 | ✅ 原生 | — | — | .augment/rules/*.md |
| Cline | ✅ 原生 | — | — | — | .clinerules/*.md |
| Roo Code | ✅ 原生 | — | — | — | .roo/rules/*.md |
| Amazon Q | — | — | — | — | .amazonq/rules/*.md |
自主 Agent
| 工具 | AGENTS.md | CLAUDE.md | GEMINI.md | Cursor Rules | 原生配置 |
|---|---|---|---|---|---|
| Jules (Google) | ✅ 原生 | — | — | — | AGENTS.md |
| Devin (Cognition) | 部分 | — | — | — | Dashboard |
关键结论： AGENTS.md 覆盖面最广——被 10+ 工具原生支持。但 Claude Code 只读 CLAUDE.md，Gemini CLI 只读 GEMINI.md，Kiro 只读 .kiro/steering/。你需要全部维护。
ProductReady 的同步策略
我们维护 6 个规则文件，内容完全一致（仅标题行不同）：
.kiro/steering/main.md → Kiro（信息源）
.claude/CLAUDE.md → Claude Code
.github/copilot-instructions.md → GitHub Copilot
.cursor/rules/main.md → Cursor
.gemini/GEMINI.md → Gemini CLI
AGENTS.md → Codex、OpenCode、Amp、Cline、Roo Code、Jules...信息源
.kiro/steering/main.md 是我们的规范文件。其他所有文件都从它派生。文件之间唯一的区别是前两行：
# Claude Code Instructions ← 标题不同
This file provides guidance to Claude Code when... ← 描述不同
## 🚨 BEFORE YOU SAY "DONE" - MANDATORY CHECKLIST ← 从这里开始完全一致
...同步方法
规则变更时，从源文件重新生成所有文件：
# Kiro 是信息源（跳过 4 行 YAML frontmatter）
SOURCE=".kiro/steering/main.md"
# 用各自的标题重新生成
tail -n +5 $SOURCE | sed '1s/.*/# Claude Code Instructions/' \
| sed '3s/.*/This file provides guidance to Claude Code when working with code in this repository./' \
> .claude/CLAUDE.md
# ... 对 cursor、gemini、AGENTS.md 重复验证
for f in .claude/CLAUDE.md .github/copilot-instructions.md \
.cursor/rules/main.md .gemini/GEMINI.md AGENTS.md; do
changes=$(diff <(tail -n +5 .kiro/steering/main.md | sed '1d;3d') \
<(cat "$f" | sed '1d;3d') | grep "^[<>]" | wc -l)
echo "$f: $changes differing lines"
done期望输出：所有文件 0 differing lines。
规则文件包含什么
我们的共享规则涵盖 AI Agent 在 monorepo 中正确工作所需的一切：
- 强制检查清单 — changelog、typecheck、KUI 保护、禁止手动迁移
- 架构 — monorepo 结构、DDD 领域模式、应用结构
- VO/DTO/PO 模式 — 永远不要将数据库实体暴露给前端
- 设计系统 — CSS 变量层级、禁止硬编码值
- 常用命令 — dev、build、test、lint、数据库设置
- 质量标准 — 6 个必需规格文件、评分系统
- 包管理 — pnpm workspace 命令、故障排除
完整文件约 750 行。每个读取它的 AI Agent 都会遵循相同的约定。
如何在你的项目中采用
第 1 步：创建信息源
选一个文件作为规范。推荐 .kiro/steering/main.md 或 AGENTS.md。
第 2 步：生成其他文件
cp AGENTS.md .claude/CLAUDE.md
cp AGENTS.md .github/copilot-instructions.md
cp AGENTS.md .cursor/rules/main.md
cp AGENTS.md .gemini/GEMINI.md
# 更新各文件的标题
sed -i '1s/.*/# Claude Code Instructions/' .claude/CLAUDE.md第 3 步：提交所有文件
git add AGENTS.md .claude/ .github/copilot-instructions.md \
.cursor/rules/ .gemini/ .kiro/steering/
git commit -m "chore: sync AI agent rules across all tools"第 4 步：保持同步
需要更新规则时，直接告诉你的 AI Agent：
"更新共享规则，加入 [你的改动]，然后同步所有 AI agent 规则文件。"
或者把这篇文章复制给任何 AI 编程助手，让它执行同步。
常见问题
Q：为什么不只用 AGENTS.md？
因为 Claude Code 不读它。Gemini CLI 不读它。Kiro 不读它。每个工具有自己的原生文件，有些不会回退到 AGENTS.md。你需要原生文件才能完全覆盖。
Q：会不会产生合并冲突？ 很少。规则变更不频繁（大约每周一次）。而且所有文件内容一致，冲突很容易解决——重新从源文件同步即可。
Q：工具专属功能怎么办？比如 Claude skills 或 Cursor commands？
保留在各自的原生位置（.claude/skills/、.cursor/commands/）。只有共享规则需要同步。工具专属扩展保持工具专属。
Q：如何一次更新所有文件？ 给任何 AI 编程助手这个指令：
"读取
.kiro/steering/main.md（或AGENTS.md），应用 [你的改动]，然后将相同的改动传播到所有其他 AI agent 规则文件：.claude/CLAUDE.md、.github/copilot-instructions.md、.cursor/rules/main.md、.gemini/GEMINI.md和AGENTS.md。验证排除标题后 0 行差异。"
就这样。一个 prompt，所有文件更新完毕。
本文反映 2026 年 2 月的 AI 编程工具生态。兼容性矩阵于 2026 年 2 月 14 日通过交叉验证各工具官方文档确认（Windsurf 文档、Codex AGENTS.md 指南、OpenCode 规则、Gemini CLI 配置、Claude Code issue #6235）。工具对 AGENTS.md 的支持正在快速演进——请查阅你所用工具的最新文档。