Use AGENTS.md or CLAUDE.md for instructions the named agent should load automatically, such as commands and repository-wide working conventions. Use ADRs or typed decision records for durable engineering rationale, alternatives, consequences and lifecycle. Link the instruction file to the decision system instead of duplicating every decision into it.
The formats have different authority
OpenAI describes AGENTS.md as persistent project guidance that Codex reads before work. Anthropic describes CLAUDE.md as project instructions loaded into Claude Code sessions and explicitly notes that the content is context rather than enforced configuration. ADRs, by contrast, are records of significant choices and their rationale.
All three can be Markdown in the repository, but identical storage does not give them identical meaning. One instructs an agent interface; one preserves a project decision for any reader.
A practical division of responsibility
Keep universal operational guidance in agent instruction files. Store decisions once in a vendor-neutral record. Tell agents how to discover that record and which situations require a query.
- AGENTS.md: run these tests; do not modify generated files; query decisions before changing product behaviour.
- CLAUDE.md: equivalent Claude-specific entry guidance where required by that tool.
- ADR or decision record: users remain recoverable for 30 days, with rationale, consequences and lifecycle.
- CI policy: prove that an objectively checkable part of the accepted decision still holds.
Avoid duplicated policy
Copying the same decision into several vendor files creates several sources of truth. A later update can change one and leave the others stale. Prefer a short pointer from each supported agent entry point to the common repository record.
Duplication may still be appropriate for a tiny, universal safety rule, but it should be generated or tested against the authoritative record where possible.
Choose by the question being answered
If the question is 'How should this agent work in this repository?', use its instruction mechanism. If the question is 'What did the team decide and why?', use the decision record. If the question is 'Does this patch still comply?', use a deterministic check. Most mature repositories need all three layers.