Share engineering decisions across Cursor, Claude Code and Codex by keeping the authoritative records in a vendor-neutral repository format. Use AGENTS.md, CLAUDE.md or editor-specific rules as thin adapters that tell each agent when and how to query the same read-only decision source.
Do not maintain three copies of the truth
Each agent supports its own instruction conventions, but duplicating decisions across those files creates drift. A rule may be updated for one agent and remain stale for another. Long instruction files also lose lifecycle, rationale and relationships between decisions.
Treat vendor files as entry points. They can contain commands, repository boundaries and a concise instruction to consult the common decision store before planning relevant work.
A portable arrangement
Store accepted and rejected decisions in reviewed Markdown with a machine-readable schema. Expose deterministic discovery through a local CLI or read-only MCP server. Configure every supported agent to use that interface and require citations in plans or pull-request summaries.
# Agent entry point
Before changing architecture or product behaviour:
1. Query the repository decision record.
2. Cite relevant decision IDs in the plan.
3. Report missing coverage rather than guessing.Keep adapters deliberately small
The adapter should explain how to reach authority, not reproduce authority. Repository-wide conventions may remain in each tool's expected file, while historical rationale and domain-specific constraints stay in the common record.
- One canonical record reviewed with code.
- Thin tool-specific discovery instructions.
- The same query and citations across agents.
- One CI path for machine-checkable consequences.
Verify portability
Start clean sessions in each agent and ask the same architecture question at the same commit. Confirm that all three discover the same decision IDs and distinguish accepted, proposed and superseded records. Differences reveal adapter or retrieval problems before they become code drift.