AGENTS.md vs CLAUDE.md: How to Keep AI Coding Agent Rules in Sync?

The Problem: Every AI Agent Speaks a Different Language

Your team uses Claude Code. Your co-founder prefers Cursor. The new hire swears by Codex CLI. And someone just discovered Gemini CLI.

Each tool has its own instruction file format. Without coordination, every developer's AI assistant follows different rules — leading to inconsistent code style, broken patterns, and wasted time fixing what the AI got wrong.

ProductReady solves this with a unified rule sync strategy. This post explains how it works and how you can adopt it.

The Compatibility Matrix

Not all AI coding tools read the same files. Here's the full landscape as of early 2026:

CLI Tools

IDE & Editors

IDE Extensions

Autonomous Agents

Key takeaway: AGENTS.md has the widest reach — natively supported by 10+ tools. But Claude Code only reads CLAUDE.md, Gemini CLI only reads GEMINI.md, and Kiro only reads .kiro/steering/. You need all of them.

ProductReady's Sync Strategy

We maintain 6 rule files with identical content (except the title line):

.kiro/steering/main.md          → Kiro (source of truth)
.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...

The Source of Truth

.kiro/steering/main.md is our canonical file. All others are derived from it. The only difference between files is the first two lines:

# Claude Code Instructions                          ← title varies
This file provides guidance to Claude Code when...  ← description varies

## 🚨 BEFORE YOU SAY "DONE" - MANDATORY CHECKLIST   ← identical from here
...                                                  ← identical content

How We Sync

When any rule changes, we regenerate all files from the source:

# Kiro is source of truth (skip 4-line YAML frontmatter)
SOURCE=".kiro/steering/main.md"

# Regenerate each file with its own title
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

tail -n +5 $SOURCE | sed '1s/.*/# GitHub Copilot Instructions/' \
  | sed '3s/.*/This file provides guidance to GitHub Copilot when working with code in this repository./' \
  > .github/copilot-instructions.md

# ... repeat for cursor, gemini, AGENTS.md

Verification

# Diff all files against source (excluding title lines)
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

Expected output: 0 differing lines for all files.

What Goes in the Rules File

Our shared rules cover everything an AI agent needs to work correctly in the monorepo:

1. Mandatory checklist — changelog, typecheck, KUI protection, no manual migrations
2. Architecture — monorepo structure, DDD domain pattern, app structure
3. VO/DTO/PO pattern — never expose database entities to frontend
4. Design system — CSS variables hierarchy, no hardcoded values
5. Essential commands — dev, build, test, lint, database setup
6. Quality standards — 6 required spec files, scoring system
7. Package management — pnpm workspace commands, troubleshooting

The full file is ~750 lines. Every AI agent that reads it will follow the same conventions.

How to Adopt This in Your Project

Step 1: Create your source of truth

Pick one file as canonical. We recommend .kiro/steering/main.md or AGENTS.md.

Step 2: Generate the others

# From AGENTS.md as source
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

# Update titles in each file
sed -i '1s/.*/# Claude Code Instructions/' .claude/CLAUDE.md
# ... etc

Step 3: Commit all files

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"

Step 4: Keep them in sync

When you need to update rules, just tell your AI agent:

"Update the shared rules to include [your change], then sync all AI agent rule files using the sync-ai-agent-rules skill."

Or copy this article's sync strategy to any AI coding agent and ask it to execute.

FAQ

Q: Why not just use AGENTS.md for everything? Because Claude Code ignores it. Gemini CLI ignores it. Kiro ignores it. Each tool has its own native file, and some don't fall back to AGENTS.md. You need the native files for full coverage.

Q: Won't this create merge conflicts? Rarely. Rules change infrequently (maybe once a week). And since all files have identical content, conflicts are easy to resolve — just re-sync from source.

Q: What about tool-specific features like Claude skills or Cursor commands? Keep those in their native locations (.claude/skills/, .cursor/commands/). Only the shared rules need syncing. Tool-specific extensions stay tool-specific.

Q: How do I update all files at once? Give any AI coding agent this instruction:

"Read .kiro/steering/main.md (or AGENTS.md), apply [your change], then propagate the same change to all other AI agent rule files: .claude/CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/main.md, .gemini/GEMINI.md, and AGENTS.md. Verify 0 diff lines excluding titles."

That's it. One prompt, all files updated.

This post reflects the AI coding tool landscape as of February 2026. The compatibility matrix was verified on Feb 14, 2026 by cross-referencing official documentation from each tool vendor (Windsurf docs, Codex AGENTS.md guide, OpenCode rules, Gemini CLI config, Claude Code issue #6235). Tool support for AGENTS.md is evolving rapidly — check your tool's documentation for the latest.