One set of rules for every agent

CLAUDE.md, AGENTS.md, GEMINI.md — the same rules, written three times, drifting apart

You tell Claude Code to run the tests with -race. A week later Codex runs them without it, because that rule went into CLAUDE.md and Codex reads AGENTS.md. Every agent reads its own file, and a rule given to one never reaches the others.

There are two separate problems here. One is a repository that several agents work in. The other is your own rules, the ones you carry across every project, which live in a different file per agent in your home directory.

Which file each agent reads

Cursor has no truly global file: cursor-agent finds .cursor/rules by walking up from the project, so ~/.cursor/rules (where its own "User Rule" goes) reaches projects under your home directory and no others, and the IDE keeps your user rules in its settings on the server. Windsurf keeps them in ~/.codeium/windsurf/memories/global_rules.md.

In one repository: make AGENTS.md the source

AGENTS.md is the name most agents already read, so keep the rules there and point the rest at it.

Claude Code. A CLAUDE.md with a single import line reads the shared file, and works whether or not your version picks up AGENTS.md on its own:

@AGENTS.md

Claude-specific lines can go under it. Deleting CLAUDE.md also works on 2.1.277 and later, since Claude Code then reads AGENTS.md itself, but the import is the version that does not depend on which build a teammate runs.

Gemini CLI. Tell it which context files to load, in .gemini/settings.json:

{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

A symlink (ln -s AGENTS.md CLAUDE.md) is the other common answer. It works on macOS and Linux, and turns into a plain text file with a path in it on a Windows checkout without symlink support.

Your own rules, across every agent

The global files are where the standing preferences go: how you want commits written, what never to run without asking, the test flag you always want. They are also the ones that drift, because nobody opens ~/.gemini/GEMINI.md to add the rule they just gave Claude Code.

deja-vu keeps them in one file and copies it out. Write the rules in ~/.config/deja/rules.md, then:

$ deja rules
rules: ~/.config/deja/rules.md, 12 lines, 640 bytes
  claude-code  missing   ~/.claude/CLAUDE.md
  codex        in sync   ~/.codex/AGENTS.md
  opencode     stale     ~/.config/opencode/AGENTS.md
  gemini       missing   ~/.gemini/GEMINI.md
run `deja rules sync` to bring them in line

$ deja rules sync

sync writes the rules into each file as a block between <!-- deja rules:start --> and <!-- deja rules:end --> and leaves everything else in the file alone. Where an agent reads a whole folder (Cline, Roo, Continue, Kiro, TRAE IDE, Cursor) the block goes into a deja-rules file of its own there. Where it loads only the first of several files, the block goes into the one already loaded, so a CLAUDE.md that Kilo, opencode or Muse reads is not hidden behind a new AGENTS.md. Hermes gets the block only in a SOUL.md it already made, since that file is also its identity, and OpenClaw only in a workspace AGENTS.md it already seeded. Edit rules.md and sync again; empty it and sync takes the blocks back out. It only writes to agents deja is installed for, and only to files it has verified the agent reads. An agent whose global file it does not know is listed and left alone rather than guessed at. deja doctor names any agent whose copy has fallen behind.

The file is capped at 8 KB. Every agent reads it on every session, so it is worth keeping to what you would say to a new colleague on day one — what belongs in a rules file covers the rest.

Finding the rules you keep repeating

Most people have never written their rules down; they say them again every few sessions. Those corrections are already in the transcripts. deja rules candidates lists the turns where you corrected an agent, across every tool on the machine, each with the session it came from:

$ deja rules candidates --since 90d
#14 codex 2026-09-03 deja:9f2c41ab
user: no, run it with -race, always
before it, the agent: Tests pass: ok  ./internal/index 1.8s
...

deja does not group them itself, because the same rule comes back in different words each time: three word-based groupings over one machine's 236 candidates put no real rule in their top ten. Ask your agent to suggest your rules instead. The deja skill has it run the command, group the list into rules stated in at least two sessions, cite the turns behind each one, and stop. Nothing is written to rules.md until you pick. On that same list a frontier model found ten real rules out of ten; a small local model invented candidate numbers, so use a strong one for this step.

When CLAUDE.md gets too long · Switching agents · When the same wall comes back

Found this useful? Star deja-vu on GitHub.