Answers
How do you keep CLAUDE.md, AGENTS.md and GEMINI.md in sync?
Not by copying. Copies drift the first time a rule changes in one file and not in the others, and the tool that reads the stale one keeps following the dead rule with no error. Inside one repository the files can be made into one: CLAUDE.md can import AGENTS.md, and Gemini CLI's context.fileName setting can point it at AGENTS.md. That puts the coding agents on one text, and it is still a file: it does not say who decided a line, when it stops being true or whether an assistant added it in a session, and it does not reach the tool that does not read the repository. A rule stays in sync when it lives once, outside every file, where someone sees it and approves it, and every tool reads it from there. Arroway is that place: each rule with who approved it and when it ends, read by every connected assistant before it acts. The install page is the first step.
Last updated October 6, 2026
Why three files drift
Each tool reads its own file: CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, AGENTS.md for the agents that follow that convention. A team using three tools ends up with three files that start as the same text. The first change goes into the file of whoever made it. From then on one assistant follows the new rule, another follows the old one, and a third has never heard of it. Nothing fails. The disagreement shows up weeks later, as two assistants giving the team two answers to the same question.
What actually holds
Inside one repository the files can be made into one: CLAUDE.md can import AGENTS.md, and Gemini CLI's context.fileName setting can point it at AGENTS.md. That changes how many files there are, not what they are: text every session loads, that an assistant can write to, with no line saying who approved it or when it ends. And it does not reach a rule about the business — a price, a client constraint, a policy — because the chat assistant, the agent in another repository and the colleague without Git do not read any of the files. What holds is the rule living once, where the team sees it, approves it and retires it, and every tool reading it from there.
When to use Arroway
Use Arroway when the same rule has to reach several tools, change in one place and stay visible to the team that follows it. The rule is recorded once, with who approved it and the condition that ends it; a replacement names the rule it retires; every connected tool reads the current version at the start of a session. What holds goes there, about the code or about the business, and not into an instruction file where an assistant can change it without anyone seeing. It does not fix files that already disagree: it gives you the place where the rule should have lived. The first step is the install page.
When not to do this
Do not set this up for a solo project with one assistant: a single file already is the single source. And do not use the import trick as the fix for a team: it reduces the number of files without telling anyone who decided a line or when it stops being true. If the only problem is two files that you control, a symlink is enough.
A common error: syncing by script
A script that copies CLAUDE.md into GEMINI.md on every commit feels like a fix, until the day someone edits the copy. The script overwrites the edit, or the edit survives and the two disagree again, and in both cases nobody sees it. Syncing text keeps the files equal; it does not decide which wording is right, and a rule nobody approved is spread to every tool at once.
What it looks like in practice
A three-person product team uses Claude Code, Gemini CLI and Cursor. In September they wrote the same ten rules in CLAUDE.md, GEMINI.md and a Cursor rules file. In October they decide that every database change needs a second reviewer. Maya adds the line to CLAUDE.md the same day. GEMINI.md is untouched; the Cursor rule never gets the line. Two weeks later a migration goes through with one reviewer and nobody can say which assistant told them it was fine. They move the rule into Arroway with Maya's name, replacing the older one-reviewer rule. The three tools read the same current rule at the start of every session, and the history shows when it changed and who changed it. Nothing the team relies on is left in the three files.
Getting three instruction files to stop disagreeing, in six steps
- Put the three files side by side and diff them. In the example team, the ten rules written in September should be identical, and every line that is not is a row to resolve. Count the differences; the number is your starting point.
- For each difference, find the person who made the change and ask which wording the team means. Do not choose by file: CLAUDE.md is not more right than GEMINI.md because it was edited more recently.
- Inside the repository, reduce the number of texts if the tools allow it: import AGENTS.md from CLAUDE.md and point Gemini CLI’s context.fileName at AGENTS.md. That makes the coding agents read one text, and nothing more than that.
- Decide which rules are about the code and which are decisions of the team. “Every database change needs a second reviewer” is a team decision, and it belongs in the place every tool reads and the owner approves, not in the shared file.
- Record each team decision once, with who approved it and what ends it. When the one-reviewer rule is replaced, the new one names the old one, and the next session of every tool opens with the current version.
- Add a check to the habit, not to the files: when someone proposes a rule from a session, the question is whether it already exists. Run the diff again after a month. If the files are diverging again, rules are still being added to them directly.
Questions people ask about this
- Can a symlink or an import keep the files in sync?
- Inside one repository, yes: an import line or a symlink makes the files one. It does not reach tools that do not read the repository, and it cannot say whether a line still stands.
- Where should a rule that every tool follows live?
- Outside every instruction file, in one place where someone sees it and approves it. In Arroway each rule carries who approved it and when it ends, and every connected tool reads the current version before it acts, whether the rule is about the code or about the business.
- How do I try Arroway?
- Install it in the tool you already use — the install page has one route for Claude, ChatGPT, Codex, Cursor or any MCP tool — and sign in when the tool asks. From then on, sessions open by reading the project and close by recording what was decided.
Where this is verifiable
Gemini CLI documentation on GEMINI.md and the context.fileName setting (geminicli.com/docs/cli/gemini-md), read on 6 October 2026; the Claude Code memory documentation, read on 29 September 2026. Each product is described only as its documentation describes it on those dates. Product documentation on this site (How it works, Install), the answers on the same rule written in four prompts and on whether Claude Code reads AGENTS.md, and the sanction, supersession and expiry-condition rules in the sanctioned product spec. Everything described here about Arroway is behaviour the tools apply today, not roadmap. The team in the example is illustrative.
https://www.arroway.app/en/answers/one-team-three-instruction-files-and-they-drift