How Do You Keep Instruction Files (AGENTS.md and CLAUDE.md) in Sync?

cacastopia — Sun, 25 Oct 2026 17:36:15 +0000

While using multiple agents, including Claude Code and Codex, I ran into a problem: the same principles (in CLAUDE.md, AGENTS.md, and other files) ended up spread across at least two places.
I had trouble finding accounts of how others had handled this problem, so I'm sharing my approach.

Written by a human (roughly 80% human, 20% AI). translated into English with AI help.

Background: The Need for a Single Source of Truth for Instructions

At work, we currently maintain instructions at several scopes: project-level instructions (committed to GitHub), user-level global instructions on my machine, and local project-level instructions. Including supporting documents such as Branch Rule, the volume realistically exceeds what a person can manage manually.
I periodically prompt the agents to "sync the instructions," but there are many variables, including which version is current and whether an instruction applies only to a specific agent, such as Claude.

To consolidate the instruction files as much as possible, I first checked which paths and formats every agent we use at work could read.

Test: Which Instruction Files Do Claude Code, Codex, and Antigravity Miss?

I designed a simple experiment with AI. First, I put the same rule in every instruction file created when using each agent, as shown below.

The rule: when the user says only "check words" (확인단어), list the check word from every file you received as instructions.

I put whale in AGENTS.md, penguin in CLAUDE.md, otter in CLAUDE.local.md, and squirrel in GEMINI.md. I asked each of the three tools only "check words" and used the returned words to determine which files the tool had actually read.

(For reference, I tested this in Mac Terminal using Orca, but it also applies to a regular terminal.)

Results: Each Tool Read Different Files and Supported Different Ways of Connecting Them

For example, Claude read AGENTS.md directly when there was no CLAUDE.md in the folder. However, when CLAUDE.mdexisted, Claude read AGENTS.md only if it contained an @AGENTS.md line. (When I removed the @AGENTS.md line from CLAUDE.md, 'whale' disappeared from Claude's response.)

The agents also differed in how they followed links between files. Only Claude expanded an @file line (the @ import syntax) inside a file. Codex and Antigravity did not. As the table below shows, the one linking method all three agents followed was a symlink.
If you point the file each agent already reads (e.g., ~/.gemini/GEMINI.md) at the source (~/.codex/AGENTS.md), all three agents read the same file. However, using a symlink has a limitation: it leaves no room for separate rules specific to each agent, such as rules for Claude plugins.

(For reference, Codex read AGENTS.override.md while ignoring an existing AGENTS.md. Contrary to the guidance AI usually gives, it cannot serve the same purpose as CLAUDE.local.md, which I had been using for personal local instructions.)

Approach: Connecting Everything Around AGENTS.md

I've currently organized our actual company project repository and my personal instructions around AGENTS.md as follows.

I used the same separation for both the project and my local computer. I put principles only in AGENTS.md, added @AGENTS.md on the first line of CLAUDE.md, and kept only Claude-specific content in CLAUDE.md. I linked documents needed only in specific situations, such as branch rules and deployment procedures, from AGENTS.md so the agents could open them when needed.

I chose AGENTS.md as the single source of truth because Codex, which I use as the orchestrator, always loads it. I therefore aligned Claude and Antigravity with Codex.

Here's what it looks like as a directory tree:

~/                                    # Global (your machine)
├── .codex/
│   └── AGENTS.md                     # Shared principles (single source of truth)
├── .claude/
│   └── CLAUDE.md                     # Line 1: @~/.codex/AGENTS.md + Claude-only rules/settings
└── .gemini/
    └── GEMINI.md -> ~/.codex/AGENTS.md   # Symlink (no agent-specific content)

my-project/                           # Project folder (committed to GitHub)
├── AGENTS.md                         # Project rules (single source of truth)
├── CLAUDE.md                         # Line 1: @AGENTS.md + Claude-only project rules
├── BRANCH_RULES.md                   # Linked from AGENTS.md, opened on demand
└── DEPLOYMENT.md                     # Linked from AGENTS.md, opened on demand

How Do You Make Every Agent Read AGENTS.md?

The choice between an @ import and a symlink depends on whether agent-specific instructions are needed. The @ import works only in Claude, and Claude-specific instructions can follow it.

Every tool follows a symlink, but the whole file becomes the source, leaving no room for tool-specific instructions. In my case, I applied a symlink to Antigravity, which did not need its own instructions.

In Short: Principles Live Only in AGENTS.md. Put @AGENTS.md in CLAUDE.md.

I centered my setup on AGENTS.md because I use Codex as the orchestrator, but you can adapt this arrangement to fit your own agent system.