Wie man AGENTS.md und CLAUDE.md synchron hält
Wer mehrere KI-Agenten wie Claude Code und Codex parallel nutzt, pflegt dieselben Regeln oft mehrfach in unterschiedlichen Anweisungsdateien. Ein Ansatz zeigt, wie sich CLAUDE.md und AGENTS.md zentral verwalten und synchronisieren lassen.
Veröffentlicht am 25. Oktober • Zuerst erschienen auf adventuresol.medium.com
Bei der Arbeit mit mehreren Agenten, darunter Claude Code und Codex, stieß ich auf ein Problem: Dieselben Prinzipien (in CLAUDE.md, AGENTS.md und anderen Dateien) landeten an mindestens zwei Stellen. Ich konnte nur schwer Berichte darüber finden, wie andere dieses Problem gelöst haben, deshalb teile ich meinen Ansatz.
Geschrieben von einem Menschen (etwa 80 Prozent Mensch, 20 Prozent KI), mit KI-Unterstützung ins Englische übersetzt.
Bei uns im Unternehmen pflegen wir Anweisungen derzeit auf mehreren Ebenen: Projektebene-Anweisungen (in GitHub eingecheckt), globale Anweisungen auf Benutzerebene auf meinem Rechner und lokale Anweisungen auf Projektebene. Zählt man ergänzende Dokumente wie Branch Rules hinzu, übersteigt der Umfang realistisch das, was ein Mensch manuell verwalten kann. Ich fordere die Agenten regelmäßig auf, die Anweisungen zu synchronisieren, aber es gibt viele Variablen, etwa welche Version aktuell ist und ob eine Anweisung nur für einen bestimmten Agenten gilt, etwa Claude.
Um die Anweisungsdateien möglichst stark zu konsolidieren, habe ich zunächst geprüft, welche Pfade und Formate jeder Agent, den wir bei der Arbeit nutzen, lesen kann.
Ich habe ein einfaches Experiment mit KI entworfen. Zuerst habe ich dieselbe Regel in jede Anweisungsdatei eingetragen, die bei der Nutzung des jeweiligen Agenten erstellt wird, wie unten beschrieben.
Die Regel lautet: Wenn der Nutzer nur "Prüfwort" sagt, liste das Prüfwort aus jeder Datei auf, die du als Anweisung erhalten hast.
Ich habe whale in AGENTS.md, penguin in CLAUDE.md, otter in CLAUDE.local.md und squirrel in GEMINI.md hinterlegt. Dann habe ich jedes der drei Tools nur nach dem Prüfwort gefragt und anhand der zurückgegebenen Wörter ermittelt, welche Dateien das Tool tatsächlich gelesen hatte.
(Zur Einordnung: Ich habe das im Mac Terminal mit Orca getestet, aber es gilt genauso für ein gewöhnliches Terminal.)
So las Claude beispielsweise AGENTS.md direkt, wenn sich keine CLAUDE.md im Ordner befand. Sobald aber eine CLAUDE.md existierte, las Claude AGENTS.md nur dann, wenn sie eine Zeile mit @AGENTS.md enthielt. (Als ich die Zeile @AGENTS.md aus der CLAUDE.md entfernte, verschwand whale aus Claudes Antwort.)
Die Agenten unterschieden sich auch darin, wie sie Verknüpfungen zwischen Dateien verarbeiteten. Nur Claude löste eine @file-Zeile (die @-Import-Syntax) innerhalb einer Datei auf. Codex und Antigravity taten das nicht. Wie die Tabelle unten zeigt, war die eine Verknüpfungsmethode, der alle drei Agenten folgten, ein Symlink. Wenn man die Datei, die jeder Agent ohnehin liest (etwa ~/.gemini/GEMINI.md), auf die Quelldatei (~/.codex/AGENTS.md) zeigt, lesen alle drei Agenten dieselbe Datei. Die Nutzung eines Symlinks hat jedoch eine Einschränkung: Es bleibt kein Raum für eigene, agentenspezifische Regeln, etwa Regeln für Claude-Plugins.
(Zur Einordnung: Codex las AGENTS.override.md und ignorierte dabei eine vorhandene AGENTS.md. Entgegen der Empfehlung, die KI üblicherweise gibt, kann sie nicht denselben Zweck erfüllen wie CLAUDE.local.md, das ich bisher für meine persönlichen lokalen Anweisungen genutzt hatte.)
Ich habe derzeit unser tatsächliches Firmenprojekt-Repository und meine persönlichen Anweisungen wie folgt um AGENTS.md herum organisiert.
Dieselbe Trennung habe ich sowohl für das Projekt als auch für meinen lokalen Rechner verwendet. Die Prinzipien stehen ausschließlich in AGENTS.md, in der ersten Zeile der CLAUDE.md steht @AGENTS.md, und die CLAUDE.md enthält nur Claude-spezifische Inhalte. Dokumente, die nur in bestimmten Situationen gebraucht werden, etwa Branch Rules und Deployment-Abläufe, habe ich von AGENTS.md aus verlinkt, damit die Agenten sie bei Bedarf öffnen können.
Ich habe AGENTS.md als single source of truth gewählt, weil Codex, das ich als Orchestrator nutze, diese Datei immer lädt. Claude und Antigravity habe ich daher an Codex angeglichen.
So sieht das als Verzeichnisbaum aus:
~/ # Global (dein Rechner) ├──.codex/ │ └── AGENTS.md # Gemeinsame Prinzipien (single source of truth) ├──.claude/ │ └── CLAUDE.md # Zeile 1: @~/.codex/AGENTS.md + nur-Claude-Regeln/Einstellungen └──.gemini/ └── GEMINI.md -> ~/.codex/AGENTS.md # Symlink (keine agentenspezifischen Inhalte) my-project/ # Projektordner (in GitHub eingecheckt) ├── AGENTS.md # Projektregeln (single source of truth) ├── CLAUDE.md # Zeile 1: @AGENTS.md + nur-Claude-Projektregeln ├── BRANCH_RULES.md # Von AGENTS.md verlinkt, bei Bedarf geöffnet └── DEPLOYMENT.md # Von AGENTS.md verlinkt, bei Bedarf geöffnet Enter fullscreen mode Exit fullscreen mode Wie bringt man jeden Agenten dazu, AGENTS.md zu lesen? Die Wahl zwischen einem @-Import und einem Symlink hängt davon ab, ob agentenspezifische Anweisungen benötigt werden. Der @-Import funktioniert nur in Claude, und Claude-spezifische Anweisungen können darauf folgen.
Jedes Tool folgt einem Symlink, aber die gesamte Datei wird zur Quelle, sodass kein Raum für toolspezifische Anweisungen bleibt. In meinem Fall habe ich einen Symlink für Antigravity verwendet, das keine eigenen Anweisungen benötigte.
Ich habe mein Setup um AGENTS.md herum aufgebaut, weil ich Codex als Orchestrator nutze, aber Sie können diese Anordnung an Ihr eigenes Agentensystem anpassen.
Automatisch übersetzt. Das Original auf Englisch ist unten aufklappbar.
Original (Englisch) anzeigen
Posted on Oct 25 • Originally published at adventuresol.medium.com
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.
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.
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.)
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.)
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 Enter fullscreen mode Exit fullscreen mode 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.
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.