AGENTS.md vs CLAUDE.md — A Single Source of Truth Strategy to Prevent Drift, and a Practical Guide to Symlink Synchronization

I used to think, "They contain basically the same content anyway, so what's the harm in having two files?" If you're reading this right now, you might want to check your own repository. If you're using Claude Code alongside Codex CLI, or Claude Code together with Cursor, this story will feel familiar.

It happened when a team using Claude Code added Codex CLI to their workflow. They copied the existing CLAUDE.md to create AGENTS.md, and three days later during a code review, they discovered API response field names were inconsistently named userId and user_id. The naming convention had been updated in only one file, while the other quietly remained on the old version.

The core point is simple — the moment more than one rules file exists, drift begins. This article explores why drift occurs — a problem relevant to anyone using multiple agents together, whether in a multi-agent environment or using different agents like Claude Code and Cursor side by side — and how to permanently synchronize two files using symlinks.

Core Concepts

What's the Difference Between CLAUDE.md and AGENTS.md?

Both files are markdown documents that tell AI coding agents "how to behave in this project." They contain coding conventions, architectural rules, prohibited actions, testing methods, and similar content that agents read as context when starting a task. The purpose is identical, but the target agent differs.

AGENTS.md is becoming an industry standard after being donated to the Linux Foundation's Agentic AI Foundation (AAIF) in December 2025. AAIF, co-founded by Anthropic, OpenAI, and Block, has over 170 member companies as of April 2026, and more than 60,000 open-source projects have adopted AGENTS.md.

Drift: The phenomenon where two files that should contain the same rules diverge over time. It happens silently when only one side is updated, or when reviewers don't keep track of both files together.

Why Doesn't Claude Code Read AGENTS.md Directly?

Claude Code currently reads CLAUDE.md preferentially. The official documentation states that AGENTS.md is "optionally referenced," but honestly, it's unclear under what conditions it is referenced. It's hard to know for certain whether your Claude Code is actually reading AGENTS.md at any given moment. GitHub issues #6235 and #34235 show ongoing requests for native AGENTS.md support, so things may change in the future. But right now, there's a reality of having to manage both files together — which is why a single source of truth strategy is necessary.

Practical Application

Let's look at how this problem actually manifests and how it has been solved in real cases.

API Contract Breakdown: When Two Agents Read Different Files

One team applied Claude Code's agent team feature to a 1,700-line Telegram mini-app. The structure had three backend agents and one frontend agent working simultaneously. CLAUDE.md specified camelCase as the naming convention, but AGENTS.md was maintained separately and still contained the old rules.

The results were disastrous. As the backend and frontend agents referenced different files, API field names became a mix of userId and user_id. An even more insidious problem occurred after context compaction. As the context was compressed during long tasks, the detailed guidelines specified in the rules files disappeared, and agents began making ad-hoc decisions.

Context Compaction: The process by which an agent compresses its initial context as tasks grow longer. During this process, detailed guidelines from rules files can be lost.

There are two lessons from this case. First, rules must exist in one place. Second, expressions like "should use camelCase" are more likely to survive compaction when written with explicit force: "must use camelCase — never use snake_case."

The Fastest Solution: Creating a Single Source with Symlinks

This is the most practical and immediately applicable approach. The pattern is to designate AGENTS.md as the canonical source and convert all other files into symlinks pointing to it.

# 1. Move existing CLAUDE.md to AGENTS.md (AGENTS.md becomes the canonical source)
mv CLAUDE.md AGENTS.md
 
# 2. CLAUDE.md becomes a symlink to AGENTS.md
#    -s: creates a symbolic link (not a hard link)
ln -s AGENTS.md CLAUDE.md
 
# 3. Do the same for GitHub Copilot instructions
#    -f: force overwrite if file exists, -n: treat target symlink itself
mkdir -p .github
ln -sfn ../AGENTS.md .github/copilot-instructions.md
 
# 4. Do the same for Cursor rules
#    Note: .mdc is a Cursor-specific format and symlink behavior may not be fully supported
#    It is recommended to verify directly in Cursor that rules are being applied
mkdir -p .cursor/rules
ln -sfn ../../AGENTS.md .cursor/rules/main.mdc
 
# 5. Verify the symlinks are correctly connected
ls -la CLAUDE.md
# CLAUDE.md -> AGENTS.md  ✓

Since Git natively tracks symlinks, when teammates run clone or pull, they get the same symlink structure. Editing only AGENTS.md automatically propagates to Claude Code, Copilot, and Cursor.

On Windows: Creating symlinks on Windows requires administrator privileges or may have limited support. In this case, the CONTEXT.md pointer file pattern introduced below is a good alternative.

PrestaShop's CONTEXT.md Architecture: Accommodating Tool-Specific Differences

PrestaShop, the large open-source e-commerce framework, took a more sophisticated approach. The structure designates CONTEXT.md as the sole source of truth, while tool-specific files are maintained only as pointer files that reference CONTEXT.md.

<!-- AGENTS.md (pointer file) -->
# AI Agent Context
 
For coding conventions, architectural rules, and development guidelines for this project,
please refer to [CONTEXT.md](./CONTEXT.md).
 
## Quick Reference
- Build: `pnpm build`
- Test: `pnpm test`
- Detailed rules: See full content of [CONTEXT.md](./CONTEXT.md)

<!-- CLAUDE.md (pointer file) -->
# Claude Code Context
 
For the full project guidelines, please refer to [CONTEXT.md](./CONTEXT.md).
 
<!-- Add any Claude Code-specific configuration here if needed -->

This approach is appealing because it handles subtle differences between tools more flexibly than symlinks. Common rules go in CONTEXT.md, and tool-specific nuances go in each pointer file. I personally use a mix of both approaches — most files are connected via symlinks, and the pointer file pattern is used only when there are tool-specific behavioral differences like those in Claude Code. However, if pointer files are too thin, agents sometimes don't follow through to CONTEXT.md, so it's recommended to include at least the minimal core rules within the pointer files themselves.

PrestaShop adopted this strategy as a Core standard and rolled it out across all domains.

Writing More Effective AGENTS.md Files

I was surprised when I saw these research figures — an ETH Zurich study (2026) found that the presence of AGENTS.md reduced median runtime to task completion by 28.64% and output token consumption by 16.58% on SWE-bench-class tasks. However, there's a condition: only files written directly by humans showed these effects, and AGENTS.md files auto-generated by AI actually slightly reduced task success rates.

The intensity of rule expression matters when writing rules.

# ❌ Expressions easily ignored after context compaction
- should use camelCase for variables
- try to avoid direct database queries in controllers
- it would be nice to add tests for new features
 
# ✅ Expressions that survive with clear intensity
- **ALWAYS** use camelCase for variables — NEVER use snake_case
- **NEVER** write direct database queries in controllers; use the repository pattern
- **MUST** add unit tests for every new public method

Pros and Cons Analysis

Advantages

Disadvantages and Caveats

Context Token: The unit of text an AI model can process at once. If rules files become bloated, the token space available for actual coding tasks may decrease.

Most Common Mistakes in Practice

1. Creating files via copy-paste and leaving them alone — The content is identical at first, but drift begins the moment only one side is updated. It's safer to convert to symlinks or pointer files immediately after creation.
2. Delegating AGENTS.md writing to AI — Research shows that context files generated by AI can be counterproductive. Even if AI helps with a draft, the process of humans directly reviewing and refining it is important.
3. Writing rules with weak expressions — "Please use camelCase when possible" is easily ignored by agents after context compaction. Writing with clear intensity like "MUST use camelCase — NEVER use snake_case" is recommended.

Closing Thoughts

I lost half a day to this problem, but fixing it took less than five minutes. In a multi-agent environment, rules files must have a single source of truth, and the fastest way to achieve that is symlinks.

AGENTS.md is indeed becoming an industry standard under AAIF. But even now, as standardization is underway, drift is quietly happening somewhere in your repository. If you're already using multiple agents, planning to introduce a second agent to your team, or even just using Claude Code and Cursor together on your own — it might be worth checking your repository today.

Three steps you can start right now:

1. Assess the current state — Check how many of CLAUDE.md, AGENTS.md, .cursorrules, and .github/copilot-instructions.md exist in your repository. You can check quickly with ls -la CLAUDE.md AGENTS.md 2>/dev/null.
2. Designate a single source — Consolidate the most comprehensive file as AGENTS.md, and convert the rest to symlinks with ln -s AGENTS.md CLAUDE.md. On Windows, consider the CONTEXT.md pointer file pattern.
3. Strengthen rule expressions — Open AGENTS.md and find expressions like "should," "try to," and "nice to have," then replace them with "MUST," "ALWAYS," and "NEVER." These become rules that survive even when agents compress their context.

Next Article: Using AGENTS.md's hierarchical structure — how to split root files and subdirectory-level files to more precisely control agents in a monorepo environment

References

Official Documentation & Standards

• AGENTS.md Official Site | agents.md
• Linux Foundation: Agentic AI Foundation (AAIF) Announcement
• Anthropic: MCP Donation and AAIF Formation
• OpenAI: AAIF Co-Founding Announcement
• Claude Code GitHub Issue #6235: AGENTS.md Support Request
• Claude Code GitHub Issue #34235: Native AGENTS.md Support Request

Research

• arXiv: On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents
• arXiv: Agent READMEs — An Empirical Study of Context Files for Agentic Coding
• InfoQ: Reassessing the Value of AGENTS.md Files (2026.03)

Practical Cases & Guides

• PrestaShop GitHub Issue #41152: AI-Agnostic Context Strategy
• SSW.Rules: How to Symlink AGENTS.md to Claude Configuration
• Kaushik Gopal: How to Keep AGENTS.md Single Source in Sync
• tessl.io: The Rise of AGENTS.md as an Open Standard
• amattn.com: Combating Agent Drift with AGENTS.md and CLAUDE.md
• deployhq.com: Integrated Guide to CLAUDE.md, AGENTS.md, and Copilot Instructions
• SmartScope: Cross-Tool Management Guide for AGENTS.md (2026.02)
• layer5.io: AGENTS.md — One File to Guide Them All
• builder.io: Improving AI Code Quality with AGENTS.md