Separate Shared Instructions From Product-Specific Ones

A repository can serve several agents, but each product has its own rules for searching and prioritizing files. Shared engineering policy can be duplicated deliberately, while specific capabilities can't be declared universal.

Where each product looks for instructions is worth keeping in view.

Product · Main project surface · Local detail · Global surface

• Codex - AGENTS.md in the repository; Nested AGENTS.md or AGENTS.override.md, closer instructions win; ~/.codex/AGENTS.md
• Claude Code - CLAUDE.md or .claude/CLAUDE.md; Child CLAUDE.md load as work proceeds; path rules in .claude/rules/; ~/.claude/CLAUDE.md
• Cursor - .cursor/rules/*.mdc or a root AGENTS.md; Globs in MDC and nested AGENTS.md; User Rules in Customize

A working strategy for a shared repository comes down to a few steps. Make a short team document canonical - verification commands, architectural boundaries, bans, the done criterion. Carry those facts into AGENTS.md, CLAUDE.md, and, if needed, a Cursor rule. Add product syntax only to the relevant file. And change the instructions together with the code that made a rule obsolete.

Two boundaries are fundamental here. The first is about compatibility.

Don't rely on accidental compatibility. Cursor officially supports AGENTS.md, Claude Code documents CLAUDE.md, Codex documents AGENTS.md. If the team uses three products, explicit adapters are safer than the guess that one file will be read by all.

The second is about what an instruction isn't.

An instruction is not enforcement. It enters context and influences the model's decision, but doesn't guarantee it. A ban on writing to production, a mandatory security scan, or a schema format must have a technical control: permission, sandbox, hook, CI, or server-side authorization.

The split is clear. Now let's write the instruction file itself - and the best guide here is an operational README, not a wish list.