One Rulebook for Two Agents

You change a writing rule, then switch agents. Did you update the other copy? Claude Code and Codex can read the same user-level rules through their own entry points. Keep the shared rules in one file and each codebase's rules in its repository.

My shared file is ~/.agents/AGENTS.md. Claude Code reaches it through an import in ~/.claude/CLAUDE.md:

@~/.agents/AGENTS.md

The Claude Code memory docs describe this import syntax. Codex reaches the same file through a symbolic link at ~/.codex/AGENTS.md:

readlink ~/.codex/AGENTS.md

It prints ../.agents/AGENTS.md.

The header tells me to edit the shared file. Each agent's entry point holds only a pointer to it.

Keep rules that apply across projects here: writing style, authorization boundaries, review expectations, and how to retrieve documentation. For example:

Use plain English. State the result first.
Saved permissions and available tools do not authorize a task.
Verify claims against current source before publishing them.
Preserve unrelated changes in the working tree.

Put detailed procedures in linked documents or skills. If a rule applies to only one harness, the software running the agent, put it in that harness's file or explain the difference beside the shared rule.

For example, RTK filters shell output in my setup. A Claude Code hook adds its prefix automatically. I have no equivalent RTK hook configured in Codex, so Codex adds the prefix itself:

rtk git status

Each repository's AGENTS.md holds its architecture, privacy rules, checks, and release steps. Codex discovers these files along the path from the project root to the working directory. In this repository, Claude Code imports the same file through CLAUDE.md:

@AGENTS.md

The Codex instruction guide explains discovery and overrides. A user-level AGENTS.override.md takes precedence over AGENTS.md. If you set CODEX_HOME, use that directory instead of the default ~/.codex.

These files tell the agent how to work. You still need separate controls to enforce tool permissions.

These commands use a POSIX shell. Before running them, merge any existing rules into the shared file and move the old entry-point files aside. Check for existing symbolic links too, including links whose targets are missing.

1. Create all 3 folders:

   mkdir -p ~/.agents ~/.claude ~/.codex

2. Write your shared rules in ~/.agents/AGENTS.md. Add a header that names it as the file to edit.

3. Create the Claude Code pointer. The subshell's noclobber setting refuses to overwrite an existing regular file:

   (set -C; printf '@~/.agents/AGENTS.md\n' > ~/.claude/CLAUDE.md)

4. Create the Codex pointer. Run this only after checking that the destination is absent:

   ln -s ../.agents/AGENTS.md ~/.codex/AGENTS.md

5. Check both pointers and confirm the shared file is readable:

   cat ~/.claude/CLAUDE.md
   readlink ~/.codex/AGENTS.md
   head -n 5 ~/.codex/AGENTS.md

6. Start a new session in each agent. Ask it which instruction files it loaded and check for a distinctive rule from your shared file.

With one harness, its normal user-level file may be enough. For a team, keep shared project rules in the repository because teammates do not share your home directory. Keep personal preferences in your user-level file.

Use harness-specific files for rules that only one agent needs. After changing a rule, start new sessions and check what each loaded. For an overview of instruction-file organization, see AI Hero's A Complete Guide to AGENTS.md.