Share one rule set between Claude Code and Codex.

Guides

If you use both Claude Code and Codex, you have two instruction files that say nearly the same thing. Edit one and forget the other, and the engines quietly start working to different rules. The fix is a single source that renders both files.

Why not just copy or symlink

A copy drifts. A symlink, or a CLAUDE.md that imports AGENTS.md, keeps them identical, which is close but wrong in a few places. Claude Code can spawn subagents and can ask you to approve a guarded command; Codex cannot. Rules about delegation and approvals need different wording per engine, and an identical file gets one of them wrong.

One source with variants

Give every rule an id. Write the shared rules once. Where an engine needs its own wording, add a variant for that engine. This is how the CommonRig rule source reads:

@default-targets claude codex

@rule GIT-APPROVAL
- For a guarded operation, make the result reviewable, then use the
  Claude approval prompt. A denied operation stays denied.

@rule GIT-APPROVAL@codex
- Codex has no ask-permission gate. If policy denies an operation, leave
  the prepared result for the owner and report the exact limitation.

The generator renders the plain rule for Claude and the @codex variant for Codex, puts the result in each engine's file and stamps it as generated, so a direct edit is visibly in the wrong place.

Render, install and check

  • Build both files into a scratch folder and read them before installing anything.
  • Install with a plan you can review and a way to roll back. Keep your original files until the generated ones have proved themselves.
  • Check for drift in CI or a pre-push hook: render again and fail if the installed files differ.
  • Lint the source: no dates in rule bodies, no retired markers, and a size budget of about 3,500 estimated tokens per engine.

With the kit this is python tools/gen.py build, install, check and lint. Without it, a short script that concatenates shared rules and per-engine files gets you most of the way; the drift check is the part people skip and later miss.

Hooks too

Hooks follow the same idea. Keep one policy file that both engines' hooks read, so a banned git operation is banned in both. The engines register hooks differently (Claude Code in settings.json, Codex in its hooks.json), so expect two small config files pointing at the same scripts.

Check your own files

Paste your CLAUDE.md or AGENTS.md into the free footprint scorer, or get the free sample and run rig doctor --lite locally. The hosted doctor check is A$0.50 a run and scores the whole setup, hooks included. The kit (A$10 once) has the rule source, generator, hooks and protocols these guides describe.

More guides